Introduction to Crystal Reports Development

  • About this online help
  • Business Objects information resources
  • Acknowledgements

Business Objects
http://www.businessobjects.com/
Support services
http://www.businessobjects.com/services/support/


About this online help

This online help includes technical information on the development tools included with Crystal Reports that allow you to integrate reporting into your application. The guide covers the Report Designer Component. It also contains tutorials and samples that will further aid you with adding the power of Crystal Reports to your application.

Crystal Reports is designed to work with your database to help you analyze and interpret important information. Crystal Reports makes it easy to create simple reports; it also has the comprehensive tools you need to produce complex or specialized reports.

Create any report you can imagine

Crystal Reports is designed to produce the report you want from virtually any data source. Built-in report wizards and experts guide you step by step through building reports and completing common reporting tasks. Formulas, cross-tabs, subreports, and conditional formatting help make sense of data and help you uncover important relationships that might otherwise be hidden. Geographic maps and charts communicate information visually when words and numbers are simply not enough.

Extend reporting to the Web

The flexibility of Crystal Reports doesn't end with creating reports—your reports can be published in a variety of formats including Microsoft® Word and Excel, email, and even over the Web. Advanced Web reporting lets other members of your workgroup view and update shared reports inside their web browser.

Incorporate reports into applications

Application and web developers can save time and meet the needs of their users by integrating the report processing power of Crystal Reports into their database applications. Support for most popular development languages makes it easy to add reporting to any application.

Whether it's the web master in IT, the promotion manager in marketing, the database administrator in finance, or the CEO, Crystal Reports is a powerful tool designed to help everyone analyze and interpret the information that's important to them.

Business Objects information resources

For more information and assistance, see Business Objects Information Resources. This appendix describes the Business Objects documentation, customer support, training, and consulting services, with links to online resources.


Acknowledgements

Patents

Business Objects owns the following U.S. patents, which may cover products that are offered and sold by Business Objects: 5,555,403, 6,247,008 B1, 6,578,027 B2, 6,490,593 and 6,289,352.

Trademarks

Business Objects, the Business Objects logo, Crystal Reports, and Crystal Enterprise are trademarks or registered trademarks of Business Objects SA or its affiliated companies in the United States and other countries. All other names mentioned herein may be trademarks of their respective owners.

Copyright

Copyright © 2004 Business Objects. All rights reserved.


Crystal Reports Key Features of the RDC

This section highlights the key changes made for developers in previous versions of Crystal Reports, and it points you to further information.

Click the appropriate link to jump to that section:

  • Summary of key features of the Report Designer Component
  • A closer look at some of the key features


Summary of key features of the Report Designer Component

With each version, key features are added to the Report Designer Component. These key features include:

  • Embed a Crystal Reports Designer in your application
  • Create and modify Report Alerts
  • Re-import subreports
  • Summarize on hierarchical data
  • Report Variables
  • Set OLE object location
  • Save preview picture
  • Charts
  • Creating reports at runtime using code
  • Cross-Tab reports
  • ADO and OLEDB tables
  • Database Expert
  • Select Distinct Records
  • Selecting & editing embedded fields
  • Report object events
  • Formatting
  • Formulas
  • Grouping
  • IDE
  • Complete XML support for the Web
  • Improved interactivity with parameters
  • Display web reports independent of server location
  • Extend reporting abilities with additional applications
  • Additional Web reporting features


Embed a Crystal Reports Designer in your application

Your users can design or edit reports at runtime with the Embeddable Designer. This easy-to-use ActiveX control provides the full power of Crystal Reports to your application. The control is placed on a form, or in a container within the form, and displays a new or existing report in design mode. This presents the user with an interactive environment in which to design or edit the report. The Embeddable Designer allows users to:

  • add data sources
  • add database fields
  • create and add formulas
  • create and add parameters
  • group data
  • summarize data
  • add charts
  • add subreports
  • add special fields
  • format fields and sections

Note: For more information see Embeddable Crystal Reports Designer Control Object Model, and Programming the Embeddable Crystal Reports Designer Control.


Create and modify Report Alerts

Report Alerts are custom messages created in the Crystal Reports Designer, the Report Designer Component, or the Embeddable Crystal Reports Designer Control. Report Alerts may indicate action to be taken by the user or information about report data. For more information see Report Alerts in the Crystal Reports User's Guide.

Two collections and two objects have been added to the RDC object model to allow you to create, modify, and monitor Report Alerts at runtime. These collections and objects are:

  • ReportAlerts Collection
  • ReportAlert Object
  • ReportAlertInstances Collection
  • ReportAlertInstance Object


Re-import subreports

Subreports can be newly created in the main report or imported from an existing report file. If the subreport is imported from an existing report file, it can be re-imported at runtime using the ReImportSubreport method. When previewed, printed, or exported, a re-imported subreport will reflect all changes made to the formatting, grouping, and structure of the existing report file.

For more information see the ReImportSubreport Method (SubreportObject Object).


Summarize on hierarchical data

Make large, complex data sets easier to understand than ever by taking advantage of the ability to create Subtotals, Grand Totals, and Summary fields for hierarchical groups: to do so, select the "Sum across hierarchy" option, which is available in the Insert Subtotal, Insert Summary, Insert Grand Total, and Change Summary dialog boxes.

Hierarchical summaries can be enabled at runtime through the HierarchicalSummaryType property. This property is available in the following two objects:

  • RunningTotalFieldDefinition Object
  • SummaryFieldDefinition Object


Report Variables

Certain events, such as the OnSectionFormat event, may get fired more than once in a section. For example, a Details section may fire multiple times for a given record if the program is performing "Keep Section Together" calculations for the report. When you use VB variables that are supposed to increment once for each record (for example, when you calculate a running total), you can have problems maintaining state with these multiple firings.

To prevent these problems, the RDC enables you to declare Report Variables. Report Variables are Crystal variables that you can use in your VB code. Report Variables "understand" what's going on in the report and they increment appropriately. This enables you to do more of your coding in VB and still get the results you expect. For more information, see Using Report Variables.

To support report variables, the methods AddReportVariable, GetReportVariableValue and SetReportVariableValue have been added to the Report object.


Set OLE object location

You can set the location of an OLE object at runtime using the method, SetOleLocation, under the OleObject object. This also enables you to change an OLE object to point to different files at run time including image files.

The method SetFormattedPicture is still supported. However, if you use both SetFormattedPicture and SetOleLocation, SetFormattedPicture overrides SetOleLocation.

Also note that if an OLE object is in the Detail section and you call SetOleLocation in the OnFormat event for every detail record, this will affect your performance significantly.


Save preview picture

In the Crystal Reports Designer, you have the option to save a snapshot of the first page of a report for previewing in the File Open dialog box. This capability is supported in the RDC.

Two methods exist in the Report Designer Component runtime under the Report object: get_Save and put_SavePreviewPicture. You can use get_SavePreviewPicture to get the property and use put_SavePreviewPicture to set the property.

Note: You should be very careful to enable this flag at design time. If you don't and if the report contains thumbnail pictures, it can affect the performance when saving or loading the report.


Charts

The following charting features are carried through the Crystal Reports Designer and the Report Designer Component:

Automatically scale data axis

Two runtime properties exist under the class GraphObject: EnableAutoScaleDataAxis and EnableAutoScaleData2Axis.

Legend layout

In the Report Designer Component runtime, the enumerator type CRPieLegendLayout is available for use, along with the property LegendLayout under the class GraphObject.

Chart on all records

Please refer to the Crystal Reports User's Guide for a detailed description of this feature.

Chart on running totals

Please refer to the Crystal Reports User's Guide for a detailed description of this feature.

Font change for Chart elements

You can change the font used for chart elements. In the Report Designer Component runtime, properties exist in the GraphObject class to change the font for these chart elements: title, subtitle, footnote, group title, data title, series title, legend, group labels, data labels and series labels.

Formats for data points and data axes in charts

Four formats exist in the Chart Expert to format data point values and data axis values: 1K, 1M, $1K and $1M.

In the Report Designer Component runtime, the following properties exist in the GraphObject class to support this:

  • DataAxisNumberFormat
  • Data2AxisNumberFormat

Creating charts based on a Cross-Tab

You can create a chart based on a cross-tab object. The method, AddGraphObject, exists with the parameter pCrossTabObject. pCrossTabObject is optional, is a VARIANT type, and has to be a CrossTabObject. (For crGroupGraph and crDetailGraph, this parameter is ignored.)


Creating reports at runtime using code

The RDC includes Report Creation API methods. These methods enable you to create ad hoc reports at runtime using nothing but code. The methods can be used within Visual Basic, Microsoft Office, or in any environment from which you can access an automation server. Because these methods now enable Crystal Reports Designer functionality in your runtime applications, they require separate licensing.


Cross-Tab reports

Cross-Tab formatting

The enhancements to the Crystal Reports Designer for formatting cross-tabs (for example, predefined grid styles, formatting separate grid lines) are now also available in the Report Designer Component at design time.

Selecting & formatting cells in Cross-Tabs

You can select individual cells in a cross-tab, or select multiple cells in a cross-tab, to format and re-size them. This is a design-time only feature.


ADO and OLEDB tables

Two methods exist in the Database object to give you more control when working with ADO and OLEDB data:

  • AddADOCommand (connection, command)
  • AddOLEDBSource (connection, tableName)

These two methods enable you to add an ADO and OLE DB data source, save the report, and then refresh the report.

Note: Some databases such as Oracle are case sensitive and require that proper case be applied to the database names and table names in the connection string.

The methods from earlier versions, SetDataSource and Add (DatabaseTables collection) allow you to set a run time ADO Recordset as a data source, but the report saved will not be refreshed.


Database Expert

The Report Designer Component has been enhanced to use the Database Expert when you:

  • Use the Report Designer Component to create a report through the Report Expert.
  • Perform a Set Location.
  • Add Database.

When you create a report or do a set location, use the Data Explorer to manage your database connections. The Data Explorer provides an integrated tree view of all data sources available to you.

For more information on the Data Explorer, please refer to Crystal Reports User's Guide.


Select Distinct Records

You can direct the RDC to select only unique records from a data source. In the Report object, EnableSelectDistinctRecords has been added to allow you to get or set this option based on user input.


Selecting & editing embedded fields

If a database field is embedded in a text object, you can select and edit the embedded objectfield as if it were not embedded. Note that the RDC allows you to manipulate embedded objects at design time only.


Report object events

BeforeFormatPage & AfterFormatPage events

The BeforeFormattingPage and EndFormattingPage events are fired before and after formatting a page respectively. These events enable you to make a variety of page-specific changes to your report.

You could, for example, reset Report Variables that you were using to calculate a subtotal on a page-by-page basis. Another possibility is to control the report formatting information as desired before the page is formatted.

Note: There are a number of properties and methods you cannot use in these events. For example, you cannot use the "SetText" method in BeforeFormatPage or AfterFormatPage or you will get a runtime error. When the events are fired, the report is in Active formatting mode while the sections are in inactive formatting mode. Thus, you can use properties and methods that affect the report object, but you can't use properties and methods that affect anything in the sections of the report.

FieldMapping event

The FieldMapping event is fired if a database is changed while it is being verified. Field mapping enables you to change the name of a database field that a report field points to if that field no longer exists or has been renamed in the data source. Verifying the database will trigger the FieldMapping event.

Note: This event is fired only when CRFieldMapping Type is set to crEventFieldMapping. Otherwise, the program will display a field mapping dialog box instead.

Note: If you have added tables with a linked field to your report then you must map that field even if it is not inserted into the report. Otherwise, when you verify the database, either the field mapping dialog box will appear and identify the linked field as an unmapped field or the FieldMapping event will fire.

NoData event

The NoData event is fired when the data set in the report is empty. It enables you to stop the processing and/or invoke error handling.

Note: This event is fired only for the main report even if there is a subreport.


Formatting

Text formatting

To complement the Crystal Reports Designer on line spacing, character spacing, text rotation and indentation for text objects and string field objects, the Report Designer Component runtime contains the following features.

In the TextObject object for text objects, and the FieldObject object for string field objects, the following properties and methods exist:

  • CharacterSpacing (read/write)
  • LineSpacing (read)
  • LineSpacingType (read)
  • SetLineSpacing (method)
  • TextRotationAngle (read/write)
  • FirstLineIndent (read/write)

    • When reading, this method gets first line indent of the first paragraph; when writing, it sets first line indent for all the paragraphs.

  • LeftIndent (read/write)

    • When reading, this method gets the left indent of the first paragraph; when writing, it sets the left indent for all the paragraphs.

  • RightIndent (read/write)

    • When reading, this method gets the right indent of the first paragraph; when writing, it sets the right indent for all the paragraphs.

  • TextFormat (read/write)

    • For text objects only.


Fractional point font support

You can specify a fractional point size for text objects and database fields, including the 10.5 point font commonly used in Japanese. To do so, type in a fractional point size in the Font tab of the Format Editor that you use to format a selected text object or database field.

Note: VB users cannot use this feature. While our own dialog box now supports fractional point sizes, Visual Basic does not support such sizes.


Accounting conventions

To support conventions used in accounting, you can control how the negative symbol, currency symbol and zero value are displayed, and reverse the sign when displaying numbers in accounting reports. To implement these conventions, the following properties have been added to the Report Designer Component runtime FieldObject class: UseReverseSign and ZeroValueString.


Formulas

Basic syntax

The formula language has been extensively enhanced with the addition of a Visual Basic-like language called Basic syntax since Crystal Reports 8. It is an alternative to the formula language. Most functions, operators, and control structures have been added to both Crystal and Basic syntaxes, and most existing Crystal capabilities have been duplicated in Basic as well. While existing Crystal Reports users do not have to learn this syntax to utilize the extra capabilities, it is intended to be easy to learn and use for developers already familiar with Visual Basic.

Apart from the functions, operators and control structures available in both syntaxes, Visual Basic developers who distribute applications can benefit from the fact that Basic formulas are portable and do not require any additional DLLs to run.

You must use a single syntax within a given formula, but you may use formulas with different syntaxes in the same report. When you enter a formula (other than a selection or search formula - see note below) in the Formula Editor, you can choose either Crystal or Basic syntax as the default syntax for the formula.

Functions available to both syntaxes include:

  • financial functions
  • mathematics functions
  • programming shortcut functions
  • type conversion functions
  • date and time functions
  • array and string functions
  • percentage functions

Operators available to both syntaxes include:

  • integer division
  • exponentiation
  • eqv
  • imp
  • xor
  • mod

Control structures available to both syntaxes include:

  • for statement
  • do statement
  • select ... case statement

For a more detailed description of these functions, operators and control structures, please refer to the Crystal Reports Online Help (crw.chm).

Note: The two syntaxes are fundamentally equivalent, with one exception: When you create or modify search or selection formulas using the Select Expert, the Search Expert, or the Formula Editor, you can only use Crystal syntax.


FormulaSyntax and LastGetFormulaSyntax

Two properties have been added to the Report class for working with these two languages: FormulaSyntax and LastGetFormulaSyntax.

  • You can specify the syntax that you want to use before you create a formula via the FormulaSyntax property.
  • After getting formula text, you can use the property LastGetFormulaSyntax to determine the syntax used for the formula.


Grouping

Hierarchical reporting

You can use hierarchical grouping to arrange data in a report to show hierarchical relationships. Keep all the elements of the hierarchy in the same table, but display the relationships between the elements. This is useful, for example, when reporting off a Human Resources database, to show the organizational hierarchy within a company.

In the Report Designer Component runtime, the following properties have been added to implement this grouping under the Area class:

  • EnableHierarchicalGroupSorting
  • ParentIDField
  • InstanceIDField
  • GroupIndent

You can use the InstanceIDField and ParentIDField properties to organize the group sorting tree, use the GroupIndent property to design the layout, and use the EnableHierarchicalGroupSorting property to enable or disable hierarchical group sorting.

At design time you can select hierarchical grouping for your report in the Report Designer Component, by right-clicking and choosing Report|Hierarchical Grouping Options. This will invoke the Change Hierarchical Options dialog box.

For more information and an example of how to use this feature, please refer to the Crystal Reports User's Guide.


IDE

Toolbars

As in the Crystal Reports Designer, toolbars have an updated, flattened look, and can be moved. And, in particular to the Report Designer Component, the toolbars can also be resized to fit your needs.


Complete XML support for the Web

Crystal Reports fully supports the Extensible Markup Language (XML) adopted by the World Wide Web Consortium (W3C) for delivering content over the Internet.

XML is emerging as the standard data format for the whole data-related industry because it's recognized across applications and across platforms. Keeping pace with the current advance in technology, Crystal Reports allows you to report off existing XML data and to export your work to XML format.


Access XML data at runtime

Use the Report Designer Component to access XML data streams at runtime and pass that information to objects in report applications.

Note: For information on using XML, refer to the "XML" chapter of the Crystal Reports User's Guide.

Export report data straight to XML

Export your report data to XML format quickly at runtime. This allows you to send the data to other eCommerce applications used to read and manipulate information.

Properties have been added to the ExportOptions object to support these features. These properties are:

  • XMLAllowMultiplePages
  • XMLFileName

Note: For more information see ExportOptions Object Properties.


Improved interactivity with parameters

Using parameters not only enables user-driven reporting, but also increases report performance, especially over the Web. Create multi-purpose reports to ensure that everyone receives the right information quickly.

All of Crystal Reports' web-enabled report viewers allow report designers and end users to utilize parameters to their full potential over the Web. Whether users prefer the Java, ActiveX, or DHTML viewers, they can interactively regulate the information they see by accepting default report parameters, picking from listed options, specifying multiple values, or entering ranges.


Display web reports independent of server location

Use Relative URLs to share your reports and their associated report objects on any server, in any directory. Each report remains independent of its actual location, because Relative URLs eliminate dependence upon any particular server or virtual directory.


Extend reporting abilities with additional applications

With BusinessObjects Enterprise, use Web Desktop, samples, or any client application designed by your Administrator (using the SDK) to access shared reports.


Additional Web reporting features

HTML and DHTML export

The performance of the HTML and DHTML export has been greatly improved.

Re-distribute the ASP Web Report Server

The enhanced ASP Web Report Server (rptserver.asp) is not dependent upon the Web Component Server, so developers can easily distribute their ASP web applications.

Note: For information on redistribution rights refer to License Manager Help (License.chm).

Facilitate administration with the license manager

Keep track of your Crystal Reports licenses and key codes with the Business Objects License Manager (available only with Crystal Reports Developer Edition). This administrative tool makes it easy for you to ensure that your product installation always meets your reporting needs. It also allows you to check the number of concurrent user licenses being used in the ASP environment. Access the Business Objects License Manager from the BusinessObjects 11 program group on the Start menu.

Please note that the Report Designer Component will work only within the concurrent license limit when used as a reporting server.

Note: For more information see "License Manager" in the License Manager Help (License.chm).


A closer look at some of the key features

Click the appropriate link to jump to that section:

  • Report Variables
  • Report Creation API
  • Using fields that bind to data sources only at runtime
  • Thin-client applications and meta-layer data
  • Field Mapping


Report Variables

The RDC includes Report Variables. These are "smart" variables that can be used to maintain state when you code things such as running totals based on a Section Format event. These variables understand what's going on inside the report formatting process at any given time, and they enable you to do more of your report-oriented coding exclusively in VB. The discussion that follows explains why you might need to use report variables.

The RDC uses a multiple pass model to generate its reports. The number of passes the program needs to generate a given report depends on the complexity of the report. There is no "one size fits all" answer to the question, "How many passes will it take?"

During each pass, various sections in the report get fired. A Details section might get fired several times for a single record. This might happen, for example, when you have selected the "Keep Section Together" option and the program jumps back and forth between pages as it determines on which page it should print the section.

If you use a standard VB variable to calculate running totals, that variable is unable to use the built-in intelligence of the RDC. When a section is fired multiple times, the variable gets incremented each time the Format event for that section is trapped. In this case your calculations will be distorted. When you create a running total in the RDC using a Crystal Running Total field, however, the program knows to increment the field value only once for each record, regardless of how often the section is fired.

Note: The maximum allowable size for a string in a string Report Variable is 255 including the null byte. If you set a string value to more than 255, the string will be truncated.

For further discussion on "what happens when" during the report creation process, see the Report Processing Model appendix in the Crystal Reports User's Guide.


Using Report Variables

Instead of using the Dim statement to declare a Report Variable, you declare it by invoking the AddReportVariable method when the Report Initialize event fires. This method requires you to supply a data type and variable name as parameters. For example:

Me.AddReportVariable crRVCurrency, "Total"

Note: Make certain you enclose the name of the variable in double quotes.

Once you have declared the variable, you can get its value using the GetReportVariableValue method that is part of the Report object. You can set or increment the variable using the SetReportVariableValue method. For example:

Me.SetReportVariableValue "Total", Me.Field3.Value + Me.GetReportVariableValue("Total")

Note: Report Variables are only available in RDC runtime. If you save a report as a RPT file to use with standalone Crystal Reports, you will lose the capability of the report variable.

For further information on Report Variables, see the Report Variables sample application in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Code\RDC\Visual Basic\Report Variables folder. For a description of the sample application, see Report Variables.


Report Creation API

The RDC now includes Report Creation API methods. These methods enable you to create ad hoc reports at runtime using nothing but code. The methods can be used within Visual Basic, Microsoft Office, or in any environment from which you can access an automation server.

The RDC also provides a Report Creation Wizard object that your application can call at runtime to enable your users to create reports at runtime using an intuitive design environment. The Wizard even attempts to identify your data source so it can make the data selection automatically.

The Report Creation API methods provide the application user with Report Designer capabilities even if they are not themselves registered users of Crystal Reports. For this reason, a licensing model is in effect for these methods only. Please refer to the license material available from the help menu in the product for further information.


Using fields that bind to data sources only at runtime

The RDC enables you to create report templates based on unbound field objects. Then, using minimal code, you can bind field objects to a data source (or one of several data sources) at runtime. The Report Engine uses the data type and the Name property of the unbound field object to match it with a data field in the recordset.

This functionality makes it easy to build reporting into n-tier applications where you have on-demand recordsets and non-continuous data connections. It also makes it easy to build a single report that can work with a variety of recordsets, making development and maintenance more efficient.

To take advantage of this functionality
  1. Add the RDC to your project.

    2. For further information, see Adding the RDC to your project.

  2. Choose the Unbound Fields option from the Field Explorer in the RDC.
  3. Choose a field object by data type and drag it into position where you want it to appear on your report.
  4. Set the Name property of the field object to match the name of the field in your recordset that you want it to bind to.
  5. Continue until you have all your fields in place.
  6. Write the code to activate the binding.

    7. This code example binds to a database table. In the code, set up an Object variable for your report. For example:

    Dim Report As New CrystalReport1

  7. Then to create the binding, code using the Report object method AutoSetUnboundFieldSource:

    8. Report.AutoSetUnboundFieldSource crBMTName


Thin-client applications and meta-layer data

The discussion of unbound fields makes it look like it is extremely easy to create unbound report templates that bind to their data sources only at runtime. It is easy, but that easiness masks, somewhat, the power of this capability. It should not be underestimated. You can use that capability to build thin-client applications that report off of meta-layer data.

If you have been interested in having your applications utilized by larger corporations, you know that you have been forced to consider a more server or multi-tiered approach. Organizations interested in keeping up with the times have been forced to move to larger customized applications for solutions like ERP systems. This combination of technology adoption has required developers, and the tools they use, to advance beyond simple applications that connect directly to a data source.

From a reporting perspective this means that you need a way to take advantage of the meta-layers within an ERP solution.


The meta-layer

A meta-layer is an intermediate data layer that holds a subset of the data in the original data source. The data in the meta layer typically has already been summarized, manipulated, and/or cleansed. Meta-layers are used when it becomes too complicated for users to understand or connect to the raw data itself.


The application and the reports

Your other challenge is based on the customizing of these systems. There is no standard database format; it is different for every company. To provide a solution, you must create client server applications that can extract the data from a meta-layer and then utilize the extracted information within the reports you provide for your users. Crystal Reports 11 takes advantage of two features to provide an answer:

  • The ability to link a report to an ADO Recordset.
  • The ability to create a report template using unbound fields.

Linking a report to an ADO recordset is closely associated with the Unbound Fields capability. An unbound report field:

  • Is a field type that you add to a blank report during the development of an application.
  • Has no data source until the user executes the report at runtime.
  • Acts like a placeholder on the report in situations where you don't have access to the user's data source.

This is the case every time you write an application that is meant to connect to a customized ERP type application. Now you have a solution:

  • The final application extracts data from the meta-layer and writes it to an ADO object.
  • The RDC connects to the ADO object at runtime and populates the Unbound Field objects.

By designing your application using unbound report templates, you can still give users the ability to generate reports against this data, even though at design time the data doesn't exist.


Web-based thin-client solutions

You can also use this entire solution over the web for a true thin-client implementation You can use the same set of code (Com objects) to extract the data from the custom system and its meta-layer, and pass it to an ADO object. The CRAXDRT (using unbound fields) can then access this ADO recordset and publish the report.

The main difference is that the report ends up being produced in an EPF format instead of RPT and it gets fed back to the user via the Web server in a viewer rather then in a preview window of an application.

To provide such a web solution, you would need to do your development in an ASP environment rather than a Windows-based development environment like VB, VC++ or Delphi.


Field Mapping

When you first create a report, the report draws its fields from the data source as it exists at that time. It uses the structure of the database (number of fields, field position, data type, etc.) to identify and select those fields you want placed on the report. If the structure of the database gets changed (by adding or deleting fields) after you create the report, you need to adapt the report to the new structure. The RDC now has a robust set of Field Mapping tools that you can use to accomplish this.


The FieldMapping event

In earlier versions, you have been able to use the Verify method in the Database object to verify that the structure of the data source matches that of the data source used in the report. This checks for prior changes to the structure. Now you can determine if the data source structure gets changed while you're verifying it by trapping the FieldMapping event. The RDC fires a FieldMapping event when there is a change to the structure during the verify process.


The FieldMappingData object

The RDC also has a FieldMappingData object that enables you to bind a report field object to a data source with a different table and/or field name, or with a different data type than that in the report. The FieldMappingData object has three read/write properties and one read only property that enable you to map the changes in the data source to the database field objects in your report. The read/write properties are FieldName, MappingToFieldIndex, and TableName. The read only property is ValueType.


What's New in the Report Designer Component

This section highlights the new features of the Report Designer Component, and it points you to further information.

This section provides an overview of the new features of the Report Designer Component (RDC), and it points you to further information.

Click the appropriate link to jump to that section:

  • New features of the RDC
  • Crystal Reports product information


New features of the RDC

The new features in version 11 for the RDC are primarily focused on format compatibility with reports that are created with Crystal Reports 11, and on how to maintain compatibility with applications that were created in previous versions of the RDC.

Complete details on the new features listed below can be found in the Crystal Reports product documentation and user guides. See also the product documentation for a list of behavior changes from version 10 to 11, as well as the list of features that are scheduled for future deprecation.

Version 11 of the RDC includes the following new features:

  • New API's
  • Improved Database Connectivity
  • New Runtime Features
  • Improved Report Design-Time Experience
  • Enhanced Deployment Options
  • More Descriptive Error Messages
  • Improved ActiveX Viewer


New API's

It is now possible to retrieve the fully qualified database table name for a table item in a report. Use the following syntax:

report.Database.Tables(#).Qualifiers.Item(#)

or

report.Datbase.Tables(#).Qualifiers(#)

where # is an integer.


Improved Database Connectivity

The RDC now uses improved database connectivity drivers, for added data connection manageability and performance.

  • Business Objects Universe support from Crystal Reports

    • You now have the ability to design and run reports against Business Objects Universe's as a data abstraction layer for your Crystal Reports.

  • Improved native Oracle database driver

    • The new Oracle database driver supports Oracle OCI v10 libraries, additional Oracle server SQL Expressions, as well as end-to-end Unicode characters in queries and returned data.

  • Teradata database connections

    • New SQL Expressions to support Teradata database connections.

  • Updated native DB2 driver

    • The native DB2 driver now supports Unicode.

  • Improved XML database driver

    • The new XML database driver supports reporting from web services and http data sources.

  • New Microsoft Exchange 2000/2003 driver

    • New features include customized reporting on Microsoft Exchange Data, which includes the following:

    • Calendar support (which includes recurring meetings)
    • Journal
    • Inbox
    • Tasks
    • Address Book
    • Contacts (which includes distribution list expansion).

    The 256 byte Field length limit has also been removed. This driver is now multi-thread enabled, which allows it to be used as an multi-threaded enterprise reporting data source.


New Runtime Features

New runtime features have been added for optimized financial calculations and image handling:

  • Image locations can be conditionally based on a formula that is calculated at report processing time.
  • Dynamic Cascading Prompts that are created in the Crystal Reports Designer are supported at runtime.

    • Note: Prompts cannot be modified or created with the embedded RDC design-time environment.

  • In the Formula Editor, report designers can choose whether null values are handled as exceptions, zeros, or default values. That behavior is supported at runtime in the RDC, but cannot be programmatically set with the RDC API.
  • New Crystal Reports formulas have been added:
    • urlEncode
    • urlDecode
    • Time Zone functions.
    • New rounding calculations, such as Ceiling, Floor, Multiple Round, and Round.
    • Improved Hierarchical Grouping to better support drilldowns and indentation.
  • The viewer and export formats now support images that span multiple horizontal pages.
  • The group sort order can now be conditionally based on a formula.
  • TopN, BottomN, TopPercentage and BottomPercentage values.
  • Support for NT Logon Impersonation for databases.


Improved Report Design-Time Experience

These new features improve the overall report design-time experience, to increase the productivity of report designers:

  • The charting dialogs have been redesigned and streamlined within the Report Designer, to make chart designing more intuitive.
  • A new and improved Printer setup dialog streamlines setting the page and paper size options for your report.
  • The new Printer Setup dialog box makes it easier to set options for the page and paper size of your report.


Enhanced Deployment Options

Deployment has been enhanced to allow application deployments that work every time.

  • The RDC merge modules are now automatically installed to \Program Files\Common Files\Merge Modules. You have the option to update these merge modules when you run the new Crystal Reports Patch installation service through the Crystal Reports designer.
  • The merge modules support recent versions of InstallShield.
  • Enhanced configurable deployment options allow full control over deployed database and exporting DLLs.


More Descriptive Error Messages

The most common error messages now make it easier for system administrators to diagnose problems. For example, the following error messages have seen improvements:

  • Opening Files

    • Messages that previously returned the text "invalid TLSV record," or only the text "TLSV," now indicate exactly why a file could not be opened, with messages such as "File in use" or "Report file is corrupt."

  • Exporting

    • The following situations now return more informative errors.

    • The message "Export failed. The report contains a feature which is not supported by the format you are exporting to" appears when the following actions are taken:
      • A report is exported to text when the report contains a subreport in the page header.
      • A report is exported to CSV when the report contains a cross-tab.
      • A report is exported to PDF when the report contains non- exportable fonts, such as some non-True Type fonts.
    • The message "Export failed. The system does not currently proved the required amount of resources" is returned when the system is out of memory or out of disk space for temporary files.
    • The message "Export failed. The requested page ranges are invalid" is returned when an invalid page range is given (for example, 7-4, 0-0).
    • The message "Failed to export" is now returned only when a problem exists in the destination format or the exported document cannot fit in the target format, such as when a very wide report is exported to Excel.
  • Database Connections

    • When a problem occurs with a database connection, a meaningful error message is returned which, when possible, also includes the specific database SWLSTATE error code.


Improved ActiveX Viewer

The ActiveX Viewer has been improved to enhance interactive report viewing with the following new features:

  • From the new Exporting dialog box, you can export reports to an editable RTF format from the viewer.

    • Note: There is no programmatic support in the RDC for exporting to editable RTF.

  • Icons appear in a standard order consistent with other Crystal Reports viewers. The icons have also been updated to be more consistent with the Crystal Reports product.
  • Page drawing performance dramatically improved in many scenarios through new caching of the rendered output.
  • Visual quality of output and printing improved to fully match Crystal Reports preview window, including better support of right-to-left text in languages such as Arabic and Thai.
  • Objects displayed in the ActiveX viewer can be highlighted individually or in groups and then copied or pasted in HTML or Rich Text format to applications such as Word, Excel and Outlook
  • Page navigation now supports the page-up and page-down keys.
  • Printing now supports multiple page ranges from the print dialog


Crystal Reports product information

See the Release Notes for additional Crystal Reports product information.


Introducing the Report Designer Component

This section introduces the Report Designer Component (RDC) and explains its architecture along with some possible development scenarios. It also provides additional sources for help and information on the RDC, including sample applications that present the RDC in real-world scenarios.

Click the appropriate link to jump to that section:

  • The Report Designer Component
  • How to Get Additional Information
  • Sample Reports
  • Sample Applications
  • Report Wizard
  • Complex Applications


The Report Designer Component

The Report Designer Component (RDC) is a powerful solution for Visual Basic developers who quickly and easily integrate reporting into their database applications. It's an ActiveX designer object that packs the reporting power of Crystal Reports into a lightweight add-in for Visual Basic 5.0 or 6.0. You can open, design and customize reports within the Visual Basic IDE. In addition:

  • Intuitive Report Experts make it flexible and efficient to connect to data and integrate powerful reports into applications.
  • With hundreds of report properties, methods and events, you have complete control over your report designs, using familiar Visual Basic code.
  • Report distribution is simplified through a small component count and free runtime.
  • Reports can be packaged within the application's executable or stored outside the application in the traditional (.rpt) format.

Note: Get the latest news about the Report Designer Component from the Business Objects Developer Zone web site at:

http://www.businessobjects.com/products/dev_zone


Design time

At design time, the Report Designer Component provides a user interface that closely integrates with the Visual Basic IDE. Through the user interface, you design and manipulate reports and report data. This interface includes events that can be directly programmed from within Visual Basic.

The Report Designer Component uses the Active Data Driver for connecting to ISAM, ODBC, and SQL databases through Data Access Objects (DAO), Remote Data Objects (RDO), ActiveX Data Objects (ADO), and Data Environments (Visual Basic 6.0 only). You can design the data set from within Visual Basic, then apply it to the report contained by the Report Designer Component.

When working in Visual Basic, you will often need to use the Report Viewer for ActiveX as a user interface to display reports. The Report Viewer is an ActiveX control that you can drop to a standard Visual Basic Form. The Report Viewer is where your report is displayed at runtime.


Runtime

The user interface provided by the Report Designer Component at design time does not appear in your application at runtime, or when it is compiled into an executable file. Instead, the Report Designer Component is accessed directly by your Visual Basic code. The Embeddable Crystal Reports Designer Control allows you to provide your users with the ability to design or edit Crystal Reports within your application using the same interface as the design-time control. However reports can be opened and saved only in the Crystal Report format (.rpt) and not in the ActiveX Designer format (.dsr) of the design time control.

The Report Designer object model provides a complete object hierarchy for direct manipulation in Visual Basic. The object model can be accessed through both the RDC runtime engine and the RDC design and runtime engine. See CR Automation Server for more information.

The Active Data Driver is also available at runtime, through the Report object of the Report Designer Component object model, and can be assigned a new set of data based on user interaction with your application. You design a Recordset or Resultset object in Visual Basic using the DAO, RDO, or ADO object model, and pass it to the report.

Finally, the Report Viewer takes center stage at runtime, connecting to the Report Designer Component and displaying the embedded report. With careful design and placement on the Form, the Report Viewer appears as a window inside your application.


RDC Architecture

If you aren't familiar with the RDC, you should note that it consists of four components. Together, these components enable you to create, design, edit, program, and preview, print, or export your reports. The components are listed below.

Click the link below to go to the desired section:

  • Report Designer
  • Automation Server
  • Crystal Report Viewer
  • Embeddable Crystal Reports Designer Control


Report Designer

The Report Designer is integrated tightly within the Visual Basic 5.0 and 6.0 IDE, enabling you to create, view, and modify reports without leaving Visual Basic. This component was specifically created for Visual Basic developers.


Automation Server

There are two automation servers provided with the RDC. The Crystal Reports ActiveX Designer Runtime Library (craxdrt.dll)—known as the RDC runtime engine, and the Crystal Reports ActiveX Designer Design and Runtime Library (craxddrt.dll)—known as the RDC design and runtime engine. Both offer the same extensive object model with hundreds of properties and methods for you to use to manipulate the report at runtime. See Unification of the RDC object model for more information on when to use each automation server.


Crystal Report Viewer

The Crystal Report Viewer is an ActiveX control that you can use to preview reports on screen. The viewer is loaded with customization options to give you great control over your interface and over the viewed report itself.


Embeddable Crystal Reports Designer Control

The Embeddable Crystal Reports Designer Control (Embeddable Designer) is an ActiveX control that you can use to allow your users to design and edit Crystal Reports in your application at runtime.

Component Description

Crystal Report Designer UI Component (crdesignerctrl.dll)

A COM (Component Object Model) component that provides the user interface at design time for the user to interact with and create or modify the report.

Crystal Report Designer Design and Runtime Time Component (craxddrt.dll)

An underlying COM component that provides services for the user interface component. The component also encapsulates all of the report objects and is responsible for all of the data processing and report layout. Use this component with client based applications that incorporate the Embeddable Designer.

Crystal Report Designer Run Time Component (craxdrt.dll)

The component that encapsulates all of the report objects and is responsible for all of the data processing and report layout. Use this component with any Client based or server side application that does not incorporate the Embeddable Designer.

Crystal Report Viewer for ActiveX (crviewer.dll)

An Active X control which can be drawn on a form and manipulated at design time. It provides a rich object model used to modify user interaction with the report at runtime. This component is required only if a developer wants to provide on-screen display of reports at runtime.

VB Form

The Report Viewer Control must be embedded on a Visual Basic Form in order to display the report on screen. The Create Report Expert can automatically add a Form with the Report Viewer embedded to the project when you finish designing a report with the Expert.

Data Set

One of the following:

  • Data Access Object (DAO) Recordset
  • Remote Data Object (RDO) Resultset
  • Active Data Object (ADO) Recordset
  • VB Data Environment
  • Crystal Data Object (CDO)
  • ODBC Direct

These objects do not need to be valid at design time. For example, you could construct a report template at design time without the data being available. This is handled through Data Definition Files. However, the data set objects must be present and valid at runtime to generate a report.


Combinations of RDC Components

The three RDC components can be used together or individually, in any combination. The following table identifies which of the components you need to use in your project:

Using the Report Designer with the Automation Server

  • VB and VBA only
  • for designing reports within IDE and manipulating the reports with code
  • not necessary to preview the reports
  • reports can be printed or exported
  • use the Crystal Formula Language, VB or VBA code for expressions in the report.

Using all three RDC components

  • VB and VBA only
  • want to design reports within IDE and manipulate the reports with code
  • reports can be previewed, printed or exported
  • use the Crystal Formula Language, VB or VBA code for expression in the report.

Using the Automation Server and the Crystal Report Viewer

  • VB and VBA, C++, Visual InterDev, Visual J++
  • want to design reports using Crystal Reports, preview from application, and manipulate the reports with code
  • reports can be printed or exported
  • use the Crystal Formula Language, VB or VBA code for expressions in the report.

Using the Automation Server, Embeddable Designer, and the Crystal Report Viewer

  • VB and VC++
  • want to allow your users to design or edit their own Crystal Reports
  • reports can be saved, printed, exported and previewed.
  • use the Crystal Formula Language, VB or VBA code for expressions in the report.

Using the Automation Server by itself.

  • VB and VBA, C++, Visual InterDev, Visual J++
  • want to design reports using Crystal Reports and manipulate the reports with code
  • reports can be printed or exported
  • use the Crystal Formula Language, VB or VBA code for expressions in the report.


Adding the RDC to your project

The installation program will attempt to add the menu item Add Crystal Reports 11 to the Project menu of the VB IDE when you install the RDC. If that menu item appears, select it to add the RDC to your project.

If the menu item does not appear on the Project menu, you will first need to add it manually, and then you can add the RDC to your project.

To add the RDC to your project
  1. Choose Components from the Project menu.
  2. Click the Designers tab in the Components dialog box when it appears.
  3. Select Crystal Reports 11 on the Designers tab.

    4. This will add the menu item to the Project menu.

  4. Finally, select Add Crystal Reports 11 from the Project menu.

The RDC is now ready to use within the VB IDE.


How to Get Additional Information

Business Objects supplies an extensive set of tools to help you master the RDC quickly and easily. These include:

  • Crystal Reports User's Guide
  • The Business Objects Web Site
  • Object Browser
  • Properties Window
  • Sample Reports
  • Sample Applications


Crystal Reports User's Guide

Since the capabilities of the RDC mirror the capabilities of Crystal Reports, you can use the Crystal Reports User's Guide to learn about the RDC's powerful reporting capabilities. For example, if you want to learn the details of the Select Expert, how to link a subreport to its parent report, or just more general information on report creation, you should refer to the User's Guide. This documentation is available in printed form as well as a searchable electronic (PDF) form on the CD. You can find the User's Guide (Usergde.pdf) in the Docs folder on the CD.


The Business Objects Web Site

Business Objects provides a wide range of developer support information and tools on its web site at:

http://www.businessobjects.com/products/dev_zone

The web site offers these support tools and more:

  • Downloadable files and product updates.
  • Developer samples.
  • A comprehensive knowledge base showing solutions and workarounds to a wide range of technical problems.
  • Technical briefs, detailed documents that discuss complex issues and/or explain how to use various sophisticated product features.
  • FAQs: quick answers to your most common questions.
  • Release Notes: details about known issues, product features, enhancements, and fixes.

The web site is updated continually so you will always be able to find current information to help you with your development challenges.


Object Browser

A source of support for many VB programmers is the VB Object Browser. Use the Object Browser to navigate the RDC automation server object model (CRAXDRT), the Report Viewer object model (CrystalActiveXReportViewerLib11Ctl), the various objects used in your project (Project n), and the VB and data object models. The Object Browser introduces you to the hierarchy of the object models, and provides you with useful information about the various classes and members in the object models.


Properties Window

The RDC exposes each object in an RDC report. This means you can view all of the design time properties and options in the Properties Window of the VB IDE. Simply select an object in the report and you can see and set its various properties visually.


Sample Reports

The program includes many sample reports you can use to learn sophisticated reporting techniques. With a full installation, you can find these samples in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Reports folder.


Sample Applications

Crystal Reports contains many Visual Basic sample applications. These applications show you how to use the RDC in real-world situations.

With a complete installation, you will find the sample applications in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Code\RDC\Visual Basic folder. The sample applications provide you with one of the most direct and tested methods for learning the RDC.

The applications contain usable code that can be modified and plugged into your own programs. They also present great ideas for using the RDC. By studying these ideas, you may be able to generate new business by offering clients sophisticated capabilities.


Visual Basic Samples

The following sample applications have been created for Visual Basic developers:

  • ADO Connection Methods
  • Change Runtime Location of OLE Object
  • Connection Info
  • Embeddable Designer Control
  • Field Mapping
  • Inventory Demo
  • Load Picture Demo
  • Printer Settings
  • Report Variables
  • Report Wizard
  • Search and Select Experts
  • Unbound fields
  • Viewer
  • Viewer Runtime options


ADO Connection Methods

This application demonstrates two methods to add ADO data sources to a report:

  • AddADOCommand takes an active ADO connection and ADO command object as parameters. In this example, a new connection is created to a database, and the resulting recordset is assigned at runtime to the report.
  • AddOLEDBSource takes as parameters the name of an active ADO connection and the name of a table that can be accessed through that connection. In this example, the connection setup through the VB Data Environment is used as a data source.

Note: Some databases such as Oracle are case sensitive and require that proper case be applied to the database names and table names in the connection string.

Both methods can be used with either the VB Data Environment or another data source created at runtime.

Note: Notice in the Designer that there is no data source attached to the report at design time.


Change Runtime Location of OLE Object

This application demonstrates how you can set the location of an OLE object at Runtime using the SetOleLocation command.

This application takes three different OLE objects:

  • A bitmap.
  • Part of an Excel spreadsheet.
  • Part of a Word document.

This application cycles through them so a different object gets printed each time the Details section gets formatted.


Connection Info

This application demonstrates the database connection properties of a report.


Embeddable Designer Control

This application demonstrates how to include the Embeddable Crystal Reports Designer Control in an application. It shows how to add a new or existing report to the Embeddable Designer, how to display the report in the Crystal Report Viewer, and how to refresh the report in the Crystal Report Viewer so it displays any changes made in the Embeddable Designer.


Field Mapping

This application demonstrates how to manipulate field mapping. It shows how to change the mapping of the report fields to a different database field.


Employee Profiles

This application demonstrates how you can set and format the text in report text objects at runtime.


Inventory Demo

The Inventory Demo is a sample application that displays a report. It shows you how to use the Report Initialize section for report level manipulation. It also includes how to change the BackColor of the report Details section conditionally for those items that need to be ordered.


Load Picture Demo

The Load Picture application shows you how to load a picture into the report at runtime. It also shows you how to change some of the values and properties of some of the text objects in the Details section of the report at runtime.

The program also shows you ways to implement calculations and calculated fields in the RDC. The two methods are:

  • Using the Crystal Formula Language.
  • Using VB code in the Section_Format event procedure.

This example describes how to perform calculations in the Section_Format event using VB.


Printer Settings

This application demonstrates how to change the report printer settings at runtime using code.

  • As of version 9, there are four report properties that allow you to easily retrieve and set PaperSize, PaperOrientation, PaperSource, and PrinterDuplex for the report printer options. All of these are demonstrated.
  • In version 9 and higher, there is also a new method called PrinterSetup that provides a Windows standard printer setup window to allow the user to change the printer properties directly at runtime. This is demonstrated as well.

The two methods are independent of each other. For example, changing the Windows standard printer setup will not alter the report printer settings and vice-versa. These properties and the method give you much more control over how the report is printed.


Report Variables

This application demonstrates the use of the Report Variable capability.

The RDC includes Report Variables. These are "smart" variables that can be used to maintain state when you are coding items such as running totals based on a Section_Format event. These Crystal variables can be used in your VB code. They understand what's occurring inside the report formatting process at any given time, and they enable you to do more of your report-oriented coding exclusively in VB.

This sample describes how to use Report Variables to calculate totals based on only part of the data. Since Report Variables accept any valid value from the VB environment, you can use values that only exist at Runtime to change the formatting of your report.

In this sample, there are three columns based on a database: one column of currency values, one column of integer values, and one column of non-integer values.

  • The first column changes to a blue color when the sum of the values in the column is greater than a random value. A total is displayed in the lower part of frmMain showing the total of the values colored blue.
  • Records in the second and third columns change color when the sum is greater than a different random value. The sum is then reset. This can be useful if you wish to start and restart a totalling operation in the middle of a report.
  • A String Report Variable is used to build a string consisting of the first digit of each green highlighted value. You could use this method to easily extract individual string values from a report field.

Note: Report Variables can only be set and retrieved while the report is formatting.


Report Wizard

You can use the Report Wizard with the Report Creation API to enable users to create entirely new reports at runtime and then view or save the report. When you implement the Wizard, you save yourself the necessity of writing "create" code for each of the objects your users put into their new report. This application shows you how easily you can implement the Wizard in your code.

You can also use the Report Wizard as a starting point for creating a custom report wizard that allows you to set your own defaults for report creation.


Search and Select Experts

This application shows you how to control the Search and Select Wizards in the Report Viewer using code.

The Search and Select Wizards allow advanced filtering and highlighting of data displayed in the ActiveX viewer. In this sample, two different methods of using the Search and Select Wizards are demonstrated:

  • Two command buttons on the main form display a search or select wizard with predefined fields and ranges already set for the user. The only displayed fields and ranges are those that have been added at runtime.
  • The Search and Select Expert buttons on the top right part of the viewer are over-ridden, allowing you to specify default criteria to search for. Alternatively, the default search and select experts can also be displayed.


Unbound fields

This application shows you how to create a report template using the Unbound Fields capability. It also shows you how to bind the fields at runtime to a data source that you also create at runtime.

In this sample, there are five unbound fields created in the report. Notice that there is no data source added to the report at design time at all—the data source is created and added to the report at runtime.

You can also use Unbound fields in formulas, although this sample does not demonstrate this use.

Unbound fields give you great flexibility in your programming. They even allow you to create a single report template that can be bound to a variety of data sources at runtime in response to user input. This enables you to create a wide range of custom reports all from a single template. See the Pro Athlete Salaries application for a demonstration of this capability.


Viewer

This simple application shows you how you can create your own Report Viewer toolbar and manipulate the ActiveX viewer using your own custom buttons.


Viewer Runtime options

This application demonstrates the many ways you can manipulate the Report Viewer at runtime. It also shows you how to implement the use of the Select Expert and the Search Expert in the Viewer.

All of the check boxes on the main form correspond to viewer properties that you can change at runtime. In this sample, there are more than 21 viewer properties that are manipulated. Note that to enable the Select Expert and Search Expert, you must reference the Crystal Select Expert OLE control module and you must place the Select Expert Control on the form.

The Select/Search Expert is essentially invisible on the form and is located immediately to the left of the About Sample Command Button in this sample.


Microsoft Office Samples

Visit the Business Objects Developer Zone web site at:

http://www.businessobjects.com/products/dev_zone

To search for Microsoft Office sample applications click Support, and then click the Download Files and Updates link.


Complex Applications

The following three applications are large and complex. They each demonstrate many of the RDC capabilities.

Click the appropriate link to jump to that section:

  • Pro Athlete Salaries
  • First Class Hotels


Pro Athlete Salaries

This application shows a very sophisticated use of the Create Report API and Unbound Fields. This report is worth studying because it demonstrates the powerful things you can do with the RDC through code alone.

Note: The Designer does not appear in the Project Explorer. This is because the report is actually a template report created at runtime using Unbound Fields and the Create API, and the fields are bound at runtime to a custom recordset generated at runtime based on user input.


First Class Hotels

The sample demonstrates a number of Crystal Reports features, as well as possible advanced uses for some features.

The main form in the sample, frmMain, is used for managing the reservations. Some features include:

  • The report displayed in the window is automatically updated whenever a reservation is added, the customer name changed, or the date range changed.
  • Double-clicking on a customer name or room number in the report will bring up a form containing information about that customer or room.
  • Clicking on one of the two miniature notepad icons in this window will also cause this same information report to be displayed.
  • The billing report that can be displayed by double-clicking the report, or clicking the notepad icons, only displays information between the start and end dates shown at the bottom of the reservation form.

The Room form, frmRoom, contains these features:

  • Allows adding/removing of hotel room numbers.
  • Clicking on the miniature notepad icon in this window will cause the information report to be displayed. The information will be displayed for all dates that the room has been used and is not restricted by a start or end date.

The Price form, frmPrice, contains these features:

  • Allows adding/removing of hotel room prices.
  • Customer: Allows adding/editing/removing of customers.
  • Clicking on the miniature notepad icon in this window will cause the information report to be displayed. The information will be displayed for all dates that the customer has stayed at the hotel and is not restricted by a start or end date.

This application uses many of the methods from earlier releases as well as this release. Here is a list to help you determine if this application has the answers you're looking for:

Crystal Reports Viewer Object

Methods | Properties | Events
PrintOut Refresh ReportSource ViewReport | EventInfo.Text EventInfo.Type | DblClicked

Crystal Reports Report Object

Methods | Properties | Events
AddReportVariable GetReportVariable SetReportVariable RecordSelectionFormula SetUnboundFieldSource | Get and Set PaperSize Get and Set PaperOrientation Get and Set PrinterDuplex Get and Set Papersource Database.Tables().Location LeftMargin RightMargin | BeforeFormatPage EndFormatPage Initialize NoData Section_Format


Quick Start for using the RDC

This section helps you get started using the Report Designer Component (RDC) in Microsoft Visual Basic. Three examples provide you with the basic skills needed to use the RDC. You will find a high-level explanation of the steps required to add the RDC to a project, a tutorial on adding an existing report to the RDC, and a tutorial on creating and modifying a new report.

Click the appropriate link to jump to that section:

  • Overview
  • Bullet Point Quick Start
  • Open an existing report
  • Create and modify a report


Overview

Using the RDC will add powerful reporting capabilities to your application, and you can do it all from the Visual Basic IDE.

Note: For information on using the RDC with other development environments, see Working with Visual C++.

The following three sections were designed to get you started with the RDC:

  • Bullet Point Quick Start

    • If you only need minimal instructions for using the RDC, this section is for you. It includes a higher level, bulleted explanation about how to create, view, and manipulate a report through the RDC.

  • Open an existing report

    • If you have created a report in the standalone version of Crystal Reports and you want to open it through the RDC and preview it in the Report Viewer, you will find this section useful. It includes a lower level, step-by-step approach.

  • Create and modify a report

    • If you want to create, preview, and manipulate a report through the RDC, you will find this section extremely useful. This is also a lower-level, step-by-step approach. It mirrors the procedure of the Bullet Point Quick Start but describes each of the bullet points in more detail.

If you have questions that are not answered by these samples, please see the Sample Applications at \Program Files\Business Objects\Crystal Reports 11\Samples\En\Code.


Bullet Point Quick Start

To add reporting capabilities to your application using the RDC:

  • Add the RDC to your project.
    • With a complete install, the option Add Crystal Reports 11 appears on the Project menu in the VB IDE. Select Add Crystal Reports 11.
    • If the option does not appear, select Components from the Project menu and check the Crystal Reports 11 option on the Designers tab. Then select Add Crystal Reports 11 when it appears on the Project menu.
  • Select a data source.

    • When you add the RDC to your project, the program presents the Crystal Report Gallery dialog box. If you're not familiar with Crystal Reports, choose the Using Report Expert option. The Standard Report Creation Wizard dialog box provides you with an easy to use interface to connect to the desired data source. See "Standard Report Creation Wizard" in the Crystal Reports User's Guide for more information.

  • Create a report.

    • From the Standard Report Creation Wizard, you can build your report by adding fields, setting up grouping and totalling, specifying your sort options, adding charts and selection criteria if you wish, and even adding a professionally designed look. You can do that by using the various wizard screens.

  • Add the Report Viewer to your project.

    • When you select Finish in the Standard Report Creation Wizard, the program prompts you to select whether or not you want the expert to add a form containing the Report Viewer Control to your project. It also prompts you to select whether or not you would like the expert to modify the project properties to set this form as the startup object. If you select Yes to add the form containing the Report Viewer Control, it also writes the necessary code for displaying your report in the viewer and resizing the viewer whenever the form is resized.

    • Once selected, if you don't want the Viewer installed automatically, or if you don't want the Viewer form to be your start-up form, you can change these actions in the Default Settings dialog box.
    • You get to the Default Settings dialog box by right-clicking in the RDC, selecting Designer, and then selecting Default Settings from the shortcut menu when it appears.
  • Create a UI for users to modify the report at runtime.

    • Now that you have a report, you may want to manipulate it with code based on user input. If you haven't done so already, here is the point where you could build the UI for the user using Visual Basic.

  • Write the code that does the modifications.

    • Now you can write the code that ties the users UI selections to the report.

    • Each object in the report is exposed in the Properties window of the VB IDE.
    • Double-click any object and you can write code for the object.
    • Double-click a section of the report and you can write code that affects the section and the objects in the section.
    • By referencing an object name in your UI code or the object index through one of the many Collections, you can manipulate that object directly based on user input.
  • Preview, print, or export the report.

    • When you have completed the steps above, you can run the application and preview, print, or export the report using the UI controls you've set up to do it.

Now you have integrated the most powerful reporting tool into your application.


Open an existing report

In this example, you will open an existing report file in Visual Basic. This activity demonstrates how to import existing reports (RPT files), and lets you become familiar with the Report Designer Component user interface. This tutorial uses Crystal Reports 11 and Microsoft Visual Basic 6.0.

Ensure that you have completed the installation of the Report Designer Component files.

To open a report directly within Visual Basic 6.0
  1. Open Visual Basic and create a new Standard EXE project by selecting Standard EXE from the start up dialog box, or by selecting it from New Project on the File menu.
  2. Add the Report Designer Component to Visual Basic if it was not already added during the installation process.
  3. From the Project menu, select Components.
  4. Click the Designers tab and select Crystal Reports 11. Click Apply and then click Close.

    5. The Report Designer is now available in this project and any projects you create in the future.

    Now you need to insert the Report Designer into the project form.

  5. On the Project menu, click Add Crystal Reports 11.

    6. The Crystal Report Gallery appears displaying the different types of Report Creation Wizards that are available.

  6. Since you will be opening an existing report file, click From an Existing Report. Click OK.
  7. Browse to the report called World Sales Report at \Program Files\Business Objects\Crystal Reports 11\Samples\En\Reports\General Business. Click Open.

    8. Depending on your setup, you may be presented with a dialog box that asks you about adding a form at runtime.

  8. Click OK.

    9. The Report Designer Component is added to your project and the report layout is displayed in the design window. Report files created in any version of Crystal Reports can be imported in this manner. Before you run the report, right-click on Form2 and select View Code. You should see Visual Basic code that looks like this:

    Dim Report As New CrystalReport1

    Private Sub Form_Load()

    Screen.MousePointer = vbHourglass

    CRViewer1.ReportSource = Report

    CRViewer1.ViewReport

    Screen.MousePointer = vbDefault

    End Sub

    Private Sub Form_Resize()

    CRViewer1.Top = 0

    CRViewer1.Left = 0

    CRViewer1.Height = ScaleHeight

    CRViewer1.Width = ScaleWidth

    End Sub

    This default code, inserted by the Report Designer Component, will point the runtime Crystal Report Viewer at the report to display the results. This makes it easy to flip between the report design window and the finished report. You can add to or modify this code, but for now you'll just view the report.

  9. From the Run menu select Start (F5), or click the Start button on the Visual Basic toolbar.

    10. After a few seconds, you will see a form displaying the finished report in the Crystal Report Viewer. You can resize the form by dragging the lower right-hand corner of the Viewer. You can save this project if you like, but it will not be required to complete the steps in the next section.

Now that you have opened and viewed a report, feel free to go back and explore some of the right-click and property settings in the Report Designer window. You may also want to browse the CRViewer class of the CrystalActiveXReportViewerLib11Ctl object to see some of the properties and methods that you can use to customize the appearance of the viewer at runtime.


Create and modify a report

In this example, you'll create and modify a simple report using the Report Designer Component. This will guide you through the basic steps in connecting to a data source and creating a report. The report you will be creating is a Sales By Region report based on a Microsoft Access database. You'll use the Report Creation Wizards to help create the report quickly and easily, then you'll modify some of its properties and make it more interactive by adding some event-driven code.

This exercise only touches on a few of the hundreds of properties and methods available, but it will give you an idea of how simple it is to fully integrate and customize reports in your Visual Basic projects.

To Add the RDC to your project
  1. Open Visual Basic and create a new Standard EXE project by selecting Standard EXE from the start up dialog box, or by selecting it from New Project on the File menu.
  2. Add the Report Designer Component to Visual Basic if it was not already added during the installation process.
  3. From the Project menu, select Components.
  4. Click the Designers tab and select Crystal Reports 11. Click Apply and then click Close.

    5. The Report Designer is now available in this project and any projects you create in the future.

    Now you need to insert the Report Designer into the project form.

  5. On the Project menu, click Add Crystal Reports 11.

    6. (In some environments, Add Crystal Reports 11 will appear as an option itself on the Project menu.)

To select a data source
  1. Check Using Report Expert and select Standard. Click OK.

    2. The Standard Report Creation Wizard appears. This window allows you to select the desired data sources.

  2. Expand the Create New Connection folder; then the ODBC(RDO) folder.

    3. The ODBC(RDO) dialog box appears.

  3. Select Xtreme Sample Database 11 from the Data Source Name list, and then click Finish.

    4. Now that you've specified the data source and connection method, you need to specify which tables to use.

  4. Expand Xtreme Sample Database 11, and then expand Tables.
  5. Under Tables, double-click Customer to add it to the Selected Tables box.

Now that you've selected the database and the table, you need to specify the fields to include in the report.

To create a report
  1. Click Next to move to the Fields page.
  2. Select the Customer Name database field from the Available Fields list, then double click on the field name or use the arrow button to add the field into the Fields to Display box.

    3. Do the same for the Last Year's Sales, City, and Region fields.

  3. Click Next to move to the Group page and select the Region field; then double click on the field name or use the arrow button to add the field into the Group By box.

    4. Do the same for the City field.

    This will group your data by Region and, within each region, by City. By default, the Sort Order for the Region and City Fields is in Ascending Order.

  4. Click Next to go to the Summaries page.

    5. Because Last Year's Sales is the only numeric field in the report, the Report Expert automatically selects it for summarizing.

  5. Click Next to move to the Group Sorting page. Select Customer.Region from the Group to be sorted list and then click Top 5 groups.

    6. Do the same for the Customer.City.

  6. Click Next to go to the Chart page and click Pie chart under "What kind of chart would you like to see?".
  7. In the Chart title box, type "Sales by Region".
  8. Click Next to go to the Record Selection page.

    9. We won't add any selection formula for this example.

  9. Finally, to give the report a professional look, click Next to go to the Template page and select a style of your choice.
  10. Click Finish.

    11. The RDC creates the report.

The Report Expert presents you with the option of adding a form with the Report Viewer Control and setting this as the start-up object.

To add the Report Viewer to your project
  1. Click OK to accept the defaults.

    2. The Expert will format the report and display it in the design window.

  2. Click the Start button on the Visual Basic toolbar or press F5 to run your project.

    3. After a few seconds, you will see a form displaying the finished report in the Crystal Report Viewer.

This exercise has shown the basic steps for creating a new report. Although you don't always have to use the Report Creation Wizards, they make connecting to your data source and creating the initial report fast and easy. You can then alter the look and feel of the report using the Report Designer window. Common tasks like field formatting, adding text, and modifying field positions can be accomplished by dragging fields or altering their properties. These can be set using Visual Basic code or in the Visual Basic object properties window.


Create a UI for users to modify the report at runtime

When you add report capabilities to your application, you provide the user with a UI for customizing their reports (setting the date range for the report, or deciding whether they want to see a detail or summary report for example). Rather than demonstrating how to build a UI (which is a VB procedure outside the scope of this tutorial) the next section shows you how to customize the report by hard-coding the modifications. With a UI, you would pass your user's selections in place of the hard code.


Write the code that does the modifications

This report is currently based on all regions. You'll modify the selection criteria to include only data from the USA. But first you may need to add a reference to your project.

  1. Close the Crystal Report Viewer.
  2. From the Project menu select References.
  3. Check the Microsoft ActiveX Data Objects Recordset 2.x Library and click OK.
  4. Double-click Form2 from your Project Explorer to open it.

    5. This form contains the Report Viewer.

  5. Double-click it to see the code in the main window.

    6. This code should appear in the General Declarations section.

    Dim Report As New CrystalReport1

    This code should appear in the Form_Load event procedure. It tells the viewer what report it should display and then it tells it to display (view) the report.

    Private Sub Form_Load()

    Screen.MousePointer = vbHourGlass

    CRViewer1.ReportSource = Report

    CRViewer1.ViewReport

    Screen.MousePointer = vbDefault

    End Sub

    This code should appear in the Form_Resize event procedure, it resizes the viewer every time the form is resized.

    Private Sub Form_Resize()

    CRViewer1.Top = 0

    CRViewer1.Left = 0

    CRViewer1.Height = ScaleHeight

    CRViewer1.Width = ScaleWidth

    End Sub

  6. To add selection criteria to the report, edit the "Form2" declarations and "Form_Load" procedure to look like this.

    7. Dim Report As New CrystalReport1

    Dim rs As New ADODB.Recordset

    Private Sub Form_Load()

    Screen.MousePointer = vbHourGlass

    rs.Open "Select * from customer where country = 'USA'", _

    "Xtreme Sample Database 11"

    Report.Database.SetDataSource rs,3,1

    CRViewer1.ReportSource = Report

    CRViewer1.ViewReport

    Screen.MousePointer = vbDefault

    End Sub

    This adds a query to select only the records with "USA" in the "Country" field. The recordset that results from that query will be passed to the report engine and the results displayed.

  7. Run the report again to see the changes.

    8. Your report should only contain USA data.

    Now you'll add a text object to the report and manipulate it using code.

  8. In the main Report Designer window, right-click just to the right of the chart in the Report Header pane and point to Insert; then select Text Object.
  9. Move the text object just above the pie chart.

    10. Tip: You may have to move the chart down a bit first.

  10. Make note of the Name in the Properties window.

    11. In this example, the name is "Text5" but the name in your project may be different.

    Now you'll set the contents of the text object you just added.

  11. Open the "ReportHeaderSection1" code for editing in the Text Object by double-clicking on the Report Header (ReportHeaderSection1) and add some code to the "ReportHeaderSection1" "Format" procedure as shown.

    12. Private Sub ReportHeaderSection1_Format(ByVal pFormattingInfo As Object)

    Text5.SetText "Here is some text from my app"

    Text5.Font.Italic = True

    Text5.Font.Bold = True

    Text5.Font.Size = 14

    End Sub

    This will set the text object, change the font to Italic, Bold 14 point, and display the results.

  12. Run the report again to see the changes.

    13. To complete this exercise, you'll now add some event-driven code to explore how you can make the run time viewer control more interactive.

  13. With the Form 2 code window open, use the Object and Procedure list boxes to select the "CRViewer1" object and add the "DrillOnGroup" and "PrintButtonClicked" procedures to the "Form2" code. Edit these new procedures as shown below:

    14. Private Sub CRViewer1_DrillOnGroup(GroupNameList As Variant, ByVal DrillType As CRVIEWERLibCtl.CRDrillType, UseDefault As Boolean)

    MsgBox "You're drilling down on the " & _

    GroupNameList(0) & " group!"

    End Sub

    Private Sub CRViewer1_PrintButtonClicked(UseDefault As Boolean)

    MsgBox "You clicked the Print button!"

    End Sub

    The "DrillOnGroup" procedure is triggered when the user double-clicks on any graph pie slice or report summary field. When this occurs, the text shown will appear in a message box. The "PrintButtonClicked" procedure works similarly when the viewer Print button is clicked. Try both of these procedures to make certain your code works as expected.

Now that you've seen a few simple ways to modify a report, you may want to explore some of the other properties and events in the report engine that you can use in your application. For more sophisticated programming examples, consult the sample applications. For more details on specific methods, properties, or events, use the VB Object Browser or consult the Crystal Reports Developer's Guide (CrystalDevHelp.chm).


RDC Data Access

This section explains data access through the Report Designer Component (RDC), and describes how to connect to a data source through the Data Expert. It also provides information on Active Data, the Microsoft Data Environment, and the database drivers used by the RDC.

Click the appropriate link to jump to that section:

  • Overview
  • The Data Expert
  • Active Data sources
  • Data Environments


Overview

In response to the question "What data can I use when building reports in the RDC?", the answer is "You have virtually no limitations." The RDC has been designed to use virtually any data source with minimal work on your part.

The Report Designer Component supports any data source that Crystal Reports can connect to. The Report Designer Component implements the Crystal Reports user interface that you are already familiar with, so you can quickly connect to any existing data.

The Report Designer Component also supports Data Environments in Visual Studio 6.0.

Probably, the best way to cover all of the available data sources is to take a brief look at the Data Expert dialog box. This dialog box appears when you select Database Expert, and it lists data source options in a hierarchical tree view.

Visit the Library on the Business Objects web site to get documentation and knowledge base articles about data access.


The Data Expert

The Current Connection, Favorites, and History nodes in the Data Expert were designed to make it more efficient for you to return to current connections, favorite data sources, or data sources you have used in the past. Those nodes are all intuitive, and they are discussed in depth in the Crystal Reports User's Guide. This section discusses some of the options available in the Create New Connection node and the Project Data node.

The Create New Connection node shows subfolders for various data sources you can connect to. Some popular choices are described here:

  • Access/Excel (DAO) lets you connect to a supported database type (Access, dBASE, Excel, Lotus, and so on). You can create a new connection using the Make New Connection option.
  • Crystal Queries lets you browse for a query (.qry) file.
  • Database Files shows a list of standard PC databases that reside locally. You can use Find Database File to browse for a PC database using the Open dialog box.
  • Dictionary/Infoview lets you browse for a dictionary (.dct or .dc5) or infoview (.civ) file.
  • ODBC (RDO) shows a list of ODBC data sources you have already configured for use.
  • OLAP opens the OLAP Connection Browser so you can choose an OLAP cube as a data source.
  • OLE DB (ADO) shows a list of OLE DB providers you have already configured for use. You can also specify a Microsoft Data Link file to use.
  • More Data Sources shows a list of other data sources that can be accessed through native drivers.

Note: The data source options available in the Create New Connections folder depend on the data access components selected during installation.

The Project Data node displays any connection to Data Environments currently available in your application.


Active Data sources

Crystal Reports can be used to report off ActiveX data sources, including ActiveX Data Objects (ADO), Remote Data Objects (RDO), and Data Access Objects (DAO). Reports created off these data sources can be used in Visual Basic applications that use these ActiveX data sources. Visual Basic applications, Crystal Reports also supports Crystal Data Objects (CDO), which are sets of relational data created at runtime using Visual Basic arrays.

Crystal Reports also offers the ability to create reports without specifying an actual data source. This is supported through the use of a Data Definition file, which is an ASCII text file with placeholders to represent database fields. By using reports created off a Data Definition File, an application developer has the flexibility of specifying the actual data source at runtime.

Crystal Reports provides these translation files for Active Data reporting:

File | Description
crdb_fielddef.dll | For Microsoft ActiveX Data Objects
crdb_ado.dll | For Microsoft ActiveX Data Objects
crdb_cdo.dll cdo32.dll | For Crystal Data Object Crystal Data Object COM DLL
crdb_dao.dll | For Microsoft Data Access Objects
crdb_odbc.dll | For ODBC

These translation files works with a different set of drivers for each data source.


DAO

You can connect to a DAO data source through the Access/Excel (DAO) node under the Create New Connection node.

Data Access Objects (DAO) is designed primarily for use with local and ISAM (Indexed Sequential Access Method) data sources created through applications such as Microsoft Access, Microsoft FoxPro, and Borland dBASE. Although DAO can be used to connect to ODBC data sources, RDO and ADO provide more powerful options for such data. However, DAO is the oldest of the three technologies, giving it the advantage of being familiar to many Visual Basic programmers. As a result, DAO is also frequently found in existing applications, and applications created with older versions of Visual Basic.

If you are adding the Report Designer Component to a Visual Basic application that already uses DAO, or if you are connecting to a local data source such as an Access or dBASE file, you should consider using DAO to design your reports. Experienced Visual Basic programmers who are familiar with the DAO object model may also want to stick with a known technology. However, if you are working with ODBC or other remote data sources, RDO and ADO may be a better solution.

Once you design your report in the Report Designer Component, information about the connection to your DAO data source is stored with the report, and cannot be accessed directly. However, you can change the data displayed by a report by changing the data source at runtime using the SetDataSource method. A DAO Recordset object may be passed to the report through this method. Keep in mind, though, the Recordset must have fields identical to those in the original data source used at design time.


ODBC (RDO)

You can connect to an RDO data source through the ODBC (RDO) node under the Create New Connection node.

Remote Data Objects (RDO) is designed specifically for working with remote data sources. This includes ODBC and most common SQL database systems. In fact, RDO acts as an object-oriented wrapper around the ODBC API. The flexibility of ODBC is available to Visual Basic programmers through the simplicity of a COM based object model. Already a common choice for developers of client/server systems, RDO allows the execution of stored procedures and the processing of asynchronous operations, meaning your users can continue to work while your application processes a data query in the background.

The basic object used to manipulate data in RDO is a Resultset (specifically, the rdoResultset object). A new Resultset can be defined in your Visual Basic application and passed to the Report Designer Component at runtime using the SetDataSource method. The RDO data source used to initially create your report at design time, however, is not available for direct manipulation. Instead, information about the connection to the data source is stored inside the instance of the Report Designer Component that you add to your application. By creating a new Resultset at runtime, though, and passing the Resultset to the Report Designer Component, you can control the data in a report based on user requests and responses.

RDO provides a powerful connection to remote data sources through ODBC. If you are designing a client/ server application, or any application that needs to connect to a large database system such as Microsoft SQL Server, Oracle, or Sybase Adaptive Server, RDO can provide a strong solution. However, RDO limits your application to standard relational database systems. Other sources of data, such as e-mail and messaging servers, system logs, and Internet/intranet server logs are unavailable to RDO. Developers designing web-based applications using Visual InterDev would also be served better by ActiveX Data Objects (ADO).


OLEDB (ADO)

You can connect to an ADO data source through the OLEDB (ADO) node under the Create New Connection node.

ActiveX Data Objects is a data connection technology designed to provide a common interface for working with relational databases, mail messaging, event logs, and most any other form of data storage. ADO can be used to connect to any OLE DB compliant data source when you design your report in the Report Designer Component.

The resulting ADO Recordset is directly available from the Report Designer Component, and can also be replaced by alternative Recordset objects. For example, if your Visual Basic application allows users to make choices that can affect the set of data displayed by a report, simply create a new ADO Recordset at runtime, then pass it to the Report Designer Component using the SetDataSource method. The only restriction is that the fields in the new Recordset match the fields originally used to design the report. For more information on using the SetDataSource method, see SetDataSource method.

ADO is the most flexible option for data access. It provides a means of connecting to all kinds of data, including mail messaging, event logs, and Web server site data. In addition, it has been designed, ultimately, to replace DAO and RDO.

  • If you are creating new applications using Visual Basic, you should strongly consider ADO for your data connections.


CDO

You can connect to a CDO data source through the CDO node under the Create New Connection node / More Data Sources node.

If you develop applications that produce data that does not exist outside of the running application (applications monitoring system or network resources, for example), you can take advantage of the most powerful reporting features in the industry via the Crystal Data Object (CDO). Using CDO and the Report Design Component, you can create reports that are instant and up to date, without first having to dump the data to a separate database.

The Crystal Data Object is an ActiveX DLL that can be accessed from any Windows development environment that supports ActiveX. By creating a Rowset object, similar to a Recordset, and filling it with fields and data, you design a virtual database table that passes as an ActiveX data source to the Crystal Active Data Driver. Once the CDO Rowset has been created, it can be used just like any other active data source such as DAO or ADO.

CDO, like DAO and ADO, is based on the Component Object Model (COM). Any development environment that supports COM interfaces can dynamically generate a set of data for a report without relying on a database that exists at design time.

Note: The Crystal Data Object does not support Memo or BLOB fields.


Data Environments

Data Environments (introduced with VB 6) allow for interactive creation of hierarchical ADO Objects at design time, and easy access to data at run time. Through the Data Environment Designer you create Data Environment objects to connect with Data sources (Connection Objects), and access data from those sources (via Command Objects) at design time and run time.

You can use a data environment as a data source for reports you create with the Report Designer Component. If your project includes a data environment, the Report Designer Component will allow you to select the data environment as a data source at design time. Runtime reports make full use of the data exposed by a data environment by working with the standard connection, command, or recordset objects provided, much like working directly with an ADO object.


Using Data Environments as report sources

If you choose to use the Data Environment (DE) as a source for a report, you must query the DE to determine the parameters required to create the command and then recreate the command separately from the DE. Crystal Reports does not persist the runtime password so you must set the password in the code. There are two ways to set the password. The first is to set the TableLogonInfo for the particular table that uses the DE by providing the appropriate password through the tables connection properties.

For example:

Dim Report As New CrystalReport1

Private Sub Form_Load()

Dim CProperty As CRAXDRT.ConnectionProperty

Report.Database.Tables(1).ConnectionProperties("Password") = "sa"

CRViewer1.ReportSource = Report

CRViewer1.ViewReport

End Sub

The second method is to set the recordset of the DE command as the data source of the report. In this case, you must first open the connection to the DE using the correct password, then execute the command that generates the recordset, and finally call SetDataSource to extract the data into the table.

For example:

Dim Report as New CrystalReport1

Private Sub Form_Load()

DataEnvironment1.Connection1.Open DataEnvironment1.Connection1.ConnectionString & ";Password=password"

DataEnvironment1.Command1

Report.Database.Tables.Item(1).SetDataSource DataEnvironment1.rsCommand1

CRViewer1.ReportSource = Report

CRViewer1.ViewReport

End Sub


SetDataSource method

The SetDataSource method is designed for reports using the Active Data driver. The Method is used to provide information about a data source to the database driver associated with a Database object. For example, if the Crystal Active Data Driver has been used to design the report, this method can be used to provide an active data source for the report, such as a DAO, ADO, or RDO Recordset or a CDO Rowset.

Microsoft Data Link (UDL) files

The Report Designer Component also supports Microsoft Data Link (UDL) files.

Microsoft Data Link Files are comparable to File DSNs in ODBC. UDL files store connection information to be used by the OLE DB layer. UDLs are available with OLE DB 2.0, which is installed by MDAC 2.x.

To create a UDL file
  1. Right-click the Windows desktop, choose New from the shortcut menu and then choose Microsoft Data Link.

    2. A new UDL file appears on the desktop. By default, it is called "New Microsoft Data Link.UDL." You can rename this file.

  2. Double-click, or right-click, and choose Properties on this icon to configure the connection.
  3. Select the appropriate OLE DB provider in the Provider tab before entering information in the Connection tab.

    4. The template for the Connection tab changes based on the OLE DB provider used.

For more information on how to use UDLs, see the Microsoft Data Link help file, "msdasc.hlp."


Report templates using unbound fields

The RDC now enables you to create report templates based on unbound field objects. Then, using minimal code, you can bind those field objects to a data source (or one of several data sources) at runtime. The Report Engine uses the data type and the Name property of the unbound field object to match it with a data field in the recordset.

This technology replaces the need for data definition files. Data definition files are still supported in the Report Designer Component however. For additional information on using Unbound Fields, see Using fields that bind to data sources only at runtime or the Unbound fields and Pro Athlete Salaries sample applications found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Code\RDC\Visual Basic folder.


Understanding the RDC Object Model

This section provides you with an understanding of the Report Designer Component (RDC) Object Model through a high-level overview of how a report is created. The overview is then related to the primary objects and collections contained in the RDC Object Model. More detailed information on a number of the objects, collections, and events is available at the end of the section.

Click the appropriate link to jump to that section:

  • Overview
  • The Application object
  • The Report object
  • The Database object
  • Object Considerations
  • Collection considerations
  • Event considerations


Overview

The Report Designer Component is a dual interface object model based on Component Object Model (COM) technology, a standard that allows applications and component objects to communicate with one another. Because the standard doesn't specify how components are structured, but defines only how they communicate with one another, the RDC can be used in any development environment that supports COM—such as Visual Basic, Visual C/C++, and so on.

Note: Visit the Library on the Business Objects web site to get documentation and knowledge base articles about the Report Designer Component Object Model.


A high level overview

The RDC is similar in operation to the Form designer in VB: it enables you to create instances of various classes visually.

  • You design a form by positioning controls where you want them to appear and then setting their properties.
    • Each of these controls is actually an instance of a class. A command button is an instance of one class. A text box is an instance of another.
  • You design a report in the same way, by positioning objects where you want them to appear and then setting their properties.
    • Each of the objects in your report is an instance of a class. A Section is an instance of one class. A text object is an instance of another.

A new report, by default contains five section objects: the Report Header (RH) section, the Page Header (PH) section, the Details section, the Report Footer (RF) section, and the Page Footer (PF) section. The sections are numbered in consecutive order from top to bottom. The top section is one; the bottom section is five. All of these sections together make up the Sections collection. The Sections collection is indexed with a one-based index.

Each of these sections has a single event: Format. The Format event is fired whenever a pass is made through the section as the report is being created. By trapping the format event for a section, you can manipulate the section or any of the objects you place in the section whenever the section is fired.

  • Manipulating the section involves actions such as setting its background color or its height.
  • Manipulating an object involves actions such as changing a font color in a field object based on a condition being true or changing the report title in response to user input.

You can do just about anything with the report at runtime, with a minimum of code, and all within the VB IDE.

At this very basic level:

  • You can place objects in your report.
  • You can manipulate the objects as needed in response to various events.


The next level

A report can have more than five sections. You can create these sections yourself if you need additional sections. The RDC will create some for you whenever you group or summarize data.

Sections are numbered consecutively as they are created.

  • For example the first new details section created is DetailsSection2
  • The second new section isDetailsSection3, and so forth.

Note: Every section created will have a unique name. Each new section will consist of the section name with a sequential number, such as DetailsSection2, PageHeader2 and so on.

When sections are created, they are added to the Sections collection and indexed appropriately.

You can place a variety of Report Objects in the sections of your report.

  • If they are Field Objects, they could be one of many kinds of fields including database fields, formula fields, parameter fields, group name fields, or many others as well.
  • If they are Subreport objects, they can each be viewed as a separate object with its own set of properties. But each subreport is itself a report, and as a report it can contain virtually all of the same kinds of different objects that it's parent report contains.
  • If they are Cross-tab objects, they too can be viewed as separate objects or as specialized reports that themselves contain a variety of different objects.

With Subreport objects and Cross-tab objects, you can change the properties of the objects themselves (Subreport Name, Cross-tab Name) and you can change the properties of the objects they contain as well.


The Primary Objects and Collections

The following objects and collections are discussed in the section:

  • The Application object
  • The Report object
  • The Areas collection
  • The Sections collection
  • The ReportObjects collection
  • The FieldDefinitions collection
  • The Subreport object
  • The Database object
  • The DatabaseFieldDefinitions collection
  • The DatabaseTables collection


The Application object

The top level of the object model is the Application object. Since it is at the top, the RDC always expects it to be there, so there's no need to reference it in your code (generally). There are some specific instances where you must reference it. For more information, see The Application object.


The Report object

Below the Application object is the Report object. The Report object contains many Collections and objects. For more information, see The Report object.


The Areas collection

The very top Collection in a report is the Areas collection. By default it contains five Area objects. This is a special kind of collection that you may not use too often (for more information, see The Sections collection).


The Sections collection

Every report, including a blank report, has Sections. The Sections are the bands in the report where you place the various report objects. By default, a new report, and thus the Sections collection for that report, contains five sections. Each of the five default sections resides in one of the five default areas—five sections:five areas. When you begin with a blank report, Areas and Sections are essentially the same. So there's little need to reference an area unless you have a specific need to do so.

For example, you want to create several of one kind of section. In this example, you want to create several Details sections. In this case, the five areas:five sections relationship is broken. To refer to those Details sections as a unit, you can think of one Details Area now containing several Details sections. When you reference the area, you are referencing all of the sections in that area.

Thus, unless you have a special need, you can think of Sections as having Report for a parent. If you have the need, or if you want to be very specific, you can also think of Sections having Area for a parent. However you think of this part of the object model is fine. As long as you have five sections and five areas, you can access Sections through Areas, or you can go directly to Sections. Your code will work either way. For more information, see The Sections collection.


The ReportObjects collection

ReportObjects is a collection that can contain many things. With the exception of Areas and Sections, everything else in a report is a report object including Database field objects, Parameter field objects, and Text objects. Note that a lower case "r" and "o" was used for the spelling of "report object". The reason is there is no "ReportObject" in the ReportObjects collection. The ReportObjects collection is just a convenient way to think about these objects and it is useful in your code.

Now many of these objects that are considered to be members of ReportObjects are also members of more specific collections.

  • A SortField object, for example, is a member of the ReportObjects collection. It is also a member of the SortFields collection.
  • A FormulaFieldDefinition object, likewise, is a member of the FormulaFieldDefinitions collection.

You can access an object through the ReportObjects collection or through its namesake collection. This provides you with much flexibility in your coding. See The ReportObjects collection.


The FieldDefinitions collection

In the ReportObjects collection, many of the members have the word "field" in their names: GroupNameFieldDefinition, ParameterFieldDefinition. Objects that contain the word "field" are also a part of the FieldDefinitions collection. As was the case with ReportObjects, there is no such thing as a generic FieldDefinition in the FieldDefinitions collection. Instead there are specific kinds of fields including FormulaFieldDefinition, SpecialVarFieldDefinition, SummaryFieldDefinition, and others as well.

Following this up the hierarchy, you'll see that a ParameterFieldDefinition is a member of:

  • Its namesake collection, ParameterFieldDefinitions.
  • The FieldDefinitions collection.
  • The ReportObjects collection.


The Subreport object

The Subreport object is part of the ReportObjects collection. A subreport is a report within a report; it is a complete report with its own Areas, Sections, and ReportObjects. Once you access a Subreport object, you manipulate the objects in the subreport the same way you would with objects in the main report. For more information, see The Subreport object.


The Database object

The Database object represents a data source for the report. But a data source doesn't mean all the data available. It means only a subset of data that is useful for the report. That subset can be defined as collections of tables and, within each of those tables, collections of fields. When you think about a data source in this way, the data side of the RDC object model becomes clear. For more information, see The Database and Database Tables objects.


The DatabaseTables collection

The Database object contains a DatabaseTables collection. This collection contains a number of DatabaseTable objects which comprise all the Tables which contain data used in the report.


The DatabaseFieldDefinitions collection

Each DatabaseTable object contains a DatabaseFieldDefinitions collection which holds all of the fields from the table that are available for the report. Each of those fields is called a DatabaseFieldDefinition.


Object Considerations

The Application object

Not all development environments support ActiveX designers. Visual C++ and Delphi, for example, are two environments where you can use the functionality of the RDC automation server but you can't add the RDC directly to your projects. In these cases, you must access the Report Designer's Report object by creating an instance of the Application object and then calling the OpenReport method as well.

In other situations, you may need to use separate report files in your application that were created or edited using Crystal Reports. An advantage of using such standalone report files is that through Crystal Reports, you can save report data with the report file, eliminating the need of maintaining a connection to a data source at runtime. In this case you will need to create an instance of the Application object and then call the OpenReport method as well.

The following code sample demonstrates the process of obtaining an Application object and opening a report file in Visual Basic:

Dim CRXApplication As CRAXDRT.Application

Dim CRXReport As CRAXDRT.Report

Private Sub Form_Load()

Set CRXApplication = CreateObject("CrystalRuntime.Application")

Set CRXReport = CRXApplication.OpenReport("C:\Reports\Sales.rpt")

End Sub

When this code finishes, CRXReport is a valid Report object and can be used just like any Report object you would obtain through the Report Designer Component.

Note: The sample call to CreateObject above uses a version independent Prog Id for the Report Designer Component. The correct Prog Id for this version of the Report Designer Component is CrystalRuntime.Application.11, but the version independent Prog Id will use the most recent version of the component installed on your system.


The Report object

Many existing ActiveX object models require declaring and creating a high level object, such as an Application object, before you can work directly with the data. The RDC, however, allows direct access to the Report object, giving you control over your reports with a small amount of Visual Basic code.

Assuming you have added the RDC to a Visual Basic application, and the (Name) property of that component is set to CrystalReport1, you can use code similar to the following to obtain a Report object representing that component:

Example:

Dim cr As New CrystalReport1

Note: For information on accessing a Report object through the Application object see The Application object.


The Field object

All relational databases have two standard features: records and fields. Records contain the actual data, while fields define what type of data the records contain.

  • You can control the records through Recordset and Resultset objects exposed by ADO, RDO, and DAO.
  • You can manipulate the fields in the data source through these objects as well.

To manipulate the fields that appear in your report, however, you must either:

  • Know the name of each database field you want to manipulate and reference each field directly.
  • Cycle through the fields in the ReportObjects collection to identify those fields that you want to manipulate.

For examples of how to use either of these methods, see Referencing objects in a report.


The Database and Database Tables objects

All reports must connect to a data source to obtain data. The most commonly used data source is a relational database. The Report Designer Object Model, therefore, has provided objects, properties, and methods specific to working with databases.

The Database object is available directly from the Report object and represents the data source used by the report. This data source can be changed using the Database object's SetDataSource, SetTableLocation method, Location property, or through the ConnectionProperties. In addition, the Database object provides the Tables property, a read-only property that gets the DatabaseTables collection of DatabaseTable objects. You have access to log on information (for password protected systems), database driver names, and database locations through a DatabaseTable object. Use code similar to the following in order to work with the Database and DatabaseTable objects:

Dim Report As New CrystalReport1

Dim tableName As String

Dim dbTable As CRAXDRT.DatabaseTable

Report.Database.Verify() ' Verifies a valid connection to the database

For Each dbTable In Report.Database.Tables

tableName = dbTable.Name

Next


The Subreport object

A SubreportObject object is another report inside the original report. Once you have obtained a SubreportObject, you can work with any aspect of it just as if it were a standard Report object.

You can obtain a SubreportObject through the ReportObjects collection. The following example shows you how to iterate through the sections of a report and change the background color of each subreport to magenta.

Dim Report As New CrystalReport1

Dim subReport As SubreportObject

Dim sect As Section

Dim rptObject As Object

For Each sect In Report.Sections

For Each rptObject In sect.ReportObjects

If rptObject.Kind = crSubreportObject Then

Set subReport = rptObject

subReport.BackColor = RGB(255, 0, 255)

Set subReport = Nothing

End If

Next

Next

Note: Currently, the Crystal Report Designer Component does not support subreports inside of subreports. The report iterations cannot go more than one subreport deep. However, you can have multiple subreports inside the main report.


The CrossTabObject object

A CrossTabObject object in the Report Designer represents a single cross-tab in your report. Cross-tabs are specialized subreports. Even if you design your primary report as a cross-tab, it is added to the report page as a separate object inside the report.

You can obtain CrossTabObject objects from a report much like you obtain subreports. Since a CrossTabObject is a report object like a field or a subreport, you can access it through the ReportObjects collection.

CrossTabObjects can be manipulated in the same way as other report objects. However, due to the complexity of this object, few properties and methods are exposed.

The following code searches for cross-tabs in a report and applies formatting features to make them stand out from the rest of the report.

Dim Report As New CrystalReport1

Dim xtObject As CrossTabObject

Dim sect As Section

Dim rptObject As Object

For Each sect In Report.Sections

For Each rptObject In sect.ReportObjects

If rptObject.Kind = crCrossTabObject Then

Set xtObject = rptObject

xtObject.BorderColor = RGB(255, 0, 0)

xtObject.HasDropShadow = True

Set xtObject = Nothing

End If

Next

Next


Collection considerations

The ReportObjects collection

The ReportObjects collection of a report Section object contains all report objects in that section. Report objects may be Text objects, Fields, Subreport objects, or Cross-tabs. To be able to work with a particular report object, you must first obtain the object, and then determine what type of object it is.

Note: If you want to work with all report objects in a section, consult ReportObject in the Object Browser for a list of properties that are common to all report objects.

Usually, report objects can be addressed directly in your code based on their Name property.

However, if you intend to work with several objects in a section, you need to refer to them through a Section object in the report. The following code locates the last object in the last section of the report and assigns a value to a String variable based on the type of object it is.

Dim Report As New CrystalReport1

Dim sect As Section

Dim rptObject As Object

Dim objKind As String

Dim lastSectWithObject As Integer

lastSectWithObject = Report.Sections.Count

Set sect = Report.Sections.Item(lastSectWithObject)

Do While sect.ReportObjects.Count <= 0

lastSectWithObject = lastSectWithObject - 1

Set sect = Report.Sections.Item(lastSectWithObject)

Loop

Set rptObject = sect.ReportObjects.Item(sect.ReportObjects.Count)

Select Case rptObject.Kind

Case crBlobFieldObject

objKind = "BLOB field object"

Case crBoxObject

objKind = "Box object"

Case crCrossTabObject

objKind = "CrossTab object"

Case crFieldObject

objKind = "Field object"

Case crGraphObject

objKind = "Graph object"

Case crLineObject

objKind = "Line object"

Case crOleObject

objKind = "OLE object"

Case crSubreportObject

objKind = "Subreport object"

Case crTextObject

objKind = "Text object"

Case Else

objKind = "Unknown object"

End Select

Note: Instead of using the Item property as shown, you can reference a report object directly using its index, for example, ReportOptions(1). You can also reference it directly using its name property by including the report object name in quotes, for example, sect.ReportObjects("Field5") instead of sect.ReportObjects(1).


The Sections collection

All report objects, such as Fields and Text objects, are contained within Sections. Often, you can obtain these directly by referring to the name property of an object in your code.

Note: There may be times, however, when you need to obtain an object through the report section it is in. At other times, you may have a need to make changes to the section itself.

Every report contains a collection of its sections, stored in the Sections property of the report object. You can access individual sections through this collection. For example, the code below sets the height of the first section of the report (the Report Header) to half an inch (720 twips) and suppresses the second section of the report (the Page Header) so that it will not appear.

Dim Report As New CrystalReport1

Report.Sections.Item(1).Height = 720

Report.Sections.Item(2).Suppress = True

For information on how to obtain and work with other objects within a Section object, such as fields and text objects, refer to The ReportObjects collection.

Each section in a report is itself a collection. The collection contains all of the report objects in that section. When designing your application, be aware that when a section is being formatted, all objects in that section are also being formatted. Also, all other sections and objects outside of the current section are not being formatted. This information can affect how data is displayed in various sections of the report, depending on your code.


Event considerations

The RDC directly supports four events:

  • AfterFormatPage
  • BeforeFormatPage
  • FieldMapping
  • NoData

The RDC supports the Format event for the Section object as well. These events are discussed in detail in the following section.


The Format event for the Section object

The Crystal Report Designer Component provides a Format event for every section of your report. This allows you to control report formatting and output dynamically at runtime. For example, you can apply conditional formatting during the Format event, based on conditions that exist only at runtime.

The Format event is a standard Visual Basic event that you can program by displaying the Code View of the Report Designer Component. Assuming the Report Designer has been named CrystalReport1 in your Visual Basic project:

  1. In the Visual Basic Project window, select the CrystalReport1 designer from the Designers folder.
  2. Click the View Code button in the toolbar at the top of the Project window.

    3. A Code window will appear for the CrystalReport1 designer component.

  3. In the object drop-down list box at the top left of the Code window, select a Section object that you want to apply code to.

    4. Notice that Section objects are numbered in the order that they appear on your report, from the top of the Report Design window to the bottom. For instance, if you select the Section1 object, your code will apply to the Report Header section of your report. These Section objects are labeled for you at the top of each section in the Report Designer window.

Notice that when you select a Section object, the Format event is automatically selected for you in the event drop-down list box at the top right of the Code window. Format is the only event available to the Section object.

When writing code for the Format event, keep in mind that not all properties and methods for all objects are available during the Format event. Many properties are available on a read-only basis. If you are not sure about a property or method, refer to the specific property or method name in the Object Browser or the Report Designer Object Model reference section of this guide.

The Format event receives a single argument from the Report Designer Component. The pFormattingInfo argument is an object of type FormattingInfo. The FormattingInfo object has only three properties:

  • IsEndOfGroup—This property is true if the section being formatted is a Group Footer.
  • IsRepeatedGroupHeader—This property is true if the section being formatted is a repeated Group Header. Repeated Group Headers appear when a group extends to two or more pages, and the group has been formatted to repeat information that appears in the Group Header on the second, third, and so on, pages. This property is only true if the Group Header is the second, third, and so on, instance of the Group Header. It is false for the original first instance of the Group Header.
  • IsStartOfGroup—This property is true if the section being formatted is a Group Header.

Note:

  • When designing your application, be aware that when a section is being formatted, all objects in that section are also being formatted. Also, all other sections and objects outside of the current section are not being formatted. This information can affect how data is displayed in various sections of the report, depending on your code.
  • If you are using the Format event to calculate values and you need to carry that value across sections (as in a running total, for example), you will need to use a Report Variable to store your ongoing total. For further information on Report Variables, see Report Variables.


The Visual Basic Initialize and Terminate events

In addition to the report-specific events, the Report object can also produce the standard Visual Basic Initialize and Terminate events.

The Initialize event is fired when you first reference the Report object at runtime. For example, your application may contain a global variable that represents the Report object of the Report Designer that you added to your application at design time:

Dim Report As New CrystalReport1

In this case, declaring and setting the Report variable fires the Initialize event. The Terminate event will be fired when this variable is set to Nothing:

Set Report = Nothing

The Initialize event and the Terminate event are fired only once for each Report instance. With that in mind, you can make many changes to your report within the event procedure code for each of these events:

Private Sub Report_Initialize()

' Add report initialization code here

End Sub

Private Sub Report_Terminate()

' Add report clean up code here

End Sub

  • Use the Initialize event to make broad changes that affect the entire report. For instance, you could assign a new data source using the SetDataSource method.
  • Use the Terminate event to clean-up of any variables or objects that you created during the Initialize event. If, for instance, you created a new ADO Recordset object in the Initialize event, you can use the Terminate event to set this Recordset object equal to Nothing, freeing up system memory and resources.


RDC Programming

This section provides solutions to a number of common runtime challenges. Most of these challenges involve accessing an object and then changing the properties. The section first discusses special considerations when programming with the Report Designer Component (RDC); it then presents the two general methods to access an object in a report or subreport. The examples assume that you have used one of these methods to locate the object of interest in order to concentrate on the special considerations that you may have with each of the various procedures.

Click the appropriate link to jump to that section:

  • Special considerations
  • Two methods to access an object in a report or subreport
  • Runtime examples


Special considerations

Object naming considerations

If your project includes other libraries that contain objects with names identical to those found in the Crystal Report Engine Object Library, you will encounter conflicts unless you reference the objects using a prefix that identifies their source. For example, if you have included the DAO Library with the RDC runtime object library in your project, you will find that both libraries include a Database Object. In order to avoid conflicts, you must prefix the objects as follows:

CRAXDRT.Database

for the object from the RDC runtime Object Library, or

DAO.Database

for the object from the DAO Library.

Scope considerations

When you specify a data source using code, it is important you place the code in the appropriate location in your project.Otherwise, you will face "no data" or runtime error situations because the report may be searching for data that has gone out of scope.

By default, the program does not read data into the report until you actually run the report (print it, preview it, and so on). Anything that terminates the connection to the data source before this time will cause out of scope problems.

Typical out-of-scope problems include:

  • Declaring a local object variable for the recordset or resultset in the Form_Load event procedure. While this may seem appropriate, the variable, and thus the data it references, will go out of scope as soon as the form stops loading.
  • Similarly, declaring a local object variable in the Report_Initialize event procedure will go out of scope because the recordset is discarded at the end of the procedure. That procedure ends before any records are read from the recordset.

Both problems can be corrected by declaring the variable for the recordset at the module level.

  • A third problem can occur when you declare a global variable for the report and try to populate it with a recordset that only has procedural scope. The following code provides a good example of this:

    • Dim CRXReport As New CrystalReport1

    Private Sub Form1_Load()

    Call SetData

    CRViewer1.ReportSource = CRXReport

    CRViewer1.ViewReport

    End Sub

    Private Sub SetData()

    Dim rs As New ADOR.Recordset

    rs.Open "Select * From Customer", "Xtreme Sample Database 11"

    CRXReport.Database.SetDataSource rs, 3, 1

    End Sub

In this example, although the CRXReport object is global (for the Form), the rs object exists only for the life of the SetData procedure. Even though it is assigned to the Report object before SetData finishes, the object, and the data that rs represents goes out of scope and is invalid for the Load event. Thus, the code will fail.

This problem can be solved using the ReadRecords method. ReadRecords forces the report to read the records into the report so that they are internal to the Report object itself rather than remaining as a separate Recordset object referenced by the report.

Private Sub SetData()

Dim rs As New ADOR.Recordset

rs.Open "Select * From Customer", "Xtreme Sample Database 11"

CRXReport.Database.SetDataSource rs, 3, 1

CRXReport.ReadRecords

End Sub

In this case, the records are read into the report prior to the end of the procedure. Thus, when the procedure ends, the recordset object may be discarded but the records are still available for use.

Index considerations

The various collections in the RDC object model are all one-based, that is, the first member of a collection has index number 1, the second member has index number 2, and so forth. Collection members are indexed consecutively in the order that they are created.

Dual Interface considerations

The Report Design Component provides dual interfaces. As a result, development environments such as Visual Basic and Visual C++ can bind with vTable interfaces at compile time, and less robust environments, VBA, ASP, for example, can use the IDispatch interface for runtime-only binding.

It is important that you use the more efficient vTable interface if it is supported by your development environment.

  • When you use vTable binding, you have "early binding" which means the VB compiler can identify syntax errors at compile time when they're easier to identify and fix than when they appear only at runtime.
  • It enables the VB IDE to speed your coding process by providing hints as you code through its "Auto List Members" and "Auto Quick Info" capabilities.

When you work with Visual Basic, always use the more efficient vTable interface as long as you Dim your object variables using specific class names instead of using the more generic "Object" type.


Two methods to access an object in a report or subreport

Referencing objects in a report

Before you work with a report object, you have to reference it (open it). You can reference a report object either explicitly or implicitly:

  • Referencing the object Explicitly is the easiest and quickest method for referencing a report object. When you use this method, your code can reference the report and its objects directly.
  • Referencing a report object Implicitly is a more generic approach. This approach allows your code to reference the report and its objects indirectly.

Explicit reference—an object in the report

Assume that in your report you have a field with the Name property "OrderID". Since you know the field name, you can use code similar to this to reference the OrderID field directly.

Dim CRXReport As New CrystalReport1

Dim CRXReportField As FieldObject

Set CRXReportField = CRXReport.OrderID

Note: Now that you have the OrderID field, you can put your code here to work with the properties of that field.

Implicit reference - cycling through the sections

If you are planning to work with a number of different kinds of report objects, you can cycle through the sections, test each of the report objects for kind, and manipulate them as you wish. You can do that using code similar to this:

Dim CRXReport As New CrystalReport1

Dim CRXTables As CRAXDRT.DatabaseTables

Dim CRXTable As CRAXDRT.DatabaseTable

Dim CRXSections As CRAXDRT.Sections

Dim CRXSection As CRAXDRT.Section

Dim CRXSubreportObj As CRAXDRT.SubreportObject

Dim CRXReportObjects As CRAXDRT.ReportObjects

Dim CRXReportObject As Object

Note: You put this code in the Form_Load event of the startup form which contains the Report Viewer.

Start by getting the sections from the Main report.

Set CRXSections = CRXReport.Sections

You begin cycling through each section in the main report.

For Each CRXSection In CRXSections

In each section, you get all the objects in the section.

Set CRXReportObjects = CRXSection.ReportObjects

You cycle through the objects.

For Each CRXReportObject In CRXReportObjects

You test the objects to see if they're subreports.

If CRXReportObject.Kind = crSubreportObject Then

When you find a subreport, you get a hold of it.

Set CRXSubreportObj = CRXReportObject

Before you work with an object in a report, you have to reference it (open it).

Implicit reference—through a collection

If you are planning to work with a specific kind of report object, you can access the object by referencing the collection that contains that object. You reference a collection in a report through the appropriate Report property. Those properties, and the collections they get, are as follow.

Property | Gets
Areas | Areas collection (Areas)
Database.DatabaseTables | Database Tables collection
FormulaFields | Formula Fields collection (FormulaFieldDefinitions)
GroupNameFields | Group Name Fields collection (GroupNameFieldDefinitions)
RunningTotalFields | Running Total Fields collection (RunningTotalFieldDefinitions)
GroupSortFields | Group Sort Fields collection (SortFields)
ParameterFields | Parameter Fields collection (ParameterFieldDefinitions)
RecordSortFields | Record Sort Fields collection (SortFields)
Sections | Section collection (Sections)
SQLExpressionFields | SQL Expression Fields collection (SQLExpressionFieldDefinitions)
SummaryFields | Summary Fields collection (SummaryFieldDefinitions)

Once you have the collection, you can cycle through the collection to locate the appropriate object you want. The following example shows you how to access the FormulaFieldDefinitions collection:

You can put this code in the General Declarations.

Dim CRXReport As New CrystalReport1

Dim CRXFormulaField As CRAXDRT.FormulaFieldDefinition

You can put this code in the Form_Load event procedure.

Private Sub Form_Load()

This code gets the collection.

Set CRXFormulaFields = CRXReport.FormulaFields

'You can put your code here to cycle through the collection

'to get the specific object you want

Finally you can view the report.

Crviewer1.ReportSource = CRXReport

Crviewer1.ViewReport

End Sub

Referencing objects in a subreport

Before you work with a subreport, you have to reference it (open it). Similar to referencing objects in a report, you can do this either explicitly or implicitly.

Explicit reference—the subreport itself

Assume that in your report you have a subreport with the Name property "Orders." Since you know the subreport name, you can use code similar to this to reference that subreport directly:

Dim CRXReport As New CrystalReport1

Dim CRXSubReport As SubreportObject

Set CRXSubReport = CRXReport.Orders

Note: Now that you have the subreport, you can add code to manipulate the subreport.

Explicit reference—an object in the subreport

Assume that in your report you have a subreport with the Name property "Orders" and that, in that subreport, you have a field with the Name property "OrderID." Since you know the subreport and field names, you can use code similar to this to reference the OrderID field directly:

Dim CRXReport As New CrystalReport1

Dim CRXSubReport As SubreportObject

Set CRXSubReport = CRXReport.Subreport1

Dim CRXSubReportField As FieldObject

Set CRXSubReportField = CRXReport.Orders_OrderID

Now that you have the OrderID field, you can add code to work with the properties of that field.

Please note the special way you reference a field in a subreport by name. You must use:

  • The name of the subreport.
  • An underscore.
  • The name of the field.

The result, in this example, Orders_OrderID, appears to be a field in myReport with the name Orders_OrderID. It is actually a field in the Orders subreport; the program uses dynamic type info to generate these names at runtime. You can find the names by looking at the Project in the Object Browser.

Implicit reference

Though this approach is more complex, it is not bound to a particular report, and the code can be reused with minor modifications for other reports that contain subreports. You can use code similar to the following to access any and all subreport(s) in a particular report.

You can declare the Variables in the General Declarations section of a form.

Dim CRXReport As New CrystalReport1

Dim CRXTables As CRAXDRT.DatabaseTables

Dim CRXTable As CRAXDRT.DatabaseTable

Dim CRXSections As CRAXDRT.Sections

Dim CRXSection As CRAXDRT.Section

Dim CRXSubreportObj As CRAXDRT.SubreportObject

Dim CRXReportObjects As CRAXDRT.ReportObjects

Dim CRXSubreport As CRAXDRT.Report

Dim CRXReportObject As Object

You put this code in the Form_Load event of the startup form which contains the Report Viewer.

You start by getting the sections from the Main report.

Set CRXSections = CRXReport.Sections

You begin by cycling through each section in the main report.

For Each CRXSection In CRXSections

In each section, you get all the objects in the section.

Set CRXReportObjects = CRXSection.ReportObjects

You cycle through the objects.

For Each CRXReportObject In CRXReportObjects

You test the objects to see if they're subreports.

If CRXReportObject.Kind = crSubreportObject Then

When you find a subreport, you get a hold of it.

Set CRXSubreportObj = CRXReportObject

Finally, you open the subreport and treat it as you would any other report.

Set CRXSubreport = CRXSubreportObj.OpenSubreport

Note: This is where you put the code for manipulating the subreport.

End If

Next CRXReportObject

Next CRXSection


Runtime examples

The following topics are discussed in this section:

  • Working with Cross-Tabs.
  • Working with Data sources.
  • Working with formatting.
  • Working with formulas/selection formulas.
  • Working with grouping.
  • Working with parameter fields.
  • Working with OLE objects.
  • Working with sorting.
  • Working with summary fields.
  • Working with text objects.


Working with Cross-Tabs

Modifying a cross-tab at runtime

A CrossTabObject object in the Report Designer represents a single cross-tab in your report. Cross-tabs are specialized subreports. Even if you design your primary report as a cross-tab, it is added to the report page as a separate object inside the report.

CrossTabObject objects can be obtained from a report much like subreports. A CrossTabObject is implemented as a single report object accessible through the ReportObjects collection.

The following code searches for cross-tabs in a report and applies formatting features to make them stand out from the rest of the report.

Dim CRXReport As New CrystalReport1

Dim CRXXtObject As CRAXDRT.CrossTabObject

Dim CRXSection As Section

Dim CRXReportObject As Object

For Each CRXSection In Report.Sections

For Each CRXReportObject In sect.ReportObjects

If CRXReportObject.Kind = crCrosstabObject Then

Set CRXXtObject = CRXReportObject

CRXXtObject.BorderColor = RGB(255, 0, 0)

CRXXtObject.HasDropShadow = True

Set CRXXtObject = Nothing

End If

Next

Next

Although cross-tabs are much like subreports, because of their specialized handling of data, there are fewer properties available to the CrossTabObject object than to the SubreportObject object. Before trying to use a property with a cross-tab in your report, verify that the property is available to the CrossTabObject object.


Working with Data sources

Changing an ADO data source location—two methods

In Crystal Reports 9 and higher, there are two methods to add ADO data sources to a report:

  • AddADOCommand takes as parameters an active ADO connection and an ADO command object. In this example, a new connection is created to a database, and the resulting recordset is assigned at runtime to the report.
  • AddOLEDBSource takes as parameters the name of an active ADO connection and the name of a table that can be accessed through that connection.

In this example, a connection set up through the VB Data Environment is used as a data source. Both methods can be used with either the VB Data Environment or another data source created at runtime.

Option Explicit

Dim CRXReport As New CrystalReport1

The ADO connection to the local database.

Dim cnn1 As ADODB.Connection

Dim datcmd1 As ADODB.Command

Demonstrate the use of AddADOCommand by opening an ADO data command and adding the data source to the report.

Private Sub cmdADO_Click()

Dim strCnn As String

Open the data connection.

Set cnn1 = New ADODB.Connection

strCnn = "Provider=MSDASQL;Persist Security Info=False;Data Source=Xtreme Sample Database 11;Mode=Read"

cnn1.Open strCnn

Create a new instance of an ADO command object.

Set datcmd1 = New ADODB.Command

Set datcmd1.ActiveConnection = cnn1

datcmd1.CommandText = "Customer"

datcmd1.CommandType = adCmdTable

Add the data source to the report.

CRXReport.Database.AddADOCommand cnn1, datcmd1

End Sub


Adding a data source and a field using AddOLEDBSource

This section demonstrates the use of AddOLEDBSource. One line of code:

  • Opens an ADO data source.
  • Adds the data source to the report.
  • Adds a field to the report that uses that data source.

In this example, an OLEDB source created in a VB Data Environment is used.

CRXReport.Database.AddOLEDBSource DataEnvironment1.Connection1,"Customer"


Setting the data source for a subreport

This section describes how to change the database location for different types of data sources:

  • Native
  • ODBC
  • Active Data

You change the database location (change the data source) for a subreport in much the same way as you set the database location for the main report. Before you can change the database location for a subreport, you first need to open the subreport. For more information, see Referencing objects in a subreport.

Once you have opened the subreport you can change the database location. The following examples show you how to do that for a variety of different types of data sources.


Native connection to PC database

If the data source of the subreport is a PC-type database (for example, MS Access), and the report is connecting natively, then you can use code similar to the following:

  1. Get the Tables collection for the subreport.

    2. Set CRXTables = CRXSubreport.Database.Tables

  2. Get the first table from the Tables collection.

    3. Set CRXTable = CRXTables.Item(1)

  3. Finally, set the location of the .mdb file.

    4. CRXTable.Location = "C:\My_Application\My_DB.mdb"

Native connection to SQL database

If the data source of the subreport is of an SQL-type (for example, MS SQL Server), and the report is connecting natively, then you can use code similar to the following:

  1. Get the Tables collection for the subreport.

    2. Set CRXTables = CRXSubreport.Database.Tables

  2. Get the first table from the Tables collection.

    3. Set CRXTable = CRXTables.Item(1)

  3. Finally, set the location of the .mdb file.

    4. CRXTable.SetLogOnInfo <servername>, <databasename>, <userid>, <password>


ODBC connection to a PC or SQL database

If the data source of the subreport is a PC-type (for example, MS Access) or SQL-type (for example, MS SQL Server), and the report is connecting via ODBC, you can use code similar to the following:

  1. Get the Tables collection for the subreport.

    2. Set CRXTables = CRXSubreport.Database.Tables

  2. Get the first table from the Tables collection.

    3. Set CRXTable = CRXTables.Item(1)

  3. Finally, set the location of the .mdb file.

    4. CRXTable.SetLogOnInfo <ODBC_DSN>, <databasename>, <userid>, <password>


Active data connection to a PC or SQL database

If the data source of the subreport is an active data source (for example, DAO, RDO, ADO, CDO, and so on), and the report is connecting using the active data driver, then you can use code similar to the following:

  1. Get the Tables collection for the subreport.

    2. Set CRXTables = CRXSubreport.Database.Tables

  2. Get the first table from the Tables collection.

    3. Set CRXTable = CRXTables.Item(1)

  3. Finally, set the location of the.mdb file.

    4. CRXTable.SetDataSource rs, 3

There are many ways that you can access a subreport, and change the database location for a subreport. The above examples are simplified and generic so that they can be used and altered to accommodate an application with any report.


Connecting to OLEDB providers

Each OLEDB provider requires a specific connection string. The following sample connection strings are for use in the "Connection" input box of the "ADO and OLE DB" option on the "Select Data Source" dialog box for the Active Data report expert.


Microsoft Jet 3.51 OLE DB Provider

Provider=Microsoft.Jet.OLEDB.3.51;Data Source=c:\Access\Northwind.mdb

Note: At this time, it is not possible to use secured Access databases in the Crystal Report expert.

  • This OLE DB provider appears to only work with 32-bit Access databases.
  • Notice that the database table and query names do not appear in the drop-down boxes. This has been tracked. The option is to use the SQL textbox instead.


Microsoft OLEDB Provider for SQL Server
Syntax

Provider=SQLOLEDB;SERVER=SName;DATABASE=DBName; UID=MyID; PWD=MyPWD

Example

Provider=SQLOLEDB;Server=TechTest;Database=Pubs;UID=Admin;PWD=sa


Microsoft OLEDB Provider for ODBC Drivers
Syntax

Provider=MSDASQL;DSN=MyDSN;UID=MyUID;PWD=MyPassword

Example

For secured Data Sources:

Provider=MSDASQL;DSN=Xtreme Sample Database 11;UID=Admin;PWD=Password

For non-secured data sources type the DSN:

Xtreme Sample Database 11

Note: If it is OLE DB that is being used as the provider for ODBC, select the first option of the "Select Data Source" dialog box ("ODBC(ADO)") which uses that specific provider by default.


Microsoft OLEDB Provider for Oracle
Syntax

Provider=MSDAORA;Password=;User ID=;Data Source=

Example

Provider=MSDAORA;Password=MyPassword;User ID=Admin;Data

Source=MyOracleServer

Note: It will probably be necessary to re-type the UserID and Password in the corresponding text boxes of the Select Recordset dialog box.


Connecting to a secure Access session

If your reports connect to secure Microsoft Access sessions, you must provide session information at runtime using the SetSessionInfo method of the DatabaseTable object. This method accepts a user ID and password that are passed to the Access session to provide a connection to the database.

Session information must be added to your code using the SetSessionInfo method, even if you specified session information at design time. Session information specified at design time is not stored with the Report Designer Component.

Assuming all tables in your report are from the same secured Access database, you can use code similar to the following to set the Access session information:

Dim CRXReport As New CrystalReport1

Dim CRXTable as CRAXDRT.DatabaseTable

For Each CRXTable In CRXReport.Database.Tables

CRXTable.SetSessionInfo "user", "password"

Next

Working with secure data in reports

If your report connects to a secure data source that requires log on information, you will not be able to log off of the data source until the Report object has been closed or has gone out of scope. Keep in mind that if you assign the Report object to the ReportSource property of the CRViewer object in the Crystal Reports Report Viewer, the Report object cannot be closed until you assign a new value to the Report Viewer or close the CRViewer object. Thus, you will not be able to log off of a secure data source until the report is no longer displayed in the Report Viewer.


Working with formatting

Using Report Variables

Certain events, like the OnSectionFormat event, may get fired more than once in a section. For example, a Details section may fire multiple times for a given record if the program is performing "Keep Section Together" calculations for the report. When you are using VB variables that are supposed to increment once for each record (as when you are calculating a running total), you can have problems maintaining state with these multiple firings.

To prevent these problems, the RDC now enables you to declare Report Variables. Report variables are Crystal variables that you can use in your VB code. Report Variables understand what's occurring in the report and they increment appropriately. This enables you to do more of your coding than ever in VB and still get the results you expect.

There are three methods you use with report variables.

AddReportVariable

You use AddReportVariable to declare a Report Variable. The following code declares four Report Variables:

  • CurrencyVal of the type currency.
  • LongVal of the type number.
  • DoubleVal of the type number.
  • StringVal of the type string.

    • AddReportVariable crRVCurrency, "CurrencyVal"

    AddReportVariable crRVNumber, "LongVal"

    AddReportVariable crRVNumber, "DoubleVal"

    AddReportVariable crRVString, "StringVal"

GetReportVariableValue

You use GetReportVariableValue to reference the value in a Report Variable. The following code references the value in the Report Variable, CurrencyVal.

CurVal = GetReportVariableValue("CurrencyVal")

SetReportVariableValue

You use SetReportVariableValue to increment a Report Variable. The following code sets the value of the Report Variable CurrencyVal to the value of the expression "CDbl(CurVal) + CDbl(FieldCurrency.Value)".

SetReportVariableValue "CurrencyVal", CDbl(CurVal) + CDbl(FieldCurrency.Value)

Note that you can only use Report Variables at runtime and that you must use double quotes every time you reference such a variable.


Formatting a section or report object conditionally

You can now do conditional formatting using VB code. Crystal Reports has allowed this in the past with its own formula language but now you can do it in VB code as well.

This Format event is fired each time this section is formatted, so you can get the values of the object and perform a variety of formatting functions.

This first example changes the backcolor of the section itself if the value of the selected field is less than 50000.

Private Sub Section6_Format(ByVal pFormattingInfo As Object)

If Field9.Value < 50000 Then

Section6.BackColor = vbRed

Else

Section6.BackColor = vbWhite

End If

End Sub

The second example changes the color of the text in the selected field if the value of that field is less than 50000.

Private Sub Section6_Format(ByVal pFormattingInfo As Object)

If Field9.Value < 50000 Then

Field9.TextColor = vbRed

Else

Field9.TextColor = vbGreen

End If

End Sub


Working with formulas/selection formulas

Passing a selection formula at runtime

When you pass the selection formula to Crystal Reports, you use the RecordSelectionFormula property of the Report object.

Note: Formulas must conform to the Crystal Reports formula syntax (that is, strings embedded in single quotes while numbers not, and so on). For Crystal Reports to parse a formula it receives from the application (Visual Basic in this case), the formula must be identical to a formula that you would enter directly into the report designer. You can use the MsgBox function in Visual Basic to verify that the formula string being sent from VB is in a format that can be used by Crystal Reports.

Two ways you can use the RecordSelectionFormula property of the Report object are:

  • Hardcoding: you can copy your code from your report and paste it into the code.
  • Using a variable: you can append the value of a variable onto your code when calling the RecordSelectionFormula property.

    • CRXReport.RecordSelectionFormula = "{Customer.Region} = 'CA'"

Note: Any dates passed to Crystal Reports must be in Crystal Reports Date format, Date(yyyy,mm,dd).


Passing a formula at runtime

When passing a value to Crystal Reports, you use the Text property of the FormulaFieldDefinition object.

First, you create your formula using the Crystal Reports formula language.

  • If you are giving it a string value, you must place a string value in it. This will force the program to treat the formula as a string.
  • A single space inside double quotes is a good idea, since this will not print if left unchanged—yet it holds the string type for when you change the actual value later from VB.

Place the new formula on your report where you would like to display the passed value.

If you will be sending a numeric value or date, again place an appropriate value in the formula in order to establish the data type of the formula.

  • To pass a numeric value to a formula, place 0 in the formula when you create the formula in Crystal Reports.
  • To pass a date value to a formula, place the Today function in the formula.

The following code shows how you can send a title to your report from your VB application. As instructed above, a formula is inserted at the top of the report, and is named Title. It presently contains a space inside quotes, as in " ".

Sub Command1_Click ()

'if we hard-code the title

CRXReport.FormulaFields.Item(1).text = "'Report Title'"

'If we use the value of the Textbox

Text1.Text = "This is a Title"

CRXReport.FormulaFields.Item(1).text = chr(34) & Text1.text & chr(34)

End Sub

The following code changes the value of a numeric formula at runtime.

Sub Command1_Click ()

'if we hard-code the numeric value

CRXReport.FormulaFields.Item(1).text = "9"

'If we use the value of a variable

x = 65

CRXReport.FormulaFields.Item(1).text = x

End Sub


Changing a subreport's record selection formula at runtime

Changing the record selection formula for a subreport is similar to changing it for the main report. Before you can change the record selection formula for a subreport, you first must open the subreport. Please refer to Referencing objects in a subreport for examples of different ways you can access a subreport.

Once you have opened the subreport object, you can use code similar to this to change its record selection formula.

CRXSubreport.RecordSelectionFormula = "{Customer.Last Year's Sales} > 100000"

The subreport acts like any report, where any object, property, and method that is accessible by the Report object is the same for a subreport. The only limitation is that subreports cannot be previewed, printed, or exported as an individual report.


Referencing a report formula using the formula name

The following code sample shows how to reference a report formula at runtime using the formula name instead of referencing the formula by index.

You can put this code in the General Declarations.

Dim CRXReport As New CrystalReport1

Dim CRXFormulaFields As CRAXDRT.FormulaFieldDefinitions

Dim CRXFormulaField As CRAXDRT.FormulaFieldDefinition

You can put this code in the Form_Load event procedure.

Private Sub Form_Load()

Set CRXFormulaFields = CRXReport.FormulaFields

Now you can cycle through the formula fields collection.

For Each CRXFormulaField In CRXFormulaFields

Here you find the formula you require by specifying its name. Note the format that the .Name property returns.

If CRXFormulaField.Name = "{@formula}" Then

Now you set the formula text.

CRXFormulaField.Text = "{Customer.Name}"

End If

Next

Finally, you can view the report.

Crviewer1.ReportSource = CRXReport

Crviewer1.ViewReport

End Sub


Working with grouping

Changing the existing group's condition field

For this scenario, assume that a report has been created which is currently grouped on the City field (for example, {Customer.City}). To change the condition field for the existing field at runtime, you can use the following code.

Note: This code assumes that you know which field you want to change and that there is only one group in the report.

You can place this code in the General Declarations section.

Dim CRXReport As New CrystalReport1 'The existing report (ActiveX Designer)

Dim CRXDBField As CRAXDRT.DatabaseFieldDefinition

You can put this code in the FORM_LOAD event procedure.

Private Sub Form_Load()

Currently the group is based on the CITY field, but you want to change it to the REGION field. This code accesses the first table to get the 12th field which is the REGION field.

set CRXDBField = CRXReport.Database.Tables.Item(1).Fields.Item(12)

Now you can set the new condition field for the existing group. Since you know that there is only one group in the report, you can reference it by its name "GH."

CRXReport.Areas.Item("GH").GroupConditionField = CRXDBField

Finally, display the report.

CRViewer1.ReportSource = CRXReport

CRViewer1.ViewReport

End Sub


Adding a new group to the report

For this scenario, assume that a report has been created and it does not contain any groups. To add a new group to the report at runtime, you can use code similar to the following:

Note: Please note that using this method will not display the group name on the report.

You can place this code in the General Declarations section.

Dim CRXReport As New CrystalReport1 'The existing report (ActiveX Designer)

Dim CRXDBField As CRAXDRT.DatabaseFieldDefinition

You can place this code in the FORM_LOAD event procedure.

Private Sub Form_Load()

For this example, you want to add a group that is based on the REGION field. This code accesses the first table to get the 12th field, which is the REGION field.

set CRXDBField = CRXReport.Database.Tables.Item(1).Fields.Item(12)

Now you can add the new group to the report. Please note that:

  • 0 is the GroupNumber in case you add more than one group.
  • CRXDBField is the ConditionField.
  • crGCAnyValue is the condition on which the group changes.
  • crAscendingOrder is the SortDirection.

    • CRXReport.AddGroup 0, CRXDBField, crGCAnyValue, crAscendingOrder

Finally, display the report.

CRViewer1.ReportSource = CRXReport

CRViewer1.ViewReport

End Sub


Adding a group sort field

This scenario requires a report that already contains a group which also must contain a summary field.

A Group Sort Field can only exist if the group contains a summary field, because that summary field is what the Sort is based on. In this example, the report is grouped on {Customer.Region} and the summary field is the "SUM of Customer.Last Year's Sales (Currency)."

To add a group sort field you can use code similar to the following:

  1. Place this code in the General Declarations section.

    2. Dim CRXReport As New CrystalReport1 'The existing report (ActiveX Designer)

    Dim CRXSortFields As CRAXDRT.SortFields

    Dim CRXSummaryField As CRAXDRT.SummaryFieldDefinition

  2. Place this code in the FORM_LOAD event procedure.

    3. Private Sub Form_Load()

  3. This code gets the SortFields collection for the groups:

    4. Set CRXCRXSortFields = CRXReport.GroupSortFields

  4. Get the first Summary Field which is the "SUM of Customer.Last Year's Sales (Currency)."

    5. Set CRXSummaryField = CRXReport.SummaryFields.Item(1)

  5. Now add the Group Sort Field.

    6. CRXSortFields.Add CRXSummaryField, crDescendingOrder

  6. Finally, display the report.

    7. CRViewer1.ReportSource = CRXReport

    CRViewer1.ViewReport

    End Sub


Modifying a group's sort direction at runtime

You can change a group's sort direction through the SortDirection property of the Area Object. To change a group's sort direction you can use code similar to the following.

Note: All the samples are based on the sample database, XTREME.MDB, which is installed by Crystal Reports.

  1. Put this code in the General Declarations section.

    2. Dim CRXReport As New CrystalReport1

  2. Put this code in the FORM_LOAD event procedure.

    3. Private Sub Form_Load()

    The Item parameter "GH1" refers to the first group header; to access the second group header you would use "GH2" This line of code sets the SortDirection to descending.

    CRXReport.Areas.Item("GH1").SortDirection = crDescendingOrder

  3. Finally, view the report.

    4. CRViewer1.ReportSource = CRXReport

    CRViewer1.ViewReport

    End Sub


Working with parameter fields

Crystal parameters and stored procedure parameters and are both set through the ParameterFieldDefinition Object. The following sample code passes four parameters to a report. The Main Report and the Subreport each have a Stored Procedure and a Crystal Parameter.

This code can go in the General Declarations Section.

Private Sub Command1_Click()

Dim CRXParamDefs As CRAXDRT.ParameterFieldDefinitions

Dim CRXParamDef As CRAXDRT.ParameterFieldDefinition

Dim CRXSubreport As CRAXDRT.Report

Set CRXParamDefs = CRXReport.ParameterFields

This code cycles through the ParameterFieldDefinitions collection in the main report.

For Each CRXParamDef In CRXParamDefs

With CRXParamDef

Select Case .ParameterFieldName

It finds and sets the appropriate Crystal parameter.

Case "MainParam"

.SetCurrentValue "Main Report Parameter"

Now it finds and sets the appropriate stored procedure parameter.

Case "[CustomerID]"

.SetCurrentValue "Alfki"

End Select

End With

Next

It opens the appropriate subreport.

Set CRXSubreport = CRXReport.OpenSubreport("sub1")

Set CRXParamDefs = CRXSubreport.ParameterFields

It cycles through the ParameterFieldDefinitions collection for the subreport.

For Each CRXParamDef In CRXParamDefs

With CRXParamDef

MsgBox .ParameterFieldName

Select Case .ParameterFieldName

It finds and sets the appropriate Crystal parameter for the subreport.

Case "SubParam"

.SetCurrentValue "Subreport Parameter"

Now it finds and sets the appropriate stored procedure parameter for the subreport.

Case "[CustomerID]"

.SetCurrentValue "Anton"

End Select

End With

Next

Finally, it disables parameter prompting so the user won't be prompted for a value.

CRXReport.EnableParameterPrompting = False

CRViewer1.ReportSource = CRXReport

CRViewer1.ViewReport

End Sub


Working with OLE objects

Setting the location of an OLE object

This example demonstrates how you can set the location of an OLE object at Runtime using the SetOleLocation command. The example takes three different OLE objects:

  • A bitmap.
  • Part of an Excel worksheet.
  • Part of a Word document.

It cycles through them so the RDC prints a different object each time it formats the Details section.

Option Explicit

Private Sub Report_Initialize()

Database.Tables(1).Location = App.Path + "\Author.mdb"

End Sub

Private Sub SectionDetails_Format(ByVal pFormattingInfo As Object)

Object to hold the bitmap:

Dim bmpHold As StdPicture

Dim iModNum As Integer

Calculate an integer to pass in as the object name.

iModNum = cRecNum.Value Mod 3 + 1

Take an action based on the integer passed in.

Select Case iModNum

The bitmap object:

Case 1

Set the variable to a bitmap.

Set bmpHold = LoadPicture(App.Path & res\SampleBitmap1.bmp")

Set the height and width of the Report object equal to the actual values for the bitmap - the StdPicture object defaults to HiMetric, the Report uses twips.

Set the bitmap on the Report equal to the variable.

Set cOLEObj.FormattedPicture = bmpHold

Convert from HiMetric to twips.

cOLEObj.Height = bmpHold.Height * 567 / 1000

cOLEObj.Width = bmpHold.Width * 567 / 1000

The Excel Worksheet object:

Case 2

cOLEObj.SetOleLocation App.Path & "\res\SampleExcel1.xls"

cOLEObj.Height = 1800

cOLEObj.Width = 5791

The Word Document object:

Case 3

cOLEObj.SetOleLocation App.Path & "\res\SampleWord1.doc"

cOLEObj.Height = 322

cOLEObj.Width = 8641

End Select

End Sub


Working with sorting

Changing the existing sort's condition field

For this scenario, a report is created which is currently sorted on the Customer Name field (for example, {Customer.Customer Name}). To change the condition field for the existing field at runtime, the following code can be used:

'General Declarations

Dim CRXReport As New CrystalReport1

Dim CRXDatabaseField As CRAXDRT.DatabaseFieldDefinition

Private Sub Form_Load()

Currently the sort is based on the Customer Name field and the application is to change it to the Last Year's Sale's field. This field must be present on the report. The code accesses the first table to get the 8th field.

Set CRXDatabaseField = CRXReport.Database.Tables.Item(1).Fields.Item(8)

There is only one Sort on this report so you will access the first item of the SortFields collection and set the field to the Last Year's Sale's field.

CRXReport.RecordSortFields.Item(1).Field = CRXDatabaseField

CRViewer1.ReportSource = CRXReport

CRViewer1.ViewReport

End Sub


Adding a new sort field to a report

In this example, you're going to add a sort field that currently isn't sorted.

You can put code like this in the General Declarations section.

Dim CRXReport As New CrystalReport1

Dim CRXDatabaseField As CRAXDRT.DatabaseFieldDefinition

Private Sub Form_Load()

Currently there is no sort in this Report. To add the sort field Customer Name, the application must first get the {Customer.Customer Name} field from the Customer Table. This code accesses the first table to get the 2nd field.

Set CRXDatabaseField = CRXReport.Database.Tables.Item(1).Fields.Item(2)

Now add the field to the SortFields Collection and set the Sort Order to ascending.

CRXReport.RecordSortFields.Add CRXDatabaseField, crAscendingOrder

Note: If the SortField is added while the Report is viewing, you will have to refresh the viewer before the new sort will be active. This can be done by clicking the Refresh button in the Report Viewer or refreshing the viewer through code. For example:

CRViewer1.Refresh

CRViewer1.ReportSource = CRXReport

CRViewer1.ViewReport

End Sub


Working with summary fields

How to change summary field kind

This example populates a combo box with the various summary field kind options and then sets a summary field to the kind selected. This code assumes that you have elsewhere declared a variable cr for your report.

Private Sub Form_Load()

Dim i As Integer

Populate the combo box.

cmbSummaryType.AddItem "crSTSum"

cmbSummaryType.AddItem "crSTAverage"

cmbSummaryType.AddItem "crSTSampleVariance"

cmbSummaryType.AddItem "crSTSampleStandardDeviation"

cmbSummaryType.AddItem "crSTMaximum"

cmbSummaryType.AddItem "crSTMinimum"

cmbSummaryType.AddItem "crSTCount"

cmbSummaryType.AddItem "crSTPopVariance"

cmbSummaryType.AddItem "crSTPopStandardDeviation"

cmbSummaryType.AddItem "crSTDistinctCount"

Get the SummaryFields collection.

Set CRXSummaryFieldDefinitions = CRXReport.SummaryFields

txtCount = CrystalSummaryFieldDefinitions.Count

Cycle through the collection.

For i = 1 To CRXSummaryFieldDefinitions.Count

Set CRXSummaryFieldDefinition =

CRXSummaryFieldDefinitions.Item(i)

lstFieldDefinition.AddItem CRXSummaryFieldDefinition.Name

Next i

End Sub

Change the summary field kind.

Private Sub lstFieldDefinition_Click()

Set CRXSummaryFieldDefinition = CRXSummaryFieldDefinitions.Item(lstFieldDefinition.ListIndex + 1)

With CRXSummaryFieldDefinition

cmbSummaryType.Text = cmbSummaryType.List(.SummaryType)

txtKind = .Kind

txtName = .Name

txtNumberofBytes = .NumberOfBytes

txtValue = OnFormat

txtValueType = .ValueType

End With

End Sub


Working with text objects

Simple and complex text objects

There are two types of text objects: simple and complex.

  • Simple text objects are processed internally by the report engine.
  • Complex complex text objects are handled by CRPAIG32.DLL.

Only complex text objects can handle carriage returns and line feeds.

If you want to use carriage returns and line feeds in your text object, you will need to force the text object to be complex. To do this, double-click on the text object to edit it and enter a carriage return (press the enter key) inside of it. Then, when carriage returns and line feeds are passed to the text object through your code, the RDC will process them properly.


Changing the contents of a text object

You can use text objects in a variety of different ways:

  • You can use a text object in a simple way to personalize a report based on your users' input (changing the report title, for example).
  • You can also use a text object to display the results of complex operations on database data.

Text objects are very flexible and powerful reporting tools.

To change the contents of a text object you use the SetText method.

  • The Text property of the object model's TextObject gives you information about the existing value; it is a read-only property however.
  • To assign a new value to the property, you must use the SetText method.

Note: The following examples change the contents of a text object during the Load event of the Form containing the Crystal Report Viewer ActiveX control. This is especially important if the value of your text object is dependent on data in your data source. Since this is also a common place to change the data source used by a report, changing values in text objects during the Load event often becomes convenient.

Making a simple text change

This example simply assigns a string to the Text1 object in the report.

Private Sub Form_Load()

Dim CRXReport As New CrystalReport1

' More code here

CRXReport.Text1.SetText "Here is some text from my app"

CRViewer1.ReportSource = CRXReport

CRViewer1.ViewReport

End Sub

Displaying a calculated result

A more complicated technique may be to access data in a database, calculate a new value in Visual Basic, and then display that value through a text object on the report. In such cases, you can supply a text object for each result when you design your report in RDC Designer. The following code assumes that you have done this:

Private Sub Form_Load()

Set up the variables.

Dim maxValue As Currency

Dim maxValueString As String

Dim CRXReport As New CrystalReport1

Dim rs As New ADODB.Recordset

Set your data source.

rs.Open "SELECT * FROM Customer", _

"DSN=Xtreme Sample Database 11;", adOpenKeyset

CRXReport.Database.SetDataSource rs

maxValue = 0

Read the records and calculate the results.

rs.MoveFirst

Do While Not rs.EOF

If rs.Fields("Last Year's Sales") > maxValue Then

maxValue = rs.Fields("Last Year's Sales")

End If

rs.MoveNext

Loop

Format and assign the results to the text object.

maxValueString = "The maximum value is " & _

Format(maxValue, "Currency")

CRXReport.Text1.SetText maxValueString

Preview the report.

CRViewer1.ReportSource = CRXReport

CRViewer1.ViewReport

End Sub

In this example, you are finding the maximum value of the Last Year's Sales field from the new data source, formatting that value as Currency, then displaying a message containing the value through a text object on the report. As you can see, text objects provide many options for controlling the output of data in your reports.


Programming the Crystal Report Viewers

The Crystal Report Viewer is a front-end user interface for viewing reports. In this section you will find detailed information on implementing the ActiveX and Java Bean viewers in your application.

Click the appropriate link to jump to that section:

  • Crystal Report Viewer for ActiveX
  • The Crystal Report Java Plugin Viewer


Application Development with Crystal Report Viewers

Developing applications that display reports on screen is now a straightforward process. Crystal Reports includes the Crystal Report Viewers as easy to use but complex components that can be embedded directly in an application. Once added to an application, reports accessed through the Report Engine Automation Server, the Report Designer Component, or the Crystal Web Reports Server can be displayed right inside your own applications. The Report Viewer retains all of the powerful formatting, grouping, and totalling power of the original report, and your users get access to data in a dynamic and clear format.

Crystal Reports provides two Report Viewers specifically designed for application development: the Crystal Report Viewer for ActiveX and the Crystal Report Java Plugin Viewer. Both provide a complete object model for programming and manipulating the Report Viewer at runtime inside your applications. Simply displaying a single report inside the Report Viewer is a simple process requiring only a couple of lines of code. However, if necessary for your application, you have the option of complete control over how the Report Viewer appears and functions.

With the Crystal Report Viewer as a front-end user interface for viewing reports, Crystal Reports development technologies allow you to develop even complex client/server or multi-tier applications that access, manipulate, and display data for intranet systems, workgroups, or any group of people needing clear and informative data on a regular basis. Design robust Business Support systems and Enterprise Information Management applications delivering even the most complex data through the Crystal Report Viewers.

This chapter describes both the ActiveX and Java Plugin versions of the Report Viewer in relation to designing applications using Crystal Reports development technologies.


Crystal Report Viewer for ActiveX

The Crystal Report Viewer for ActiveX is a standard ActiveX control that can be added to an application in any development environment that supports ActiveX. Programmers using Visual Basic, Delphi, Visual C++, or Borland C++ programmers all receive the benefit of quickly adding a powerful report viewer to an application with little coding.

As a standard component, the ActiveX Report Viewer exposes several properties at design time, but also provides a complete object model with properties, methods, and events that can be programmed at runtime. The following sections discuss various topics for working with the ActiveX Report Viewer in Visual Basic. If you are using a development environment other than Visual Basic, use these topics as a guideline, but refer to your development software documentation for specific information on working with ActiveX controls.

The Crystal Report Viewer, as an ActiveX control, includes a complete object model for controlling how it appears in an application, and how it displays reports. Simply displaying a report in the Report Viewer window takes little code, but to truly make use of its power requires a broader understanding of how to work with the object model.

Related topics: :

Adding the Report Viewer to a Visual Basic project

Using the CRViewer object


Adding the Report Viewer to a Visual Basic project

If you create a new report using the Create Report Expert in the Crystal Report Designer Component, the Crystal Report Viewer Control can be automatically added to a Form in your Visual Basic project. However, there may be times when you need to add the control by hand. In addition, the Crystal Report Viewer Control can be implemented in other environments, many of which may not support ActiveX designers, meaning the Create Report Expert is unavailable.

Use the following steps to add the Crystal Report Viewer ActiveX control to a Form in your Visual Basic application. This tutorial assumes the Form already exists in your project and is named Form1.

First, you must verify that a reference to the Crystal Report Viewer Control exists in your project.

  1. From the Project menu, select the Components command.

    2. The Components dialog box appears.

  2. On the Controls Tab of the Components dialog box, scroll through the list of ActiveX controls until you find Crystal Report Viewer Control.

    3. If you do not see the Crystal Report Viewer Control in the list, use the Browse button to locate the CRVIEWER.DLL component in the \Program Files\Common Files\Business Objects\3.0\crystalreportviewers11\ActiveXControls directory.

  3. If the check box next to the Crystal Report Viewer Control is not selected, select it on now.
  4. Click OK.

    5. The CRViewer control appears in the Visual Basic toolbox.

  5. Click the CRViewer control on the toolbox, then draw the Crystal Report Viewer Control on your form by dragging a rectangle across the form with the mouse pointer.

    6. An instance of the control will be added to your Form.

  6. Adjust the size and position of the Report Viewer on your form, and use the Properties window to adjust the overall appearance of the control.


Using the CRViewer object

The CRViewer object represents an instance of the Crystal Report Viewer Control that has been added to your project. If you have created a report using the Crystal Report Designer Component and accepted the defaults for adding the Report Viewer to your project, the Crystal Report Viewer Control in your application will be named CRViewer1. CRViewer1 can be used in your code as a CRViewer object. For instance, the following code demonstrates a simple technique for assigning a report to the Report Viewer, and displaying it:

CRViewer1.ReportSource = report

CRViewer1.ViewReport

For more information on the properties and methods available with this object, refer to the Report Viewer object model and the CRViewer object.

The topics listed below describe several aspects of the Report Viewer object model and present examples of how to use the Report Viewer objects, methods, properties and events in your Visual Basic code.

  • Specifying a report
  • Working with secure data in reports
  • Handling Report Viewer events
  • Moving through a report
  • Printing the report
  • Controlling the appearance of the Report Viewer


Specifying a report

The most important task with the Crystal Report Viewer Control is to specify a report and display it at runtime. This is easily handled with the ReportSource property and the ViewReport method.

Private Sub Form1_Load()

Dim report As New CrystalReport1

CRViewer1.ReportSource = report

CRViewer1.ViewReport

End Sub

In this example, assigning the report and displaying it in the Report Viewer is handled when the Form containing the Report Viewer object is loaded into the application. A reference to the report is first obtained in the form of a Report object representing a Crystal Report Designer Component that has been added to the Visual Basic project.

ReportSource is a property of the Report Viewer's CRViewer object which corresponds directly to the Crystal Report Viewer Control added to the project. In this case, that control has been named CRViewer1. The ReportSource property can accept a report in the form of a Report Object exposed by the Report Designer Component or the Crystal Web Reports Server.

Finally, the ViewReport method is called. This method has no parameters and has the job simply of displaying the specified report inside the Crystal Report Viewer Control.


Working with secure data in reports

If your report connects to a secure data source that requires log on information, you must release the Report object from the Report Viewer before you can log off of the data source. This can be done by assigning a new Report object to the ReportSource property, or by closing the CRViewer object. Until this is done, the data source will not be released from the Report object and you cannot log off.


Handling Report Viewer events

The Crystal Report Viewer Control allows you to write custom code for several events relating to user interaction with both the control window and the report displayed. For instance, if you design a drill down report using the Report Designer Component, your users are likely to want to drill down on detail data. You can provide custom handling of such an event by writing code fort the DrillOnGroup event.

To add event procedures to the Crystal Report Viewer Control for the DrillOnGroup and PrintButtonClicked events
  1. In the Visual Basic Project window, select the Form containing the Crystal Report Viewer Control.
  2. Click the View Code button in the toolbar for the Project window.

    3. A code window for the form appears.

  3. In the drop-down list box at the upper left hand corner of the code window, select the CRViewer1 control.

    4. (This name will appear different if you changed the Name property of the control in the Properties window.)

  4. In the drop-down list box at the upper right corner of the code window, select the DrillOnGroup event.

    5. A procedure appears for handling the event.

  5. Add the following code to the DrillOnGroup event procedure:

    6. Private Sub CRViewer1_DrillOnGroup(GroupNameList As Variant, _

    ByVal DrillType As CRVIEWERLibCtl.CRDrillType, _

    UseDefault As Boolean)

    MsgBox "You're drilling down on the " & GroupNameList(0) & " group!"

    End Sub

  6. In the drop-down list box at the upper right of the code window, select the PrintButtonClicked event.

    7. A new procedure appears for this event.

  7. Add the following code for the new event:

    8. Private Sub CRViewer1_PrintButtonClicked(UseDefault As Boolean)

    MsgBox "You clicked the Print button!"

    End Sub

The DrillOnGroup event is triggered when a user double-clicks a chart, a map, or a report summary field. The code added to the event procedure will display a message box with the name of the group. The PrintButtonClicked event is fired if the user clicks the print button on the Report Viewer window. Note that any code added to these event handlers replaces the default action of the event. A more practical use of these events would be to display custom dialogs or perform other report related calculations and procedures.


Moving through a report

Often, reports consist of several pages. The Crystal Report Viewer Control provides, by default, controls that allow a user to move through the pages of the report. However, you may need to implement a system through which your own code controls when separate pages are displayed.

The CRViewer object provides several methods for moving through a report, including methods to move to specific pages:

  • ShowFirstPage
  • ShowLastPage
  • ShowNextPage
  • ShowPreviousPage
  • ShowNthPage
  • GetCurrentPageNumber

And methods for moving to specific groups in the report:

  • ShowGroup
Moving through pages

The first set of methods designed for moving through the pages of a report are straightforward and correspond directly to controls that normally appear on the Crystal Report Viewer Control window. ShowFirstPage, ShowLastPage, ShowNextPage, and ShowPreviousPage simply switch to the first, last, next, or previous page in the report, respectively. They are all used in the same manner in code:

CRViewer1.ShowFirstPage

CRViewer1.ShowLastPage

CRViewer1.ShowNextPage

CRViewer1.ShowPreviousPage

If the requested page cannot be displayed, for instance, if the last page in the report is currently displayed and ShowNextPage is called, the currently displayed page will be refreshed.

For more controlled movements through the report, ShowNthPage can display a specific page of the report:

CRViewer1.ShowNthPage 5

This method accepts a page number as its only argument. If the selected page number does not exist, for example, page 10 is selected from a 6 page report, then either the last or first page will be displayed, depending on the page number requested.

As a convenience, the GetCurrentPageNumber method has also been included. You can obtain the currently displayed page from within your code at any time using this method:

Dim pageNum As Long

pageNum = CRViewer1.GetCurrentPageNumber

Moving to a specific group

Grouping is a common feature of reports, and, since page numbers can frequently change based on current data, it may be more appropriate to navigate through a report using groups. For example, if a report is grouped by cities within states, and by states within countries, you can include code to display the group for a specific city.


Printing the report

Although the Crystal Report Viewer Control is designed primarily for displaying reports on screen, users frequently want a hard-copy of the data. The PrintReport method provides printing functionality to the user. The following code demonstrates the use of the PrintReport method. (This example assumes that a report and viewer object have already been created and initialized.)

CRViewer1.ReportSource = Report

Set the PrintMode property to 0 for PDF printing, or 1 for ActiveX printing.

CRViewer1.PrintMode = 0

CRViewer1.PrintReport


Controlling the appearance of the Report Viewer

By default, the Report Viewer window includes several controls for allowing users to navigate through a report, enlarge the view of a report, refresh the data in a report, and more. There may be applications that you create in which you want to limit a user's interaction, change the look of the Report Viewer window, or provide an alternate means of accessing the same functionality.

For instance, you could turn off the navigation controls in the Report Viewer, then create your own controls to navigate through the report that call the ShowFirstPage, ShowLastPage, ShowNextPage, ShowPreviousPage, and ShowNthPage methods. (See Moving through a report.) For handling such custom features, the Report Viewer object model provides several properties for enabling and disabling different features of the Report Viewer ActiveX control:

  • DisplayBackgroundEdge
  • DisplayBorder
  • DisplayGroupTree
  • DisplayTabs
  • DisplayToolbar
  • EnableAnimationCtrl
  • EnableCloseButton
  • EnableDrillDown
  • EnableExportButton
  • EnableGroupTree
  • EnableHelpButton
  • EnableNavigationControls
  • EnablePopupMenu
  • EnablePrintButton
  • EnableProgressControl
  • EnableRefreshButton
  • EnableSearchControl
  • EnableSearchExpertButton
  • EnableSelectExpertButton
  • EnableStopButton
  • EnableToolbar
  • EnableZoomControl

Using these properties requires assigning a value of either True or False. True enables the specified control or feature of the Report Viewer, while False disables it.

Note: The EnableSearchExpertButton and EnableSelectExpertButton features are only availble when using the Report Viewer ActiveX control with the Report Designer Component.

The following code demonstrates how to disable the entire toolbar for the Report Viewer window:

CRViewer1.DisplayToolbar = False


The Crystal Report Java Plugin Viewer

The Crystal Report Java Plugin Viewer can be added to an application in any development environment that supports Java (version 1.1 or higher). Programmers receive the benefit of quickly adding a powerful report viewer to an application with little coding.

As a standard component, the Crystal Report Java Plugin Viewer exposes several properties at design time, but also provides a complete object model with properties, methods, and events that can be programmed at runtime. The following discusses one approach to creating an application using the Crystal Report Java Plugin Viewer. It describes the creation of a simple Applet which will allow a report to be viewed from your browser.

This example uses the Bean Box, a component of the Bean Developer Kit (BDK) from Sun Microsystems Inc. The Bean Box is not intended to be used for serious application development, rather as a platform for testing Beans interactively at design time, and creating simple applets for run time testing. The Bean Box is available for download from Sun Microsystems.


Adding the Report Viewer Bean to the project

To add the Java Plugin Viewer to the Bean Box
  1. Locate the JAR file called ReportViewer.jar in the Viewers directory.

    2. Program Files\Common Files\Business Objects\3.0\crystalreportviewers11\JavaViewer

  2. Either copy the file to the \jars subdirectory of the BDK, or from the Bean Box, select LoadJar from the File menu and specify the pathname of the file.

    3. The Crystal Report Viewer Icon should appear in the ToolBox palette.


Creating a simple applet with the Report Viewer

To add the Java Plugin Viewer to the Bean Box Composition window and create an applet
  1. Click the Java Plugin Viewer's name (Crystal Report Viewer) in the ToolBox palette.
  2. Click the location in the Bean Box Composition window where you want the Report Viewer Bean to appear.
  3. Resize the Report Viewer in the Composition window until you are able to see the controls and report window.

    4. In the Bean Box Property Sheet window, you will see the list of Report Viewer Bean properties. These can be set and edited. For example to view a report click on the reportName property. When the dialog box appears enter the URL of a report file (for example: "http://localhost/scrreports/craze/adcont2s.rpt").

    The report should be displayed in the Crystal Report Viewer Report window.

  4. To create a simple applet, select MakeApplet from the File menu.

    5. This will create an applet which when called from your browser will display the report specified in the reportName property. You will be prompted to specify a directory where your applet and its supporting file will be placed (or the default tmp subdirectory of the beanbox directory).

If you look at the directory containing the applet, you will notice that there are a number of supporting files and directories. Locate the HTML file (<appletname>.html) and click it. Your default browser displays the Report Viewer and the report.

The minimum required to actually run the application using the Java Plugin Viewer is:

  • The HTML file which references the applet class file.
  • The extracted ReportViewer.jar file and any supporting jar files.
  • The applet class file.


Programming the Embeddable Crystal Reports Designer Control

This section demonstrates how to integrate the Embeddable Crystal Reports Designer Control (Embeddable Designer) into your application. Included are tutorials on creating sample applications in both Microsoft Visual Basic and Microsoft Visual C++. A brief section on creating reports in the designer at runtime is also included.

Click the appropriate link to jump to that section:

  • Overview
  • Creating a Microsoft Visual Basic sample application with the Embeddable Designer
  • Creating a Microsoft Visual C++ sample application with the Embeddable Designer
  • Designing reports in the Embeddable Designer


Overview

The Embeddable Crystal Reports Designer Control (Embeddable Designer) is easily integrated into your application and provides your users with an interactive environment to design or edit Crystal Reports.

The following examples demonstrate how to create a sample application using the Embeddable Designer in both Microsoft Visual Basic and Microsoft Visual C++. Two tutorials are provided:

  • Creating a Microsoft Visual Basic sample application with the Embeddable Designer
  • Creating a Microsoft Visual C++ sample application with the Embeddable Designer


Creating a Microsoft Visual Basic sample application with the Embeddable Designer

This tutorial assumes that you have prior knowledge of Microsoft Visual Basic, Crystal Reports, and the Report Designer Component. The following procedure and sample code detail how to create an application that demonstrates the Embeddable Designer. The application will consist of a single form with a tab control and buttons to create a new report or open an existing report. The tab control has two property pages. The first page (Designer tab) contains the Embeddable Designer, and the second page (Viewer tab) contains the Crystal Reports Viewer Control. See Programming the Crystal Report Viewers. With the application running, you will be able to open a new report or an existing report in the Embeddable Designer. After designing or editing a report, view it in the Crystal Report Viewer. When you go back to the Embeddable Designer to make changes, you'll see those changes updated automatically in the Crystal Report Viewer.

Note: The sample application was created in Microsoft Visual Basic version 6.0 with Service Pack 4.

This tutorial contains the following steps:

  • Step 1: Creating the user interface (Microsoft Visual Basic)
  • Step 2: Writing the code (Microsoft Visual Basic)
  • Step 3: Running the Embeddable Designer application (Microsoft Visual Basic)


Step 1: Creating the user interface (Microsoft Visual Basic)

To return to the introduction, go to Creating a Microsoft Visual Basic sample application with the Embeddable Designer.

In this step, you will add the references, components, forms, and controls for the application.

  1. Create a new Standard EXE project.
  2. Add the following components to the project:
    • Crystal Report Viewer Control.
    • Embeddable Crystal Reports Designer Control Library 11.0.
    • Microsoft Common Dialog Control 6.0.
    • Microsoft Tabbed Dialog Control 6.0 (Sp4).
  3. Add the following reference to the project:
    • Crystal Reports ActiveX Designer Design and Runtime Library 11.0.

      • Note: See Programming the Crystal Report Viewers for more information.

  4. Add the following controls from the Toolbox to the form:
    • Three CommandButton controls.
    • Common Dialog (Microsoft Common Dialog Control 6.0).
    • SSTab1 (Microsoft Tabbed Dialog Control 6.0 (SP4)).
    • CRDesignerCtrl (Embeddable Crystal Reports Designer Control).
    • CRViewer (Crystal Report Viewer Control).
  5. Set the properties for the form and the controls:
    • Form1 (Main form for the application):
      • Name = frmMain
      • Caption = Embeddable Crystal Reports 11 Designer Control Sample
      • Height = 8265
      • Width = 10815
    • SStab1 (Tabbed control containing the Embeddable Designer and Crystal Report Viewer Controls):

      • Note: Click the tabs on SSTab1 to access the separate Caption properties.

      • Name = SSTab1
      • Tabs = 2
      • Tab0 Caption = Design
      • Tab1 Caption = Preview
      • Enabled = False
      • Height = 7600
      • Left = 0
      • Tab Height = 300
      • Top = 130
      • Width = 10825
    • CRDesignerCtrl1 (Designs and edits reports):

      • Note: Place the control on the tab labeled "Designer."

      • Name = CRDesignerCtrl1
      • Height = 6540
      • Left = 240
      • Top = 720
      • Width = 10325
    • CRViewer1 (Views reports):
      • Name = CRViewer1
      • Width = 10325
      • Left = 240
      • Top = 720
      • Height = 6540
    • CommonDialog1 (Creates an Open dialog to select reports):
      • Name = CommonDialog1
      • Filter = Crystal Reports |*.rpt
    • Button1 (Creates a new report):
      • Name = cmdNew
      • Caption = &New Report
      • Left = 120
      • Top = 7850
    • Button2 (Opens an existing report):
      • Name = cmdOpen
      • Caption = &Open Report
      • Left = 1950
      • Top = 7850
    • Button3 (Closes the form and exits the application):
      • Name = cmdExit
      • Caption = &Exit
      • Left = 9030
      • Top = 7850

To continue with this procedure, go to Step 2: Writing the code (Microsoft Visual Basic).


Step 2: Writing the code (Microsoft Visual Basic)

To return to the previous part of this procedure, go to Step 1: Creating the user interface (Microsoft Visual Basic).

In this step you will add the code to:

  • Create a new report.
  • Create an Open dialog box to open an existing report.
  • Set the report object to CRDesignerCtrl1 and view the report in design mode.
  • Set the report object to CRViewer1, set the zoom level, and view the report.
  • Refresh the report when switching from the Designer tab to the Viewer tab on the Microsoft Tabbed Dialog Control.
  1. Type or insert the sample code below into the code module of frmMain.
  2. Once you have added the code, on the Run menu click Start to run the application.

Note: Error handling is not included in the code samples.

Option Explicit

Dim m_Application As New CRAXDDRT.Application

Dim m_Report As CRAXDDRT.Report

' *************************************************************

'DisplayReport is a procedure that

' - Enables the Tab control the first time a report is created

' or opened.

' - Sets the report object to the Embeddable Designer(CRDesigner1).

' - Disables the Help menu in the Embeddable Designer.

' - Sets the report object to the Crystal Report Viewer Control

' (CRViewer1).

' - Sets the Crystal Reports Viewer to view the report.

Public Sub DisplayReport()

' Enable the tab control if disabled.

If SSTab1.Enabled = False Then SSTab1.Enabled = True

' Set the Report Object.

CRDesignerCtrl1.ReportObject = m_Report

' Note----------------

' Set all other properties for CRDesignerCtrl1 after setting the

' ReportObject property

' --------------------

' Disable the Help menu.

CRDesignerCtrl1.EnableHelp = False

' Set the report source.

CRViewer1.ReportSource = m_Report

' Set the viewer to view the report.

CRViewer1.ViewReport

' Set the zoom level to fit the page

' to the width of the viewer window.

CRViewer1.Zoom 1

End Sub

' *************************************************************

Private Sub Form_Load()

' Set the tab control to display the Designer tab

'when the form is loaded.

SSTab1.Tab = 0

End Sub

' *************************************************************

Private Sub SSTab1_Click(PreviousTab As Integer)

' Refresh the report when clicking Preview,

' without refreshing the data from the server.

If PreviousTab = 0 Then CRViewer1.RefreshEx False

End Sub

' *************************************************************

' Create a new report and display it in the Embeddable Designer

Private Sub cmdNew_Click()

' Set the report object to nothing.

Set m_Report = Nothing

' Create a new report.

Set m_Report = m_Application.NewReport

' Call DisplayReport to set the report to the Embeddable Designer

' and the Crystal Report Viewer and then display the report in the

' Embeddable Designer.

Call DisplayReport

End Sub

' *************************************************************

' Use the Microsoft Common Dialog control to open a report.

Private Sub cmdOpen_Click()

CommonDialog1.CancelError = True

On Error GoTo errHandler

' Display the open dialog box.

CommonDialog1.ShowOpen

' Set the report object to nothing.

Set m_Report = Nothing

' Open the selected report.

Set m_Report = m_Application.OpenReport(CommonDialog1.FileName, 1)

' Call DisplayReport to set the report to the Embeddable Designer

' and the Crystal Report Viewer

Call DisplayReport

Exit Sub

errHandler:

' User cancelled dialog

End Sub

' *************************************************************

Private Sub cmdAbout_Click()

frmAbout.Show vbModal

End Sub

' *************************************************************

Private Sub cmdExit_Click()

Unload Me

End Sub

To continue with this procedure, go to Step 3: Running the Embeddable Designer application (Microsoft Visual Basic).


Step 3: Running the Embeddable Designer application (Microsoft Visual Basic)

To return to the previous part of this procedure, go to Step 2: Writing the code (Microsoft Visual Basic).

In this step you will:

  • Create and design a new report in the Embeddable Designer.
  • View the report and any changes made to the report.
  • Open and edit an existing report in the Embeddable Designer.
  • View the report and any changes made to the report.
  1. With the application running, click New Report.

    2. An empty report will appear in the Embeddable Designer.

    Note: The interface for the Embeddable Designer is the same one used for ActiveX Designer reports created in the Microsoft Visual Basic IDE with the Crystal Reports Report Designer Component.

  2. Design a new report to view.

    3. If you are not familiar with the designer environment, see Designing reports in the Embeddable Designer for a step-by-step procedure on creating a simple report off the Xtreme Sample Database ODBC data source.

  3. Click Preview to view the report in the Crystal Report Viewer.
  4. Click Design and make some changes to the report. Then click Preview to see the changes in the Crystal Report Viewer.
  5. Click Open.
  6. In the Open dialog box, select one of the sample reports and click Open to view the report in the Embeddable Designer.
  7. Click Preview to view the report in the Crystal Report Viewer.
  8. Click Design and make some changes to the report. Then click Preview to see the changes in the Crystal Report Viewer.

To return to the introduction, go to Creating a Microsoft Visual Basic sample application with the Embeddable Designer.


Creating a Microsoft Visual C++ sample application with the Embeddable Designer

This tutorial assumes that you have prior knowledge of Microsoft Visual C++, Crystal Reports, and the Report Designer Component. The following procedure and sample code create an application that demonstrates the Embeddable Designer. The application will consist of main dialogs for the Embeddable Designer, and for the Crystal Reports Viewer Control. For details, see Programming the Crystal Report Viewers.

With the application running, you will be able to open a new or existing report in the Embeddable Designer. After designing or editing a report, you can preview it in the Crystal Report Viewer by clicking the Preview button. You can then return to the Embeddable Designer by clicking the Design button. When you go back to to edit the report, you can see those changes updated automatically by clicking the Preview button again.

This tutorial contains the following steps:

  • Step 1: Creating the User Interface (Microsoft Visual C++)
  • Step 2: Adding member variables and member functions (Microsoft Visual C++)
  • Step 3: Writing the code (Microsoft Visual C++)
  • Step 4: Running the Embeddable Designer application (Microsoft Visual C++)


Step 1: Creating the User Interface (Microsoft Visual C++)

To return to the introduction, go to Creating a Microsoft Visual C++ sample application with the Embeddable Designer.

In this step, you will create a Dialog-based MFC.EXE application and add the components, and controls for the application.

  1. Using the AppWizard, create a starter Dialog-based MFC application. The main dialog will display reports in Embeddable Designer and the Crystal Report Viewer:
    • Project Name: Embeddable_Designer
    • Application Class Name: CEmbeddable_DesignerApp
    • Dialog Class Name: CEmbeddable_DesignerDlg
  2. Add the Embeddable Designer Control and the Crystal Report Viewer Control through the Components and Controls Gallery dialog box:
    • Embeddable Crystal Reports Designer Control Library 11.0
    • Crystal Report Viewer Control
  3. Add the following controls from the Toolbox to IDD_EMBEDDABLE_DESIGNER_DIALOG (Embeddable Designer dialog):
    • Six buttons
    • Embeddable Crystal Reports Designer Control
    • Crystal Report Viewer
  4. Set the properties for the Embeddable Designer dialog and its controls:
    • IDD_EMBEDDABLE_DESIGNER_DIALOG (Create, open, save, design and preview reports):
      • Caption: Embeddable Designer
      • Height: 340
      • Width: 540
    • Embeddable Crystal Reports Designer Control (Designs and edits reports):
      • Height: 300
      • Left: 7
      • Top: 7
      • Width: 525
    • Crystal Report Viewer:
      • Height: 300
      • Left: 7
      • Top: 7
      • Width: 525

        • Note: Either the Embeddable Designer or the Crystal Report Viewer will be hidden depending on whether the user is designing or previewing a report.

    • All Buttons (Common Properties):
      • Align all Buttons to the bottom of the form
      • Height: 14
      • Width: 50
    • Button1 (Creates a new report):
      • ID: IDC_NEW_REPORT
      • Caption: &New Report
      • Left: 7
    • Button2 (Opens an existing report):
      • ID: IDC_OPEN_REPORT
      • Caption: &Open Report
      • Left: 66
    • Button3 (Saves a report):
      • ID: IDC_SAVE_REPORT
      • Caption: &Save Report
      • Left: 125
    • Button4 (Shows the Crystal Report Viewer and hides the Embeddable Designer.):
      • ID: IDC_PREVIEW
      • Caption: &Preview
      • Left: 184
    • Button5 (Shows the Embeddable Designer and hides the Crystal Report Viewer):
      • ID: IDC_SHOW_DESIGNER
      • Caption: &Design
      • Left: 184
    • Button6 (Exits the application):
      • ID: IDCANCEL
      • Caption: E&xit
      • Left: 483

To continue with this procedure, go to Step 2: Adding member variables and member functions (Microsoft Visual C++).


Step 2: Adding member variables and member functions (Microsoft Visual C++)

To return to the previous part of this procedure, go to Step 1: Creating the User Interface (Microsoft Visual C++).

In this step, you will add the member variables for the controls on the Embeddable Designer dialog and then add member functions, and member variables for the CEmbeddable_DesignerDlg class.

This step is broken into 2 sections:

  • Adding member variables for the Embeddable Designer dialog controls
  • Adding member variables and functions to the CEmbeddable_Designer class


Adding member variables for the Embeddable Designer dialog controls

To return to the previous part of this procedure, go to Step 2: Adding member variables and member functions (Microsoft Visual C++).

Use the Class Wizard to create the member variables for the controls.

  1. Create member variables for the controls on the Embeddable Designer dialog:
    • Embeddable Designer Control:
      • Control ID: IDC_EMBEDDABLECRYSTALREPORTSDESIGNERCTRL
      • Type: CCRDesignerCtrl
      • Member: m_Designer
    • Crystal Report Viewer Control:
      • Control ID: IDC_CRVIEWER1
      • Type: CCrystalReportViewer4
      • Member: m_Viewer
    • New Report Button:
      • Control ID: IDC_NEW_REPORT
      • Type: CButton
      • Member: m_NewReport
    • Open Report Button:
      • Control ID: IDC_OPEN_REPORT
      • Type: CButton
      • Member: m_OpenReport
    • Save Report Button:
      • Control ID: IDC_SAVE_REPORT
      • Type: CButton
      • Member: m_SaveReport
    • Preview Button:
      • Control ID: IDC_PREVIEW
      • Type: CButton
      • Member: m_Preview
    • Design Button:
      • Control ID: IDC_SHOW_DESIGNER
      • Type: CButton
      • Member: m_ShowDesigner

Adding member variables and functions to the CEmbeddable_Designer class.


Adding member variables and functions to the CEmbeddable_Designer class

To return to the previous part of this procedure, go to Adding member variables for the Embeddable Designer dialog controls.

Add the following member variables, and member functions to the CEmbeddable_Designer class. The code for the functions will be added in Step 3: Writing the code (Microsoft Visual C++).

  1. Create the following member variables:
    • Application pointer for the Craxddrt Application Object:
      • Variable Type: IApplicationPtr
      • Variable Name: m_Application
    • Report pointer for the Craxddrt Report Object:
      • Variable Type: IReportPtr
      • Variable Name: m_Report
  2. Create the following member function:
    • Function to create or open a report and initialize the controls on the Embeddable Designer form.
      • Function Type: void
      • Function Declaration: InitReport(BOOL bNew)
  3. Add a member function for the BN_CLICKED message of each of the following buttons:
    • New Report: (Click to create a new report)
      • Member function name: OnNewReport
    • Open Report: (Click to open an existing report)
      • Member function name: OnOpenReport
    • Save Report: (Click to save the current report)
      • Member function name: OnSaveReport
    • Preview: (Click to Preview the current report)
      • Member function name: OnPreview
    • Design: (Click to edit the current report)
      • Member function name: OnShowDesigner

To continue with this procedure, go to Step 3: Writing the code (Microsoft Visual C++).


Step 3: Writing the code (Microsoft Visual C++)

To return to the previous part of this procedure, go to Step 2: Adding member variables and member functions (Microsoft Visual C++).

In this step, you will write the code for member functions added in Step 2: Adding member variables and member functions (Microsoft Visual C++); you will also add directives and constants to the source and header files.

This step is broken into 2 sections:

  • Adding directives and constants to the source and header files
  • Adding the code for the CEmbeddable_Designer class


Adding directives and constants to the source and header files

To return to the previous part of this procedure, go to Step 2: Adding member variables and member functions (Microsoft Visual C++).

Add the following directives and constants to the Source and Header files.

  1. Add a constant to Embeddable_DesignerDlg.cpp.

    2. // Filter for the Open dialog box and the Save As dialog box

    static const char BASED_CODE szFilter[] = "Crystal Reports|*.rpt||";

To continue with this procedure, go to Adding the code for the CEmbeddable_Designer class.


Adding the code for the CEmbeddable_Designer class

To return to the previous part of this procedure, go to Adding directives and constants to the source and header files.

Type or insert the code for the member functions created in Adding member variables and functions to the CEmbeddable_Designer class. The CEmbeddable_DesignerDlg class handles the basic functionality of the Embeddable Designer sample application. The class will handle all of the report functionality including creating a new report or opening an existing report, and displaying it in the Embeddable Designer or the Crystal Report Viewer. Once a report is designed or edited it can be saved, previewed, or refreshed.

Note: Error handling is not included in the code samples.

  1. Add the code to the OnInitDialog function.

    2. // Hide the Crystal Reports Viewer control and show the Embeddable Designer control.

    m_Viewer.ShowWindow(SW_HIDE);

    m_Designer.ShowWindow(SW_SHOW);

  2. Add the code for the InitReport function.

    3. // In this function a report is created or opened. The report is set to

    // the Embeddable Designer and Crystal Report Viewer, with the Embeddable

    // Designer visible and the Crystal Report Viewer hidden. Then the

    // command buttons are initialized so that Save Report, and Preview are

    // enabled, and Design is disabled and hidden.

    void CEmbeddable_DesignerDlg::InitReport(BOOL bNew)

    {

    // Create a new report for designing and previewing.

    if(bNew)

    {

    m_Application.CreateInstance("CrystalDesignRuntime.Application");

    m_Report = m_Application->NewReport();

    }

    // Show an Open dialog box, and then browse and open a report

    // for editing and previewing.

    else

    }

    // Initialize the Open dialog box to only display the

    // Crystal Report(.rpt) file type.

    CFileDialog FileDlg(TRUE,"*.rpt",NULL, OFN_EXPLORER, szFilter);

    // Show the Open dialog box

    int iReturn = FileDlg.DoModal();

    if(iReturn == IDOK)

    {

    // Get the name and path of the report file selected from the

    // Open dialog box.

    _bstr_t FileName(FileDlg.GetPathName().AllocSysString());

    // Create the Application Object.

    m_Application.CreateInstance("CrystalDesignRuntime.Application");

    // Open the report selected from the Open dialog box.

    m_Report = m_Application->OpenReport(FileName);

    }

    else if (iReturn = IDCANCEL)

    {

    // Terminate the execution of the function if the

    // user cancels.

    return;

    }

    }

    // Set the report object to the Embeddable Designer.

    m_Designer.SetReportObject(m_Report);

    // Set the report souce for the Crystal Reports Viewer.

    m_Viewer.SetReportSource(m_Report);

    // Set the width of the report page to the width of the viewing area.

    m_Viewer.Zoom(1);

    // View the report in the Crystal Reports Viewer control.

    m_Viewer.ViewReport();

    // Check if the Save Report button is enabled.

    // If the button is disabled then enable the Save Report,

    // and Preview buttons. The Save Report button will always

    // be enabled once the first report is opened or created.

    BOOL bEnabled;

    if( bEnabled == FALSE)

    {

    m_SaveReport.EnableWindow(TRUE);

    m_Preview.EnableWindow(TRUE);

    }

    // Check if the Embeddable Designer is hidden.

    // If it is hidden then hide the Design button, show the

    // Preview button, hide the Crystal Reports Viewer, and

    // show the Embeddable Designer.

    if(!m_Designer.IsWindowVisible())

    {

    m_ShowDesigner.ShowWindow(SW_HIDE);

    m_Preview.ShowWindow(SW_SHOW);

    m_Viewer.ShowWindow(FALSE);

    m_Designer.ShowWindow(TRUE);

    }

    }

  3. Add the code for the OnNewReport function.

    4. // In this function call the InitReport function and pass a

    // value of True to create a new report. Passing a value of

    // False opens an existing report.

    void CEmbeddable_DesignerDlg::OnNewReport()

    {

    InitReport(TRUE);

    }

  4. Add the code for the OnOpenReport function.

    5. // In this function call the InitReport function and pass

    // a value of False to open an existing report. Passing a

    // value of True creates a new report.

    void CEmbeddable_DesignerDlg::OnOpenReport()

    {

    InitReport(FALSE);

    }

  5. Add the code for the OnSaveReport function.

    6. // In this function open a Save As dialog box and save the current

    // report to the selected path and name.

    void CEmbeddable_DesignerDlg::OnSaveReport()

    {

    // Initialize the Save As dialog box to only display the Crystal

    // Report (.rpt) file type.

    CFileDialog FileDlg(FALSE,"*.rpt",NULL,OFN_EXPLORER, szFilter);

    // Show the Save As dialog box.

    int iReturn = FileDlg.DoModal();

    if(iReturn == IDOK)

    {

    // Get the path and name selected in the Save As dialog box.

    _bstr_t FileName(FileDlg.GetPathName().AllocSysString());

    // Save the report to the path and name specified in the

    // Save As dialog box.

    m_Designer.SaveReport(FileName);

    }

    else if(iReturn == IDCANCEL)

    {

    // Terminate the execution of the function if the

    // user cancels.

    return;

    }

    }

  6. Add the code for the OnPreview function

    7. // In this function, refresh the report without refreshing the data

    // source, hide the Preview button and the Embeddable Designer, and

    // then show the Design button and the Crystal Report Viewer.

    void CEmbeddable_DesignerDlg::OnPreview()

    {

    m_Viewer.RefreshEx(FALSE);

    m_Preview.ShowWindow(SW_HIDE);

    m_Designer.ShowWindow(SW_HIDE);

    m_ShowDesigner.ShowWindow(SW_SHOW);

    m_Viewer.ShowWindow(SW_SHOW);

    }

  7. Add the code for the OnShowDesigner function.

    8. // In this function, hide the Design button and the Crystal Report

    // Viewer, and show the Preview button and the Embeddable Designer.

    void CEmbeddable_DesignerDlg::OnShowDesigner()

    {

    m_ShowDesigner.ShowWindow(SW_HIDE);

    m_Viewer.ShowWindow(SW_HIDE);

    m_Preview.ShowWindow(SW_SHOW);

    m_Designer.ShowWindow(SW_SHOW);

    }

To continue with this procedure, go to Step 4: Running the Embeddable Designer application (Microsoft Visual C++).


Step 4: Running the Embeddable Designer application (Microsoft Visual C++)

To return to the previous part of this procedure, go to Step 3: Writing the code (Microsoft Visual C++).

In this step you will:

  • Create and design a new report in the Embeddable Designer.
  • View the report and any changes made to the report.
  • Open and edit an existing report in the Embeddable Designer.
  • View the report and any changes made to the report.
  • Save a report.
  1. With the application running, click New Report.

    2. An empty report will appear in the Embeddable Designer.

    Note: The interface for the Embeddable Designer is the same one used for ActiveX Designer reports created in the Microsoft Visual Basic IDE with the Report Designer Component.

  2. Design a new report to view.

    3. If you are not familiar with the designer environment, refer to Designing reports in the Embeddable Designer for a step-by-step procedure on creating a simple report off the Xtreme Sample Database ODBC data source.

  3. Click Preview to view the report in the Crystal Report Viewer.
  4. Click Design and make some changes to the report in the Embeddable Designer. Then click Preview to see the changes in the Crystal Report Viewer.
  5. Click Open. In the Open dialog box, select one of the sample reports and click Open to view the report in the Embeddable Designer dialog.
  6. Click Preview to view the report in the Crystal Report Viewer.
  7. Click Design and make some changes to the report in the Embeddable Designer. Then click Preview to see the changes in the Crystal Report Viewer.
  8. Click Save Report.
  9. In the Save As dialog box, browse to the desired directory, type the name you want to save the report as, and then click Save.

Note: When you are designing a report the Preview button will be visible, and when you are previewing a report the Design button will be visible.

To return to the introduction, go to Creating a Microsoft Visual C++ sample application with the Embeddable Designer.


Designing reports in the Embeddable Designer

Designing reports in the Embeddable Designer is an intuitive process. In this procedure, you will create a simple report off the Xtreme Sample Database 11 ODBC data source, which installs with Crystal Reports. The report will include a text object, database fields, and a group.

The procedure contains the following steps:

  • Step 1: Adding a data source to the report
  • Step 2: Adding fields and grouping to the report


Step 1: Adding a data source to the report

In this step, you will use the Data Explorer to add the Customer table from the ODBC data source Xtreme Sample Database 11.

  1. On the Main Report tab, right-click Database Fields, and then click Add Database to Report.
  2. In the Data Explorer dialog box, expand ODBC and expand Xtreme Sample Database 11; then select Customer, and click Close.
  3. In the Visual Linking Expert dialog box, click OK.

    4. The data source is now added to the report.


Step 2: Adding fields and grouping to the report

In this step you will add a text object to the Report Header section, the Customer Name and Last Year's Sales Fields to the Details section, and a group based on the Region field.

  1. On the Main Report tab, right-click in the white space to access the shortcut menu.
  2. On the shortcut menu, point to Insert, and then click Text Object.

    3. An object frame appears with the Arrow pointer.

  3. Drag the object frame to the Report Header section and click to release the text object.
  4. Double-click the text object to edit it, and then type: Xtreme Sales Report by Region.
  5. Expand Database Fields, and then expand Customer to view the database fields.
  6. Drag the Customer Name and Last Year's Sales fields into the Details section.

    7. A column heading for each field is automatically placed in the Page Header section.

  7. Click Insert Group on the toolbar.
  8. In the Insert Group dialog box, select Region, and then click OK.

You are now ready to preview, export, print, or save the report. See Crystal Reports Online Help (crw.chm) for more information on designing reports in the Crystal Reports environment.

Note: You can find the typical Crystal Report Designer commands (menu items and toolbar buttons) on the shortcut menu of the Embeddable Designer. The Embeddable Designer does not support OLAP grids or maps.


Working with Visual C++

This section illustrates how the Report Designer Component (RDC) can be integrated using Visual C++.

Click the appropriate link to jump to that section:

  • Overview
  • Using the RDC with Visual C++


Overview

While much of this help system is aimed at the Visual Basic developer, it is important to note that the integration methods can be used in any environment that supports COM. This section shows you how to use different integration methods with other popular development environments.

Note: For more information visit the following sites:

  • Visit the Business Objects Developer Zone web site at http://www.businessobjects.com/products/dev_zone.
  • Visit the Business Objects Support site at http://support.businessobjects.com. At this site you will find links to documentation and knowledge base articles about using the Report Designer Component with Visual C++.


Using the RDC with Visual C++

There are different ways to access the Report Designer Component (RDC) and any other COM Automation server through Visual C++. This section describes how to use the #import method.

Manipulating the RDC in Microsoft Visual C++ involves three steps:

  • Define and instantiate a variable to be used to manipulate the RDC COM object.
  • Instantiate an actual instance of the RDC COM object and assign it to a variable.
  • Manipulate the Properties and Methods and then output the report.

The following section leads you through the details in each of these steps.

Previewing a Report through Visual C++

To preview a report through Visual C++
  1. Open Visual C++ 6.0 if it isn't already running.
  2. On the File menu, select New.
  3. In the New dialog box, select the MFC AppWizard (exe) from the Projects tab.
  4. Type MyRDC for the Project Name and click OK.
  5. In the first step of the wizard, select Dialog based and click Finish to accept the defaults for the MFC AppWizard, and then click OK in the New Project Information dialog box.

    6. When the wizard executes, a dialog box appears in design mode.

  6. Right-click the dialog box and select Insert ActiveX Control from the popup dialog box. From the list of available controls, select Crystal Report Viewer Control.
  7. Resize the control to the desired size.
  8. Rearrange the OK and Cancel buttons to their desired location.
  9. Select the View|Class Wizard.
  10. Click the Member Variables tab and ensure that the class name is CMyRDCDlg.
  11. Add a variable for the IDC_ACTIVEXREPORTVIEWER1 and click OK when prompted to add the control to the project.
  12. Name the member variable for the viewer m_Viewer.
  13. Click OK to save the changes and then close the dialog box.
  14. Add the following code after #endif // _AFX_NO_AFXCMN_SUPPORT:

    15. #import "c:\program files\common files\business objects\3.0\bin\craxdrt.dll" no_namespace

  15. On the File|Open menu, select the MyRDCdlg.h file that was generated by the MFC App wizard and click Open.
  16. Declare protected member variables for the RDC's Application and Report objects in the implementation section of the MyRDCdlg.h header file.

    17. For optional Variant parameters declare a protected dummy variable in the same section.

    IApplicationPtr m_Application;

    IReportPtr m_Report;

    VARIANT dummy;

  17. In the MyRDCdlg.CPP file, add the following code to the CMyRDCDlg::OnInitDialog() method just before the return statement:

    18. // A dummy variant

    VariantInit (&dummy);

    dummy.vt = VT_EMPTY;

    // Specify the path to the report you want to print

    _bstr_t ReportPath("c:\\Program Files\\Business Objects\\Crystal Reports 11\\Samples\\En\\Reports\\General Business\\Inventory.rpt");

    _variant_t vtEmpty(DISP_E_PARAMNOTFOUND, VT_ERROR);

    // Instantiate the IApplication object

    m_Application.CreateInstance("CrystalRuntime.Application.11");

    //Open the Report using the OpenReport method

    m_Report = m_Application->OpenReport(ReportPath, dummy);

    //Print the Report to window

    m_Viewer.SetReportSource(m_Report);

    m_Viewer.ViewReport();

  18. Finally, on the Build menu, select Rebuild All, then Execute.

    19. When the app runs, it opens the report and displays it in the viewer control on the application's dialog. Click OK or Cancel to dismiss the dialog and terminate the application.

Opening and Printing a Crystal Report through the RDC

To open and print a Crystal Report through the RDC
  1. On the File|Open menu, open the MyRDC.CPP file. Add the following code to the MyRDC.InitInstance() method just before the return statement:

    2. // A dummy variant

    VariantInit (&dummy);

    dummy.vt = VT_EMPTY;

    HRESULT hr = S_OK;

    // Specify the path to the report you want to print

    _bstr_t ReportPath("c:\\Program Files\\Business Objects\\Crystal Reports 11\\Samples\\En\\Reports\\General Business\\Inventory.rpt");

    _variant_t vtEmpty(DISP_E_PARAMNOTFOUND, VT_ERROR);

    // Instantiate the IApplication object

    m_Application.CreateInstance("CrystalRuntime.Application.11");

    //Open the Report using the OpenReport method

    m_Report = m_Application->OpenReport(ReportPath, dummy)

    //Print the Report to printer

    m_Report->PrintOut(dummy, dummy, dummy, dummy);

  2. Finally, on the Build menu, select Rebuild All.

There are hundreds of properties, methods, and events in the Report Designer Component object model that you can manipulate through your code to meet the demands of virtually any reporting requirement.


Report Designer Component Object Model

The Report Designer Component is the ultimate development tool for your reporting needs. In this section you will find a detailed description of the Report Designer Component Object Model and its properties, methods, and events.

Click the appropriate link to jump to that section:

  • Overview of the Report Designer Object Model
  • Unification of the RDC object model
  • Runtime licensing
  • Object naming conflicts
  • Objects and Collections
  • Creatable Objects
  • Application Object
  • Area Object
  • Areas Collection
  • BlobFieldObject Object
  • BoxObject Object
  • ConnectionProperty Object
  • ConnectionProperties Collection
  • CrossTabGroup Object
  • CrossTabGroups Collection
  • CrossTabObject Object
  • Database Object
  • DatabaseFieldDefinition Object
  • DatabaseFieldDefinitions Collection
  • DatabaseTable Object
  • DatabaseTables Collection
  • ExportOptions Object
  • FieldDefinitions Collection
  • FieldElement Object
  • FieldElements Collection
  • FieldMappingData Object
  • FieldObject Object
  • FormattingInfo Object
  • FormulaFieldDefinition Object
  • FormulaFieldDefinitions Collection
  • GraphObject Object
  • GroupNameFieldDefinition Object
  • GroupNameFieldDefinitions Collection
  • LineObject Object
  • MapObject Object
  • ObjectSummaryFieldDefinitions Collection
  • OlapGridObject Object
  • OleObject Object
  • Page Object
  • PageEngine Object
  • PageGenerator Object
  • Pages Collection
  • ParameterFieldDefinition Object
  • ParameterFieldDefinitions Collection
  • ParameterValue Object
  • ParameterValues Collection
  • ParameterValueInfo Object
  • ParameterValueInfos Collection
  • PrintingStatus Object
  • Report Object
  • ReportAlert Object
  • ReportAlerts Collection
  • ReportAlertInstance Object
  • ReportAlertInstances Collection
  • ReportObjects Collection
  • RunningTotalFieldDefinition Object
  • RunningTotalFieldDefinitions Collection
  • Section Object
  • Sections Collection
  • SortField Object
  • SortFields Collection
  • SpecialVarFieldDefinition Object
  • SQLExpressionFieldDefinition Object
  • SQLExpressionFieldDefinitions Collection
  • SubreportLinks Collection
  • SubreportObject Object
  • SummaryFieldDefinition Object
  • SummaryFieldDefinitions Collection
  • TableLink Object
  • TableLinks Collection
  • TextObject Object
  • Examples
  • Enumerated Types


Overview of the Report Designer Object Model

Please review the following comments regarding Object naming conflicts.


Unification of the RDC object model

Craxddrt.dll (Crystal Reports ActiveX Designer Design and Runtime Library) is a unified object model that combines the runtime capabilities of the Craxdrt.dll (Crystal Reports ActiveX Designer Run Time Library) with the design time capabilities of the Craxddt.dll (Crystal Reports ActiveX Designer Design Time Library). Craxddrt.dll will replace Craxddt.dll for versions 8.5 and up. Both the Craxddrt.dll and the Craxdrt.dll contain all the objects and associated methods, properties, and events needed for creating, opening, exporting, saving, and printing a report at run time. In addition, Craxddrt.dll is either used with the RDC ActiveX Designer when designing reports at design time, or used with the Embeddable Designer when designing reports at run time. See Embeddable Crystal Reports Designer Control Object Model for more information.

Note: The RDC ActiveX Designer is only available in Microsoft Visual Basic.

Prior to version 8.5, the Craxdrt.dll would be distributed with an application. Now the developer has a choice of two automation servers to distribute. Craxdrt.dll is backwards-compatible with previous versions and contains all the features introduced in this version. Use the Craxdrt.dll for any client-side application that does not contain the Embeddable Designer, or use it for any server-side application. Craxddrt.dll is apartment-model threaded, but is not thread safe, and can only be used in a client-side application. Although the Craxddrt.dll is a fully functional automation server for the RDC, and can work in any client-side application, it will increase the install size. Therefore, it is recommended that you only use Craxddrt.dll with the Embeddable Crystal Reports Designer Control.


Runtime licensing

Your Crystal Reports developer edition license provides the rights to distribute software applications that use or embed most files and functionality of the product, free of charge. In addition, your Crystal Reports developer edition contains features that provide a great deal of flexibility and power for developers to embed reporting into their applications. These runtime report creation features may only be used and distributed if the appropriate licensing is obtained from Crystal Decisions by paying the required royalty fees. Please refer to the License Manager Help (License.hlp) for lists of features that are royalty-free and royalty-required.


Object naming conflicts

If your project includes other libraries that contain objects named identical to those found in the Crystal Report Engine Object Library, you will encounter conflicts unless you reference the objects using a prefix. For example, if you have included the DAO Library with the Crystal Report Engine Object Library in your project, both libraries include a Database Object. In order to avoid conflicts, you must prefix the objects as follows:

CRAXDRT.Database

for the Crystal Report Engine Object Library, or

DAO.Database

for the DAO Library.


Objects and Collections

The following Objects and Collections, listed alphabetically, are discussed in this section. Properties, Methods, and Events are listed under the appropriate Object or Collection.

Note: Some of the report creation calls are not included in the free runtime license included with Crystal Reports. For a list of calls that require additional licensing, please see the License Manager Help (License.hlp).


Creatable Objects

There are several Crystal Reports objects which can be created by passing their Prog Ids into the CreateObject function provided by Visual Basic. The table below lists these objects.

Object | Prog Id
Application Object | CrystalRuntime.Application
ParameterValue Object | CrystalRuntime.ParameterValue
ParameterValues Collection | CrystalRuntime.ParameterValues
ParameterValueInfo Object | CrystalRuntime.ParameterValueInfo
ParameterValueInfos Collection | CrystalRuntime.ParameterValueInfos

Note: The version number can be appended to the Prog Id (for example, CrystalRuntime.ParameterValue.11). If the version number is not specified, CreateObject will create the object using the most recently installed version of craxdrt.dll.


Application Object

An instance of the Application object can be created using the Visual Basic New keyword or the CreateObject function and the Prog Id CrystalRuntime.Application.11. For example:

  • Using the New keyword

    • Dim app as New CRAXDRT.Application

    Set app = New CRAXDRT.Application

Or,

' Automatically creates a new instance of the object when it is first

' referenced in the code, so it doesn't have to be set.

Dim app as New Application

  • Using the CreateObject function

    • ' If the version number of the application is not specified, CreateObject

    ' will create an application running against the most recently installed

    ' version of craxdrt.dll

    Dim app As Application

    Set app = CreateObject("CrystalRuntime.Application")

Or,

' Specify the version number to require version 8.5 of the dll.

Dim app As Application

Set app = CreateObject("CrystalRuntime.Application.8.5")

Click Application Object Methods to continue.


Application Object Methods

The following methods are discussed in this section:

  • CanClose Method (Application Object)
  • GetLicenseStatus Method (Application Object)
  • GetVersion Method (Application Object)
  • LogOffServer Method (Application Object)
  • LogOnServer Method (Application Object)
  • LogOnServerEx Method (Application Object)
  • NewReport Method (Application Object)
  • OpenReport Method (Application Object)
  • SetMatchLogOnInfo Method (Application Object)


CanClose Method (Application Object)

The CanClose method indicates whether or not the Application Object can be destroyed. This method will return FALSE as long as there are valid Report objects in existence and at least one Report Object is in the printing-in-progress state. The Application object can only be destroyed if no instances of the Report Object are in the printing-in-progress state. If you obtain a Report object directly from the Report Designer Component added to your project at design time, then CanClose will always return False until you destroy that object (usually by setting it equal to Nothing).

Syntax

Function CanClose () As Boolean

Returns
  • TRUE if the Engine can be closed.
  • FALSE if the Engine is busy.


GetLicenseStatus Method (Application Object)

The GetLicenseStatus method is used to get the license number of the Report Creation API License and the current count of licenses in use.

Syntax

GetLicenseStatus(pMaxLicenseNumber, pLicenseUsed) As Boolean

Returns
  • True if the license is active and the pLicenseUsed parameter was used in the call.
  • False if the license is not active and the pLicenseUsed parameter was used in the call.


GetVersion Method (Application Object)

The GetVersion method returns an integer that, when converted to hex, represents the version number of the dll.

Syntax

Function GetVersion () As Integer

Returns
  • Returns an integer that represents the version number of the dll when converted to hexidecimal.
Sample

'Display the version number in a text box.

Text1.text = Hex(CRXApplication.GetVersion)


LogOffServer Method (Application Object)

The LogOffServer method logs off an SQL server or other data sources such as ODBC or OLEDB provider. Use this method when you have logged on to the data source using LogOnServer Method (Application Object).

Syntax

Sub LogOffServer (pDllName As String, pServerName As String,

[pDatabaseName], [pUserID], [pPassword])

Parameters

Parameter | Description
pDLLName | Specifies the name of the DLL for the server or password protected non-SQL table you want to log on to, for example "P2SODBC.DLL". Note that the DLLName must be enclosed in quotes. DLL names have the following naming convention: P2B*.DLL for standard (non-SQL) databases, P2S*.DLL for SQL/ODBC databases.
pServerName | Specifies the log on name for the server used to create the report. (For ODBC, use the data source name.) This value is case-sensitive. See Remarks below.
[pDatabaseName] | Specifies the name for the database used to create the report. See Remarks below.
[pUserID] | Specifies the User ID number necessary to log on to the server. See Remarks below.
[pPassword] | Specifies the password necessary to log on to the server.

Remarks
  • For parameters pServerName, pDatabaseName, and pUserId, pass an empty string ("") to preserve the existing setting or pass a non-empty string (for example, "Server A") to override a value that is already set in the report.
  • If you try to log off a server that is still in use (i.e., there is an object variable still in focus that holds reference to a report that requires being logged on to the server to access data) you will be unable to log off. This will apply to every object that comes from the Report Object, as they all hold reference to the report through their respective Report properties.
  • If you assign the Report object to the ReportSource property of the CRViewer Object (CRVIEWERLib), in the Crystal Reports Report Viewer, enabling the report to be displayed through the Report Viewer, you cannot call LogOffServer for the report until you assign a new report to the Report Viewer or close the CRViewer object.


LogOnServer Method (Application Object)

The LogOnServer method logs on to an SQL server or other data sources such as ODBC. Once logged on using this method, you will remain logged on until you call LogOffServer Method (Application Object), or until the Application Object, is destroyed and craxdrt.dll is unloaded.

Syntax

Sub LogOnServer (pDllName As String, pServerName As String,

[pDatabaseName], [pUserID], [pPassword])

Parameters

Parameter | Description
pDLLName | Specifies the name of the DLL for the server or password protected non-SQL table you want to log on to, for example "P2SODBC.DLL". Note that the dllName must be enclosed in quotes. DLL names have the following naming convention: P2B*.DLL for standard (non-SQL) databases, P2S*.DLL for SQL/ODBC databases.
pServerName | Specifies the log on name for the server used to create the report. (For ODBC, use the data source name.) This value is case-sensitive. See Remarks below.
[pDatabaseName] | Specifies the name for the database used to create the report. See Remarks below.
[pUserID] | Specifies the User ID number necessary to log on to the server. See Remarks below.
[pPassword] | Specifies the password necessary to log on to the server.

*When you pass an empty string ("") for this parameter, the program uses the value that's already set in the report. If you want to override a value that's already set in the report, use a non-empty string (that is, "Server A").

Remarks

For parameters pServerName, pDatabaseName, and pUserId, pass an empty string ("") to preserve the existing setting or pass a non-empty string (for example, "Server A") to override a value that is already set in the report.


LogOnServerEx Method (Application Object)

The LogOnServer method logs on to an SQL server or other data sources such as ODBC. Using LogOnServerEx, you can pass server type or connection information. Once logged on using this method, you will remain logged on until you call LogOffServer Method (Application Object), or until the Application Object, is destroyed and craxdrt.dll is unloaded.

Syntax

Sub LogOnServerEx (pDllName As String, pServerName As String,

[pDatabaseName], [pUserID], [pPassword],

[pServerType], [pConnectionString])

Parameters

Parameter | Description
pDLLName | Specifies the name of the DLL for the server or password protected non-SQL table you want to log on to, for example "P2SODBC.DLL". Note that the dllName must be enclosed in quotes. DLL names have the following naming convention: P2B*.DLL for standard (non-SQL) databases, P2S*.DLL for SQL/ODBC databases.
pServerName | Specifies the log on name for the server used to create the report. (For ODBC, use the data source name.) This value is case-sensitive. See Remarks below.
[pDatabaseName] | Specifies the name for the database used to create the report. See Remarks below.
[pUserID] | Specifies the User ID number necessary to log on to the server. See Remarks below.
[pPassword] | Specifies the password necessary to log on to the server.
[pServerType] | Specifies the database Server Type.
[pConnectionString] | Specifies the connection string.


NewReport Method (Application Object)

The NewReport method creates a new empty Report Object.

Syntax

Function NewReport () As Report

Returns
  • Returns a new empty Report Object.


OpenReport Method (Application Object)

The OpenReport method opens an existing report file, creating an instance of the Report object. Through the Report Object, you can change formatting, formulas, selection formulas, and sort fields for the report, then print, preview, or export the report.

Syntax

Function OpenReport (pFileName As String, [OpenMethod]) As Report

Parameters

Parameter | Description
pFileName | Specifies a string value indicating the file name and path of the report that you want to open.
OpenMethod | CROpenReportMethod. Specifies whether you want to open the report exclusively. If you do not provide this parameter the report is opened exclusively and it cannot be opened a second time.

Returns
  • Returns an instance of the Report Object if the report was successfully opened.
  • Returns 0 if the report file does not exist or if an error occurs.
Remarks
  • The OpenMethod parameter can take the values "0" (open by default) or "1" (open temporary copy). If you open a report as a temporary copy ("1"), you must save the report using the SaveAs Method (Report Object) rather than the Embeddable Designer's SaveReport Method in order to avoid a runtime error.


SetMatchLogOnInfo Method (Application Object)

The SetMatchLogOnInfo Method sets global match log on info option, matching the log on password.

Syntax

Sub SetMatchLogOnInfo (bl As Boolean)

Parameter

Parameter | Description
bl | Specifies whether the option is selected (TRUE).


Area Object

The Area Object represents an area in a report. An area is a group of like sections in the report (i.e., Details A - Da, Details B - Db, etc.) that all share the same characteristics. Each section within the area can be formatted differently. This object allows you to retrieve information and set options for a specified area in your report.

Area Object Properties

Property | Description | Read/Write | Restriction in event handler
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
CopiesToPrint | Integer. Gets or sets the number of copies of each item in the Details section of the report. For example, by default, each line of the Details section only prints once. By setting this to 3, each line of the Details section would print 3 times. | Read/Write | Can be written only when formatting idle.
DetailHeight | Long. Gets the mailing label report detail area height, in twips. | Read only | None
DetailWidth | Long. Gets multiple column report detail area width, in twips. | Read only | None
DiscardOtherGroups | Boolean. Gets or sets the discard other groups option. | Read/Write |
EnableHierarchicalGroupSorting | Boolean. Gets or sets group hierarchically flag. | Read/Write | Formatting idle.
GroupCondition | CRGroupCondition. Gets or sets the group condition. | Read/Write | Can be written only when formatting idle.
GroupConditionField | Object. Gets or sets the group condition field. | Read/Write | Can be written only when formatting idle.
GroupIndent | Long. Gets or sets group indent, in twips. | Read/Write | Formatting idle.
GroupNumber | Integer. If the area is a group area, this returns the group number. Otherwise, exception is thrown. | Read only | None
HideForDrillDown | Boolean. Gets or sets hide for drill down option. | Read/Write | Can be written only when formatting idle.
HorizontalGap | Long. Gets the horizontal gaps going across page in a multiple column report. | Read only | None
InstanceIDField | A field definition object. Gets the instance ID field. See Remarks. | Read only | Formatting idle.
KeepGroupTogether | Boolean. Gets or sets the keep group together option. | Read/Write | Can be written only when formatting idle.
KeepTogether | Boolean. Gets or sets the keep area together option. | Read/Write | Can be written only when formatting idle.
Kind | CRAreaKind. Gets which kind of area (for example, Details, Report Header, Page Footer, etc.). | Read only | None
Name | String. Gets or sets the area name. | Read/Write | Can be written only when formatting idle.
NewPageAfter | Boolean. Gets or sets the new page after options. | Read/Write | Can be written only when formatting idle.
NewPageBefore | Boolean. Gets or sets the new page before option. | Read/Write | Can be written only when formatting idle.
NumberOfTopOrBottomNGroups | Integer. Gets or sets the number of top or bottom groups. | Read/Write | Formatting idle.
Parent | Report Object. Gets reference to the parent object. | Read Only | None
ParentIDField | A field definition object. Gets the parent ID field. See Remarks. | Read only | Formatting idle.
PrintAtBottomOfPage | Boolean. Gets or sets the print at bottom of page option. | Read/Write | Can be written only when formatting idle.
RepeatGroupHeader | Boolean. Gets or sets the repeating group header option. | Read/Write | Can be written only when formatting idle.
ResetPageNumberAfter | Boolean. Gets or sets the reset page number after option. | Read/Write | Can be written only when formatting idle.
Sections | Sections Collection. Gets a Collection of all the sections in the area. | Read Only | None
SortDirection | CRSortDirection. Gets or sets the group sort direction. | Read/Write | Can be written only when formatting idle.
SpecifiedGroups | Gets or sets the specified groups. | Read/Write | Can be written only when formatting idle.
Suppress | Boolean. Gets or sets the area visibility. | Read/Write | Can be written only when formatting idle.
TopOrBottomNGroupSortOrder | CRTopOrBottomNGroupSortOrder. Gets or sets the top or bottom N group sort order. | Read/Write | Formatting idle.
TopOrBottomNSortField | SummaryFieldDefinition Object. Gets or sets the top or bottom n sort field. | Read/Write | Formatting idle.

Remarks

After getting the field definition object from the InstanceIDField or the ParentIDField property, you can use the Kind property to determine what type of field definition object it is. All field definition objects have the Kind property.


Area Object Methods

The following methods are discussed in this section:

  • SetInstanceIDField Method (Area Object)
  • SetParentIDField (Area Object)


SetInstanceIDField Method (Area Object)

Use the SetInstanceIDField method to set an instance ID field.

Syntax

Sub SetInstanceIDField (InstanceIDField)

Parameter

Parameter | Description
InstanceIDField | Specifies the instance ID field that you want to set.


SetParentIDField (Area Object)

Use the SetParentIDField method to set the parent ID field.

Syntax

Sub SetParentIDField (ParentIDField)

Parameter

Parameter | Description
ParentIDField | Specifies the parent ID field that you want to set.


Areas Collection

The Areas Collection contains the area objects for every area in the report. Access a specific Area Object in the collection using the Item property.

Areas Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of areas in the collection. | Read only | None
Item (index) | Area Object. Gets an item from the Collection. Item has an index parameter that can be either a string reference to the area (for example, "RH", "PH", "GHn", "D", "GFn", "PF", or "RF") or a numeric, 1-based index (for example, Item (1) for the Report Header area). The items in the collection are indexed in the order they are listed for each section/area. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None

Remarks

Instead of using the Item property as shown, you can reference an area directly (for example, Areas("RH") or Areas(1)).


BlobFieldObject Object

The BlobFieldObject Object allows you to get and set information for bitmap database fields in a report.

BlobFieldObject Object Properties

Examples

Property | Description | Read/Write | Restriction in event handler
BackColor | OLE_COLOR. Gets or sets the object background color. | Read/Write | Can be written only when formatting idle or active.
BorderColor | OLE_COLOR. Gets or sets the object border color. | Read/Write | Can be written only when formatting idle or active.
BottomCropping | Long. Gets or sets bottom cropping size, in twips. | Read/Write | Can be written only when formatting idle.
BottomLineStyle | CRLineStyle. Gets or sets the bottom line style. | Read/Write | Can be written only when formatting idle or active.
CloseAtPageBreak | Boolean. Gets or sets the close border on page break. | Read/Write | Can be written only when formatting idle or active.
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
CssClass | String. Gets or sets the cascading style sheet Class. | Read/Write | Can be written only when formatting idle.
Field | DatabaseFieldDefinition Object. Gets the database field definition object containing information about the BLOB field. | Read only | None
HasDropShadow | Boolean. Gets or sets the border drop shadow option. | Read/Write | Can be written only when formatting idle or active.
Height | Long. Gets or sets the object height, in twips. | Read/Write | Can be written only when formatting idle or active.
KeepTogether | Boolean. Gets or sets the keep object together option. | Read/Write | Can be written only when formatting idle or active.
Kind | CRObjectKind. Gets CRObjectKind which specifies the kind of object (for example, box, cross-tab, field, etc.). | Read only | None
Left | Long. Gets or sets the object upper left position, in twips. | Read/Write | Can be written only when formatting idle or active.
LeftCropping | Long. Gets or sets the left cropping size, in twips. | Read/Write | Can be written only when formatting idle.
LeftLineStyle | CRLineStyle. Gets or sets the left line style. | Read/Write | Can be written only when formatting idle or active.
Name | String. Gets or sets the object name. | Read/Write | Can be written only when formatting idle.
Parent | Section Object. Gets reference to the parent object. | Read only | None
RightCropping | Long. Gets or sets the right cropping size, in twips. | Read/Write | Can be written only when formatting idle.
RightLineStyle | CRLineStyle. Gets or sets the right line style. | Read/Write | Can be written only when formatting idle or active.
Suppress | Boolean. Gets or sets the object visibility. | Read/Write | Can be written only when formatting idle or active.
Top | Long. Gets or sets the object upper top position, in twips. | Read/Write | Can be written only when formatting idle or active.
TopCropping | Long. Gets or sets the top cropping size, in twips. | Read/Write | Can be written only when formatting idle.
TopLineStyle | CRLineStyle. Gets or sets the top line style. | Read/Write | Can be written only when formatting idle or active.
Width | Long. Gets or sets the object width, in twips. | Read/Write | Can be written only when formatting idle or active.
XScaling | Double. Gets or sets the width scaling factor. For example, 1 means 100%, 2 means 200%, 0.5 means 50% etc. The scaling factor may range from 0.01 to 100. | Read/Write | Can be written only when formatting idle.
YScaling | Double. Gets or sets the height scaling factor. For example, 1 means 100%, 2 means 200%, 0.5 means 50% etc. The scaling factor may range from 0.01 to 100. | Read/Write | Can be written only when formatting idle.


BoxObject Object

The Box Object represents a box that has been drawn on the report. This object allows you to get information about boxes in a report.

BoxObject Object Properties

Examples

Property | Description | Read/Write | Restriction in event handler
Bottom | Long. Gets or sets the object lower bottom position, in twips. | Read/Write | Can be written only when formatting idle.
BottomRightSection | Section Object. Gets the bottom right section. | Read only | Can be written only when formatting idle.
CloseAtPageBreak | Boolean. Gets or sets the close border on page break option. | Read/Write | Can be written only when formatting idle.
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
CornerEllipseHeight | Long. Gets or sets the corner elipse height, in twips. | Read/Write |
CornerEllipseWidth | Long. Gets or sets the corner elipse width, in twips. | Read/Write |
CssClass | String. Gets or sets the cascading style sheet Class. | Read/Write | Can be written only when formatting idle.
ExtendToBottomOfSection | Boolean. Gets or sets the extend to bottom of section option. | Read/Write | Can be written only when formatting idle.
FillColor | OLE_COLOR. Gets or sets the fill color. | Read/Write | Can be written only when formatting idle.
HasDropShadow | Boolean. Gets or sets the border drop shadow option.. | Read/Write | Can be written only when formatting idle.
Kind | CRObjectKind. Gets which kind of object (for example, box, cross-tab, field, etc.). | Read only | None
Left | Long. Gets or sets the upper left position, in twips. | Read/Write | Can be written only when formatting idle or active.
LineColor | OLE_COLOR. Gets or sets the line color. | Read/Write | Can be written only when formatting idle.
LineStyle | CRLineStyle. Gets or sets the line style. | Read/Write | Can be written only when formatting idle.
LineThickness | Long. Gets or sets the line thickness, in twips. | Read/Write | Can be written only when formatting idle.
Name | String. Gets or sets the object name. | Read/Write | Can be written only when formatting idle.
Parent | Section Object. Gets reference to the parent object. | Read only | None
Right | Long. Gets or sets the object lower right position, in twips. | Read/Write | Can be written only when formatting idle.
Suppress | Boolean. Gets or sets the object visibility. | Read/Write | Can be written only when formatting idle.
Top | Long. Gets or sets the object upper top position, in twips. | Read/Write | Can be written only when formatting idle.


ConnectionProperty Object

The ConnectionProperty Object is a property bag that stores connection information for the report. Information is dependent on the Business Objects database DLL used by the report and the database drivers that support the DLL. The collection of ConnectionProperty objects can hold common properties defined in our database DLLs, connection properties from the supporting drivers, or both. For example a report based off an OLEDB (ADO) connection to Microsoft SQL Server will contain properties supplied by the database DLL (crdb_ado.dll) such as Provider, Data Source, Initial Catalog, User ID, and Password, as well as the properties supplied by the supporting drivers such as Local Identifier, Connect Timeout and so on. The values for these properties can be set to connect to the current data source for the report or to change the data source for the report.

For more information on the common connection properties see Common Connection Properties.

ConnectionProperty Object Properties

Examples

Property | Description | Read/Write | Restriction in event handler
ChildProperties | ConnectionProperties Collection. Gets the child properties of this connection property in a hierarchal property structure. | Read only | None
Description | String. Gets or sets the description of the connection property. | Read/Write | None
LocalizedName | String. Gets or sets the localized name of the connection property. | Read/Write | None
Name | String. Gets or sets the name of the connection property. | Read/Write | None
Value | Variant. Gets or Sets the value of the connection property. Note: Some Values are Write only. For example the value for the Password connection property. | Read/Write | None


Common Connection Properties

The following table lists the connection properties defined in the Crystal Decisions database DLLs. Use these properties when connecting to the desired data source.

Data source | Connection property name | Connection property value description | Remarks
ODBC (RDO) crdb_odbc.dll |  |  |
 | Connection String | String. The complete connection string containting the driver information. This can be obtained from content of a File DSN. | DSN, FILEDSN and Connection String are mutually exclusive
 | Database | String. The name of the database. | This property can be used together with the DSN, FILEDSN, and Connection String.
 | Database Type | String. The type of file. For example: ODBC (RDO) - or - OLE DB (ADO) | This is an optional property.
 | DSN | String. The ODBC data sourec name. | DSN, FILEDSN and Connection String are mutually exclusive.
 | FILEDSN | String. Path to the File DSN. | DSN, FILEDSN and Connection String are mutually exclusive
 | Password | String. The password used to connect to the data source. | This property can be used together with the DSN, FILEDSN, and Connection String.
 | Trusted_Connection | Boolean. Set to True if you want the connection to use NT Authentication. | This property can be used together with the DSN, FILEDSN, and Connection String.
 | User ID | String. The user name required to connect to the data source. | This property can be used together with the DSN, FILEDSN, and Connection String.
OLE DB (ADO) crdb_ado.dll |  |  |
 | Data Source | String. The data source that the OLE DB provider is connected to such as a file path and database name or a server name. | This property can be used together with the Provider and Microsoft Data Link File.
 | Database | String. The name of the database. | This property can be used together with the Provider and Microsoft Data Link File.
 | Database Type | String. The type of file. For example: ODBC (RDO) - or - OLE DB (ADO) | This is an optional property.
 | Integrated Security | Boolean. Set to True if you want the connection to use NT Authentication. | This property can be used together with the Provider and Microsoft Data Link File.
 | Microsoft Data Link File | String. The file path to the Data Link. | Provider and Microsoft Data Link File are mutually exclusive.
 | Password | String. The password used to connect to the data source. | This property can be used together with the Provider and Microsoft Data Link File.
 | Provider | The name of the OLEDB provider. For example: Microsoft.Jet.OLEDB.4.0 -or- SQLOLEDB | Provider and Microsoft Data Link File are mutually exclusive.
 | User ID | String. The user name required to connect to the data source. | This property can be used together with the Provider and Microsoft Data Link File.
Access/Excel (DAO) crdb_dao.dll |  |  |
 | Database Name | String. The full file path to the databse. | This property is required for changing the location and name of the database.
 | Database Password | String. The password used to connect to the data source. | This property is only required if the daabse has database level security.
 | Database Type | String. The type of file. For example: ODBC (RDO) - or - OLE DB (ADO) | This is an optional property.
 | Session Password | String. The password for a system DSN. | You must provide System Database Path if Session UserID and Session Password are provided.
 | Session UserID | String. The user name for a system DSN. | You must provide System Database Path if Session UserID and Session Password are provided.
 | System Database Path | String. | You must provide System Database Path if Session UserID and Session Password are provided.
Oracle crdb_oracle.dll |  |  |
 | Database Type | String. The type of file. For example: ODBC (RDO) - or - OLE DB (ADO) | This is an optional property.
 | Server | String. The Service name. |
 | Password | String. The password used to connect to the data source. |
 | User ID | String. The user name required to connect to the data source. |
Native connections to local databases. crdb_p2b*.dll |  |  | These include Act!, Btrieve, DB2, Dbase, FoxPro, Paradox and so on.
 | Database Path | String. The full file path to the database. | This property is required for changing the location and name of the database.
 | Database Type | String. The type of file. For example: ODBC (RDO) - or - OLE DB (ADO) | This is an optional property.
 | Password | String. The password used to connect to the data source. |
 | User ID | String. The user name required to connect to the data source. |
Native connections to server data sources. crdb_p2s*.dll |  |  | These include Informix, DB2 Server, Lotus Domino, and so on.
 | Database | String. The database name. |
 | Database Type | String. The type of file. For example: ODBC (RDO) - or - OLE DB (ADO) | This is an optional property.
 | Server | String. The server name. |
 | Password | String. The password used to connect to the data source. |
 | User ID | String. The user name required to connect to the data source. |
Field Definitions Only crdb_fielddef.dll |  |  |
 | Database Type | String. The type of file. For example: ODBC (RDO) - or - OLE DB (ADO) | This is an optional property.
 | Field Definition File | String. The full file and path to the Field defintion file (*.ttx). |
File Systam Data crdb_FileSystem.dll |  |  |
 | Database Type | String. The type of file. For example: ODBC (RDO) - or - OLE DB (ADO) | This is an optional property.
 | File Mask | String. A mask to filter the types of files returned. For example: *.exe |
 | Include Empty Directories | Boolean. Set to True to include empty directories. |
 | Max Number of Subdirectory Levels | Integer. The number of subdirectory levels to include. | Set this value to -1 to include all subdirectories.
 | Starting Directory | String. The path to the starting directory. |


ConnectionProperties Collection

The ConnectionProperties Collection is a collection of ConnectionProperty Object in a report. Each object in the collection is a property bag that contains information on a connection property. Use the Item property to access a specific ConnectionProperty Object in the Collection.

For more information on the common connection properties see Common Connection Properties.

ConnectionProperties Collection Properties

Examples

Property | Definition | Read/Write | Restriction in event handler
Count | Long. Gets the number of objects in the collection. | Read only | None
Item (indexAs Long) | ConnectionProperty Object. Gets an item from the Collection specified by name. | Read only | None
NameIds | Variant. Returns an array containing the name of each connection property in the collection. | Read only | None


ConnectionProperties Collection Methods

The following methods are discussed in this section:

  • Add Method (ConnectionProperties Collection)
  • Delete Method (ConnectionProperties Collection)
  • DeleteAll Method (ConnectionProperties Collection)


Add Method (ConnectionProperties Collection)

Use the Add method to add a ConnectionProperty Object to the Collection as a name value pair.

Examples
Syntax

Function Add (Name As String, Value)

Parameter | Description
Name | Specifies the name of the connection property that you want to add to the Collection.
Value | Specifies the value of the connection property.

Remarks

Use this method if alternate connection properties are required to establish a connection to a new data source. For example changing the report's database driver through the DLLName property in the DatabaseTable Object, or connecting to a report created off an OLEDB (ADO) data source to a different provider (Microsoft.Jet.OLEDB.4.0 to SQLOLEDB). Use the Delete Method (ConnectionProperties Collection) or the DeleteAll Method (ConnectionProperties Collection)to remove any connection properties.


Delete Method (ConnectionProperties Collection)

Use the Delete method to remove a ConnectionProperty Object from the Collection.

Examples
Syntax

Sub Delete (index)

Parameter

Parameter | Description
index | Specifies the index number of the Object that you want to remove from the Collection.

Remarks

Use this method to remove any connection properties that are no longer required when connecting to a new data source. For example changing the report's database driver through the DLLName property in the DatabaseTable Object, or connecting a report created off an OLEDB (ADO) data source to a different provider (Microsoft.Jet.OLEDB.4.0 to SQLOLEDB). Use the Add Method (ConnectionProperties Collection) to add any new connection properties.


DeleteAll Method (ConnectionProperties Collection)

Use the Delete method to remove all ConnectionProperty Objects from the Collection.

Examples
Syntax

Sub DeleteAll ()

Remarks

Use this method to remove all existing connection properties when connecting to a new data source. For example changing the report's database driver through the DLLName property in the DatabaseTable Object, or connecting a report created off an OLEDB (ADO) data source to a different provider (Microsoft.Jet.OLEDB.4.0 to SQLOLEDB). Use the Add Method (ConnectionProperties Collection) to add any new connection properties.


CrossTabGroup Object

The CrossTabGroup Object contains information related to CrossTabGroups in a report.

CrossTabGroup Properties

Examples

Property | Description | Read/Write | Restriction in event handler
BackColor | OLE_COLOR. Gets or sets the crosstab group background color. | Read/Write | Idle
Condition | CRGroupCondition. Gets or sets the crosstab group condition. | Read/Write | Idle
EnableSuppressLabel | Boolean. Gets or sets the crosstab group enable suppress label option. | Read/Write | Idle
EnableSuppressSubtotal | Boolean. Gets or sets the crosstab group enable suppress subtotal option. | Read/Write | Idle
Field | A field definition object. Gets or sets the crosstab group's field. See Remarks. | Read/Write | Idle
Parent | CrossTabObject Object. Gets reference to the crosstab group parent object. | Read only | None
SortDirection | CRSortDirection. Gets or sets the crosstab group sort direction. | Read/Write | Idle

Remarks

After getting the field definition object from the Field property, you can use the Kind property to determine what type of field definition object it is. All field definition objects have the Kind property.


CrossTabGroups Collection

The CrossTabGroups Collection contains CrossTabGroup Objects associated with a report.

CrossTabGroups Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the CrossTabGroup count. | Read only | None
Item (index As Long) | CrossTabGroup Object. Gets an item from the Collection. | Read only | None
Parent | CrossTabObject Object. Gets reference to the parent object. | Read only | None


CrossTabGroups Collection Methods

The following methods are discussed in this section:

  • Add Method (CrossTabGroups Collection)
  • Delete Method (CrossTabGroups Collection)


Add Method (CrossTabGroups Collection)

Examples

Use the Add method to add a field as a CrossTabGroup to the CrossTabGroups Collection.

Syntax

Function Add (Field) As CrossTabGroup

Parameter

Parameter | Description
Field | Specifies the field that you want to add as a CrossTabGroup to the Collection.

Returns

Returns a CrossTabGroup Object member of the Collection.


Delete Method (CrossTabGroups Collection)

Examples

Use the Delete method to remove a CrossTabGroup Object from the Collection.

Syntax

Sub Delete (index As Long)

Parameter

Parameter | Description
index | Specifies the index of the CrossTabGroup Object that you want to delete from the Collection.


CrossTabObject Object

The CrossTabObject Object allows you to get and set information for cross-tab objects in a report.

CrossTabObject Object Properties

Property | Description | Read/Write | Restriction in event handler
BackColor | OLE_COLOR. Gets or sets the object background color. | Read/Write | Can be written only when formatting idle or active.
BorderColor | OLE_COLOR. Gets or sets the object border color. | Read/Write | Can be written only when formatting idle or active.
BottomLineStyle | CRLineStyle. Gets or sets the bottom line style. | Read/Write | Can be written only when formatting idle or active.
CloseAtPageBreak | Boolean. Gets or sets the close border on page break option. | Read/Write | Can be written only when formatting idle or active.
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
ColumnGrandTotalColor | OLE_COLOR. Gets or sets the column grand total color. | Read/Write | Idle
ColumnGroups | Remarks. Gets the column groups Collection. | Read only | None
CssClass | String. Gets or sets the cascading style sheet Class. | Read/Write | Can be written only when formatting idle.
EnableKeepColumnsTogether | Boolean. Gets or sets the enable keep columns together option. | Read/Write | Idle
EnableRepeatRowLabels | Boolean. Gets or sets the enable repeat row labels option. | Read/Write | Idle
EnableShowCellMargins | Boolean. Gets or sets the enable show cell margins option. | Read/Write | Idle
EnableShowGrid | Boolean. Gets or sets the enable show grid option. | Read/Write | Idle
EnableSuppressColumnGrandTotals | Boolean. Gets or sets the enable suppress column grand totals option. | Read/Write | Idle
EnableSuppressEmptyColumns | Boolean. Gets or sets the enable suppress empty columns option. | Read/Write | Idle
EnableSuppressEmptyRows | Boolean. Gets or sets the enable suppress empty rows option. | Read/Write | Idle
EnableSuppressRowGrandTotals | Boolean. Gets or sets the enable suppress row grand totals option. | Read/Write | Idle
HasDropShadow | Boolean. Gets or sets the border drop shadow option. | Read/Write | Can be written only when formatting idle or active.
Height | Long. Gets the object height, in twips. | Read only | Can be written only when formatting idle or active.
KeepTogether | Boolean. Gets or sets the keep object together option. | Read/Write | Can be written only when formatting idle or active.
Kind | CRObjectKind. Gets which kind of object (for example, box, cross-tab, field, etc.). | Read only | None
Left | Long. Gets or sets the upper left position, in twips. | Read/Write | Can be written only when formatting idle or active.
LeftLineStyle | CRLineStyle. Gets or sets the left line style. | Read/Write | Can be written only when formatting idle or active.
Name | String. Gets or sets the object name. | Read/Write | Can be written only when formatting idle.
Parent | Section Object. Gets reference to the parent object. | Read only | None
RightLineStyle | CRLineStyle. Gets or sets the right line style. | Read/Write | Can be written only when formatting idle or active.
RowGrandTotalColor | OLE_COLOR. Gets or sets the row grand total color. | Read/Write | Idle
RowGroups | Remarks. Gets the row groups Collection. | Read Only | None
SummaryFields | ObjectSummaryFieldDefinitions Collection. Gets the summary fields. | Read Only | None
SpecifiedGroups | Gets or sets the specified groups from a row or column in the crosstab. | Read/Write | Can be written only when formatting idle
Suppress | Boolean. Gets or sets the object visibility option. | Read/Write | Can be written only when formatting idle or active.
Top | Long. Gets or sets the object upper top position, in twips. | Read/Write | Can be written only when formatting idle or active.
TopLineStyle | CRLineStyle. Gets or sets top line style. | Read/Write | Can be written only when formatting idle or active.
Width | Long. Gets the object width, in twips. | Read Only | Can be written only when formatting idle or active.


Database Object

The Database Object provides properties to get information about the database accessed by a report. See Overview of the Report Designer Object Model.

Database Object Properties

Property | Description | Read/Write | Restriction in event handler
Links | TableLinks Collection. Gets database link collection. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None
Tables | DatabaseTables Collection. Gets the DatabaseTables Collection which specifies the database objects used in the report (for example, an Access report may contain a query or a SQL Server report may be based on a stored procedure - if so, they will be returned as part of this collection along with the database table used in the report). | Read only | None


Database Object Methods

The following methods are discussed in this section:

  • AddADOCommand Method (Database Object)
  • AddOLEDBSource Method (Database Object)
  • LogOffServer Method (Database Object)
  • LogOnServer Method (Database Object)
  • LogOnServerEx Method (Application Object)
  • SetDataSource Method (Database Object)
  • Verify Method (Database Object)


AddADOCommand Method (Database Object)

Use the AddADOCommand method to add a database table to your report through an ADO connection and command.

Syntax

Sub AddADOCommand (pConnection, pCommand)

Parameters

Parameter | Description
pConnection | Specifies the ADO connection that you want to use.
pCommand | Specifies the ADO command that you want to use.


AddOLEDBSource Method (Database Object)

Use the AddOLEDBSource method to add a database table to your report through an OLE DB provider.

Syntax

Sub AddOLEDBSource (pConnectionString As String, pTableName As String)

Parameters

Parameter | Description
pConnectionString | Specifies the connection string for the OLE DB provider.
pTableName | Specifies the OLE DB database table that you want to add to your report.

Remarks

Some databases such as Oracle are case sensitive and require that proper case be applied to the database names and table names in the connection string.

'Instantiate the report object.

Set m_Report = New CrystalReport1

' Convert the database driver to ODBC.

m_Report.Database.ConvertDatabaseDriver "p2sodbc.dll", True

' Set the logon information for the ODBC data source.

' If the logon information is not set, an error will be produced when the

' report is previewed or exported.

m_Report.Database.Tables(1).SetLogOnInfo "Xtreme Sample Database 10", "", "", ""

' Verify the database.

' If the database is not verified before exporting, an error will be produced.

' If the database is not verified before previewing the report, the user may be

' prompted when the report is refreshed in the Crystal Report Viewer.

m_Report.Database.Verify


LogOffServer Method (Database Object)

The LogOffServer method logs off an SQL server, ODBC or other data source. Use this method when you have logged on to the data source using LogOnServer. This method can be invoked only in formatting Idle mode.

Syntax

Sub LogOffServer (pDllName As String, pServerName As String,

[pDatabaseName], [pUserID], [pPassword])

Parameters

Parameter | Description
pDllName | Specifies the name of the DLL for the server or password protected non-SQL table you want to log on to, for example "P2SODBC.DLL". Note that the dllName must be enclosed in quotes. DLL names have the following naming convention: P2B*.DLL for standard (non-SQL) databases, P2S*.DLL for SQL/ODBC databases.
pServerName | Specifies the log on name for the server used to create the report. For ODBC, use the data source name. This value is case-sensitive. See Remarks below.
[pDatabaseName] | Specifies the name for the database used to create the report. See Remarks below.
[pUserID] | Specifies the User ID number necessary to log on to the server. See Remarks below.
[pPassword] | Specifies the password necessary to log on to the server.

Remarks
  • When you pass an empty string ("") for pServerName, pDatabaseName, or pUserID, the program uses the value that's already set in the report. If you want to override a value that's already set in the report, use a non-empty string (for example, "Server A").
  • If you try to log off a server that is still in use (that is, there is an object variable still in focus that holds reference to a report that requires being logged on to the server to access data) you will be unable to log off. This will apply to every object that comes from the Report Object, as they all hold reference to the report through their respective Report properties.
  • If you assign the Report object to the ReportSource property of the CRViewer Object (CRVIEWERLib), in the Crystal Reports Report Viewer, enabling the report to be displayed through the Report Viewer, you cannot call LogOffServer for the report until you assign a new report to the Report Viewer or close the CRViewer object.


LogOnServer Method (Database Object)

The LogOnServer method logs on to an SQL server, ODBC or other data source. Once logged on using this method, you will remain logged on until you call LogOffServer or until the Application Object is destroyed and craxdrt.dll is unloaded. This method can be invoked only in formatting Idle mode.

Syntax

Sub LogOnServer (pDllName As String, pServerName As String,

[pDatabaseName], [pUserID], [pPassword])

Parameters

Parameter | Description
pDllName | Specifies the name of the DLL for the server or password protected non-SQL table you want to log on to, for example "P2SODBC.DLL". Note that the dllName must be enclosed in quotes. DLL names have the following naming convention: P2B*.DLL for standard (non-SQL) databases, P2S*.DLL for SQL/ODBC databases.
pServerName | Specifies the log on name for the server used to create the report. For ODBC, use the data source name. This value is case-sensitive. See Remarks below.
[pDatabaseName] | Specifies the name for the database used to create the report. See Remarks below.
[pUserID] | Specifies the User ID number necessary to log on to the server. See Remarks below.
[pPassword] | Specifies the password necessary to log on to the server.

Remarks

When you pass an empty string ("") for this parameter, the program uses the value that's already set in the report. If you want to override a value that's already set in the report, use a non-empty string (for example, "Server A").


LogOnServerEx Method (Database Object)

The LogOnServerEx method logs on to an SQL server, ODBC or other data source. Using this method, you can pass ServerType and ConnectionString info. Once logged on using this method, you will remain logged on until you call LogOffServer or until the Application Object is destroyed and craxdrt.dll is unloaded. This method can be invoked only in formatting Idle mode.

Syntax

Sub LogOnServerEx (pDllName As String, pServerName As String,

[pDatabaseName], [pUserID], [pPassword],

[pServerType], [pConnectionString])

Parameters

Parameter | Description
pDllName | Specifies the name of the DLL for the server or password protected non-SQL table you want to log on to, for example "P2SODBC.DLL". Note that the dllName must be enclosed in quotes. DLL names have the following naming convention: P2B*.DLL for standard (non-SQL) databases, P2S*.DLL for SQL/ODBC databases.
pServerName | Specifies the log on name for the server used to create the report. For ODBC, use the data source name. This value is case-sensitive. See Remarks below.
[pDatabaseName] | Specifies the name for the database used to create the report. See Remarks below.
[pUserID] | Specifies the User ID number necessary to log on to the server. See Remarks below.
[pPassword] | Specifies the password necessary to log on to the server.
[pServerType] | Specifies the database Server Type.
[pConnectionString] | Specifies the connection string.

Remarks

When you pass an empty string ("") for this parameter, the program uses the value that's already set in the report. If you want to override a value that's already set in the report, use a non-empty string (for example, "Server A").


SetDataSource Method (Database Object)

The SetDataSource method is used to provide information about a data source to the database driver associated with this Database object at runtime. For instance, if a report has been designed using the Crystal Active Data Driver this method can be used to provide an active data source for the report, such as a DAO, ADO, or RDO Recordset or a CDO Rowset. In this case, the object passed to the second parameter of this method replaces, at runtime, the field definition file used to create the report. This method can be invoked only in formatting Idle mode. When using a secure connection such as SQL Server, some additional code is required (see Remarks below).

Syntax

Sub SetDataSource (data, [dataTag], [tableNumber])

Parameters

Parameter | Description
data | Variant data passed to the database driver. For example, with Active data, this must be a Recordset object if you are using DAO, ADO, or the Visual Basic data control. This must be a Rowset object if you are using CDO.
[dataTag] | A value indicating the type of data being passed to the DatabaseTable object in the Data parameter. Currently, the only possible value is 3. This value must be used for all Active data sources including DAO, ADO, RDO, CDO, and the Visual Basic data control.
[tableNumber] | Specifies the index number of the table to be set. Default value = 1.

Remarks
  • When the data source uses a secure connection, such as SQL Server, additional information must be passed in the "form load" event before the call to view the report. For example,

    • DataEnvironment1.Command1

    Report.Database.SetDataSource (DataEnvironment1.rsCommand1)

  • SetDataSource method is used to set a datasource at runtime. If the report is initially created and then saved, and then later run using either the RDC or CRW, the runtime datasource (DAO, ADO, or RDO Recordset) cannot be recreated. The user will not be able to run or preview the report.


Verify Method (Database Object)

The Verify method verifies that the location of the database is still valid and checks to see if any changes have been made to table design, etc. If there are any changes to the database, the Verify method will update the report automatically to reflect these changes. See Remarks below. This method can be invoked only in formatting Idle mode.

Syntax

Sub Verify ()

Remarks

Prior to calling Verify, you can use the CheckDifferences Method (DatabaseTable Object) to determine what kind of differences, if any, exist between the report table and the physical table. pDifferences parameter of CheckDifferences method will pass back one or more bitwise (XOR'd) CRTableDifferences enums indicating the information that you want to retrieve.


DatabaseFieldDefinition Object

The DatabaseFieldDefinition Object represents a database field used in the report. This object provides properties for getting information on database fields in the report.

DatabaseFieldDefinition Object Properties

Property | Definition | Read/Write | Restriction in event handler
DatabaseFieldDisplayName | String. Gets the display name for the field in the database. | Read Only | None
DatabaseFieldName | String. Gets the name of the field in the database (for example, Product ID). | Read only | None
Kind | CRFieldKind. Gets which kind of field (for example, database, summary, formula, etc.). | Read only | None
Name | String. Gets the unique Crystal formula form name of the field within the report as {table.FIELD} (for example, {product.PRODUCT ID}). | Read only | None
NextValue | Variant. Gets the field next value. | Read only | Can be read only when top-level Report object is formatting active.
NumberOfBytes | Integer. Gets the number of bytes required to store the field data in memory. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None
PreviousValue | Variant. Gets the field previous value. | Read only | Can be read only when top-level Report object is formatting active.
TableAliasName | String. Gets the alias for the table containing the field. | Read only | None
Value | Variant. Gets the field current value. | Read only | Can be read only when top-level Report object is formatting active.
ValueType | CRFieldValueType. Gets which type of value is found in the field. | Read only | None


DatabaseFieldDefinitions Collection

The DatabaseFieldDefinitions Collection is a collection of database field definition objects. One object exists in the collection for every database field accessed by the report. Access a specific DatabaseFieldDefinition Object in the collection using the Item property.

DatabaseFieldDefinitions Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of DatabaseFieldDefinition Object, in the collection. | Read only | None
Item (index As Long) | DatabaseFieldDefinition Object. Item has an index parameter that is a numeric, 1-based index for the object that you want to retrieve (for example, Item (1) for the first database field in the collection). The items in the collection are indexed in the order they appear in the database table. | Read only | None
Parent | DatabaseTable Object. Reference to the parent object. | Read only | None

Remarks

Instead of using the Item property as shown, you can reference a database directly (for example, DatabaseFieldDefinitions(1)).

DatabaseFieldDefinitions Collection Methods

The following method is discussed in this section:

  • GetItemByName Method (DatabaseFieldDefinitions Collection)


GetItemByName Method (DatabaseFieldDefinitions Collection)

Use the GetItemByName method to retrieve a DatabaseFieldDefinition object by name.

Syntax

Sub GetItemByName(name As String, databaseFieldDefinition)

Parameters

Parameter | Description
name | The item's unique name.
databaseFieldDefinition | DatabaseFieldDefinition Object. An object to hold the retrieved item.


DatabaseTable Object

The DatabaseTable Object refers to a database table accessed by the report.

DatabaseTable Object Properties

Examples

Property | Description | Read/Write | Restriction in event handler
ConnectBufferString | String. Gets the table connect buffer string. | Read only | None
ConnectionProperties | ConnectionProperties Collection. Gets the collection of connection properties from the table. | Read only | None.
DatabaseType | CRDatabaseType. Gets the database table type | Read only | None
DescriptiveName | String. Gets the table descriptive name. | Read only | None
DllName | String. Gets the table driver DLL name. | Read only | None
Fields | DatabaseFieldDefinitions Collection Properties. Gets the collection of database fields in the table. | Read only | None
Location | String. Gets or sets the location of the database table. | Read/Write | Can be written only when formatting idle.
Name | String. Gets or sets the alias name for the database table used in the report. | Read/Write | Can be written only when formatting idle.
Parent | Database Object. Reference to the parent object. | Read only | None


DatabaseTable Object Methods

The following methods are discussed in this section:

  • CheckDifferences Method (DatabaseTable Object)
  • SetDataSource Method (DatabaseTable Object)
  • SetTableLocation Method (DatabaseTable Object)
  • TestConnectivity Method (DatabaseTable Object)


CheckDifferences Method (DatabaseTable Object)

Use the CheckDifferences method to determine what kind(s) of differences were found between the report table and the physical table.

Syntax

Sub CheckDifferences (pDifferences As Long, [reserved])

Parameters

Parameter | Description
pDifferences | CRTableDifferences. Bitwise constants specify the table difference(s) (XOR'd), if any.
[reserved] | Reserved. Do not use.


SetDataSource Method (DatabaseTable Object)

The SetDataSource method is used to provide information about a data source to the database driver associated with this DatabaseTable object at runtime. For instance, if a report has been designed using the Crystal Active Data Driver this method can be used to provide an active data source for the report, such as a DAO, ADO, or RDO Recordset or a CDO Rowset. In this case, the object passed to the second parameter of this method replaces, at runtime, the field definition file used to create the report. This method can be invoked only in formatting Idle mode. When using a secure connection such as SQL Server, some additional code is required (see Remarks below).

Syntax

Sub SetDataSource (data, [dataTag])

Parameters

Parameter | Description
data | Variant data passed to the database driver. For example, with Active data, this must be a Recordset object if you are using DAO, ADO, or the Visual Basic data control. This must be a Rowset object if you are using CDO.
[dataTag] | A value indicating the type of data being passed to the DatabaseTable object in the Data parameter. Currently, the only possible value is 3. This value must be used for all Active data sources including DAO, ADO, RDO, CDO, and the Visual Basic data control.

Remarks
  • When the data source uses a secure connection, such as SQL Server, additional information must be passed in the "form load" event before the call to view the report. For example,

    • DataEnvironment1.Command1

    Report.DatabaseTable.SetDataSource (DataEnvironment1.rsCommand1)

  • SetDataSource method is used to set a datasource at runtime. If the report is initially created and then saved, and then later run using either the RDC or CRW, the runtime datasource (DAO, ADO, or RDO Recordset) cannot be recreated. The user will not be able to run or preview the report.


SetTableLocation Method (DatabaseTable Object)

The SetTableLocation method is used to set the DatabaseTable location, sublocation, and connect buffer string.

Examples
Syntax

Sub SetTableLocation (pLocation As String, pSubLocation As String,

pConnectBufferSting As String)

Parameters

Parameter | Description
pLocation | Specifies the location of the database table (file path and name.ext).
pSubLocation | Specifies the sublocation of the database table.
pConnectBufferSting | Specifies the connection buffer string.

Remarks

For example:

object.SetTableLocation "xtreme.mdb", "Customer", ""


TestConnectivity Method (DatabaseTable Object)

The TestConnectivity method tests to see if the database can be logged on to with the current information and if the database table can be accessed by the report.

Syntax

Function TestConnectivity () As Boolean

Returns
  • TRUE if the database session, log on, and location information is all correct.
  • FALSE if the connection fails or an error occurs.


DatabaseTables Collection

The DatabaseTables Collection is a collection of DatabaseTable objects. A DatabaseTable object exists for every database object (for example, table, query, stored procedure, etc.) accessed by the report. Access a specific DatabaseTable Object in the collection using the Item property.

DatabaseTables Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of database objects in the collection. | Read only | None
Item (indexAs Long) | DatabaseTable Object. Item has an index parameter that is a numeric, 1-based index (for example, Item (1)). The items in the collection are indexed in the order in which they were added to the report. | Read only | None
Parent | Database Object. Reference to the parent object. | Read only | None

Remarks

Instead of using the Item property as shown, you can reference a table directly (for example, DatabaseTable(1)).


DatabaseTables Collection Methods

The following methods are discussed in this section:

  • Add Method (DatabaseTables Collection)
  • AddStoredProcedure Method (DatabaseTables Collection)
  • Delete Method (DatabaseTables Collection)


Add Method (DatabaseTables Collection)

Use the Add method to add a database table to the report.

Syntax

Sub Add (pLocation As String, [pSubLocation], [pConnectInfo],

[tableType], [pDllName], [pServerName], [pServerType],

[pDatabaseName], [pUserID], [pPassword])

Parameters

Parameter | Description
pLocation | Specifies the location of the database table that you want to add to the report.
[pSubLocation] | Specifies the sublocation of the database table that you want to add to the report.
[pConnectInfo] | Specifies the connection string.
[tableType] | Specifies the type of database table that you want to add to the report.
[pDllName] | Specifies the DLL name for the database containing the table that you want to add.
[pServerName] | Specifies the database Server Name.
[pServerType] | Specifies the database Server Type.
[pDatabaseName] | Specifies the database (file path and name.ext) containing the table that you want to add.
[pUserID] | Specifies the User's ID.
[pPassword] | Specifies the User's Password.

Remarks
  • DatabaseTables.Add method is very generic and can be used to add tables to a report from all kinds of data sources (for example, PC Table, SQL Server, ODBC, OLE DB provider, ADO, RDO, DAO Recordset).
  • For example:

    • object.Add "xtreme.mdb", "Customer"

  • You may use Add() to add a stored procedure to a report. No inital values are passed to the procedure's parameters so you need to set the values later using other API functions. To pass parameter values at the time of adding the stored procedure, use the AddStoredProcedure Method (DatabaseTables Collection) instead.


AddStoredProcedure Method (DatabaseTables Collection)

Use the AddStoredProcedure method to add a stored procedure and its initial parameter values to the report.

Syntax

Sub AddStoredProcedure (pLocation as String,

[pSubLocation],[pConnectionInfo],[tableType],[pDllName],

[pServerType],[pDatabaseName],[pUserID],[pPassword],[paramValueInfos])

Parameters

Parameter | Description
pLocation | Specifies the location of the database table that you want to add to the report.
[pSubLocation] | Specifies the sublocation of the database table that you want to add to the report.
[pConnectInfo] | Specifies the connection string.
[tableType] | Specifies the type of database table that you want to add to the report.
[pDllName] | Specifies the DLL name for the database containing the table that you want to add.
[pServerName] | Specifies the database Server Name.
[pServerType] | Specifies the database Server Type.
[pDatabaseName] | Specifies the database (file path and name.ext) containing the table that you want to add.
[pUserID] | Specifies the User's ID.
[pPassword] | Specifies the User's Password.
[ParamValuesInfos] | ParameterValueInfos Collection. Specifies the initial values for the stored procedure's parameters.

Remarks

AddStoredProcedure() has one additional parameter that Add() does not have: ParamValuesInfos. This parameter allows the initial values for the stored procedure's parameters to be passed at the same time as the procedure is added to the report. If you do not want to pass initial parameter values, use Add Method (DatabaseTables Collection) instead.


Delete Method (DatabaseTables Collection)

Use the Delete method to remove a database table from the Collection.

Syntax

Sub Delete (index As Long)

Parameter

Parameter | Description
index | Specifies the 1-based index number in the Collection of the database table that you want to delete.


ExportOptions Object

The ExportOptions object provides properties and methods for retrieving information and setting options for exporting your report (that is, export format, destination, etc.). An ExportOptions Object is obtained from the ExportOptions property of the Report Object.

ExportOptions Object Properties

Property Description Read/Write Restriction in event handler

ApplicationFileName

String. Gets or sets the destination application file name.

Read/Write

Set before exporting report to an application destination.

CharFieldDelimiter

String. Gets or sets the character used to separate fields in character separated text formats. This character delimits every field in the file.

Read/Write

None

CharStringDelimiter

String. Gets or sets the character used to enclose string values in character separated text formats.

In general, this character delimits only string fields (number, date fields, etc., have no delimiter). However, if a field that is generally not delimited contains either 1) a field separator character, 2) a field delimiter character, or 3) a newline, then that field must be delimited.

Read/Write

None

DestinationDLLName

String. Gets the Internal Name property of the DLL used to export the report to a certain destination. The destination is set in the DestinationType property.

Read only

None

DestinationType

CRExportDestinationType. Gets or sets the export destination type.

Read/Write

None

DiskFileName

String. Gets or sets the file name if the report is exported to a disk.

When exporting to HTML use HTMLFileName. When exporting to XML use XMLFileName.

Read/Write

None

ExcelAreaGroupNumber

Integer. Gets or sets the base area group number if the area type is group area when exporting to Excel.

Read/Write

None

ExcelAreaType

CRAreaKind. Gets or sets the base area type if not using constant column width when exporting to Excel.

Read/Write

None

ExcelChopPageHeader

Boolean. Specifies whether page headers are to be simplified when exporting to Excel format.

Read/Write

None

ExcelConstantColumnWidth

Double. Gets or sets the column width when exporting to Excel.

Read/Write

None

ExcelConvertDateToString

Boolean. Gets or sets export to Excel has converting date values to strings option.

Read/Write

None

ExcelExportAllPages

Boolean. Gets or sets export to Excel with all pages.

Read/Write

None

ExcelExportImagesInDataOnly

Boolean. Specifies whether the images are exported.

Read/Write

None

ExcelExportPageAreaPair

CRExcelExportPageAreaPair. Specifies how the page header and footer pair are to be exported.

Read/Write

None

ExcelFirstPageNumber

Long. Gets or sets export to Excel for first page number.

Read/Write

None

ExcelLastPageNumber

Long. Gets or sets export to Excel for last page number.

Read/Write

None

ExcelMaintainColumnAlignment

Boolean. Specifies whether column alignment is maintained when exporting to Excel format.

Read/Write

None

ExcelMaintainRelativeObjectPosition

Boolean. Specifies whether relative object position is maintained upon export.

Read/Write

None

ExcelPageBreaks

Boolean. Gets or sets export to Excel has page break option.

Read/Write

None

ExcelShowGridLines

Boolean. Specifies whether gridlines will show in the exported report.

Read/Write

None

ExcelTabHasColumnHeadings

Boolean. Gets or sets exporting to Excel has column headings option.

Read/Write

None

ExcelUseConstantColumnWidth

Boolean. Gets or sets export to Excel to use constant column width.

Read/Write

None

ExcelUseFormatInDataOnly

Boolean. Specifies whether object formats like font attributes and text color are exported in Excel Data Only format.

Read/Write

None

ExcelUseTabularFormat

Boolean. Gets or sets exporting to Excel to use tabular format.

Read/Write

None

ExcelUseWorksheetFunctions

Boolean. Gets or sets export to Excel to use worksheet functions to represent subtotal fields in the report.

Read/Write

None

ExchangeDestinationType

CRExchangeDestinationType. Gets or sets the Exchange destination type for reports exported to Exchange folders.

Read/Write

None

ExchangeFolderPath

String. Gets or sets the path of the Exchange folder for reports exported to Exchange (for example, "MyFolders@Inbox").

Read/Write

None

ExchangePassword

String. Sets Exchange password.

Write only

None

ExchangeProfile

String. Gets or sets a user profile for accessing an Exchange folder for reports exported to Exchange.

Read/Write

None

ExchangePathHasColumnHeadings

Boolean. Gets or sets the column heading option when exporting to Exchange.

Read/Write

None

FormatDLLName

String. Gets the Internal Name property of the DLL used to export the report to a certain format type. The export format type is set in the FormatType property.

Read only

None

FormatType

CRExportFormatType. Gets or sets the format type for the exported report (for example, text, Excel, etc.).

Read/Write

None

HTMLEnableSeperatedPages

Boolean. Gets or sets the option to create seperated pages when exporting to HTML format.

Read/Write

None

HTMLFileName

String. Gets or sets the HTML file name for reports exported to HTML format.

Read/Write

None

HTMLHasPageNavigator

Boolean. Gets or sets the option to display a page navigator on each page of a report exported to HTML format.

Read/Write

None

LotusDominoComments

String. Gets or sets the destination Lotus Domino comments.

Read/Write

None

LotusDominoDatabaseName

String. Gets or sets the destination Lotus Domino database name.

Read/Write

None

LotusNotesFormName

String. Gets or sets the destination Lotus Domino form name.

Read/Write

None

MailBccList

String. Gets or sets a Blind Carbon Copy (BCC) list for reports e-mailed to a VIM e-mail account.

Read/Write

None

MailCcList

String. Gets or sets a Carbon Copy (CC) list for reports e-mailed.

Read/Write

None

MailMessage

String. Gets or sets the e-mail message included with e-mailed reports.

Read/Write

None

MailSubject

String. Gets or sets the e-mail subject heading for reports being e-mailed.

Read/Write

None

MailToList

String. Gets or sets the To list for reports being e-mailed.

Read/Write

None

MailUserName

String. Gets or sets mail user name.

Read/Write

None

NumberOfLinesPerPage

Integer. Gets or sets the number of lines to appear per page option for reports exported to a paginated text format.

Read/Write

None

ODBCDataSourceName

String. Gets or sets the ODBC data source for reports exported to ODBC.

Read/Write

None

ODBCDataSourcePassword

String. Sets the ODBC data source password.

Write only

None

ODBCDataSourceUserID

String. Gets or sets the user name used to access an ODBC data source for reports exported to ODBC.

Read/Write

None

ODBCExportTableName

String. Gets or sets the database table in the ODBC data source that the report file exported to ODBC will be appended to. You can also create a new table using this property.

Read/Write

None

Parent

Report Object. Reference to the parent object.

Read only

None

PDFExportAllPages

Boolean. Gets or sets whether or not to export all pages of the report to Portable Document Format(PDF). PDFExportAllPages must be set to false when setting PDFFirstPageNumber and PDFLastPageNumber.

Read/Write

None

PDFFirstPageNumber

Long. Gets or sets the start page, of a page export range, when exporting to PDF. PDFExportAllPages must be set to False or this value is ignored.

Read/Write

None

PDFLastPageNumber

Long. Gets or sets the end page, of a page export range, when exporting to PDF. PDFExportAllPages must be set to False or this value is ignored.

Read/Write

None

RTFExportAllPages

Boolean. Gets or sets whether or not to export all pages of the report to Rich Text Format(RTF). RTFExportAllPages must be set to false when setting RTFFirstPageNumber and RTFLastPageNumber.

Read/Write

None

RTFFirstPageNumber

Long. Gets or sets the start page, of a page export range, when exporting to RTF. RTFExportAllPages must be set to False or this value is ignored.

Read/Write

None

RTFFLastPageNumber

Long. Gets or sets the end page, of a page export range, when exporting to RTF. RTFExportAllPages must be set to False or this value is ignored.

Read/Write

None

UseDefaultCharactersPerInch

Boolean. Gets or sets use default characters per inch option.

Read/Write

None

UserDefinedCharactersPerInch

Long. Gets or sets user defined characters per inch.

Read/Write

None

UseReportDateFormat

Boolean. Gets or sets whether the date format used in the report should also be used in the exported report. Can be used for Data Interchange Format (DIF), Record Style Format, and comma, tab, or character separated format.

Read/Write

None

UseReportNumberFormat

Boolean. Gets or sets whether the number format used in the report should also be used in the exported report. Can be used for Data Interchange Format (DIF), Record Style Format, and comma, tab, or character separated format.

Read/Write

None

XMLAllowMultipleFiles

Boolean. Gets or sets allow multiple files, when exporting to XML. When set to True the Schema file for the report will be exported along with the XML file. The Schema file will be either an XML schema (.xsd) or a Document Type Definition (.dtd), depending on the options selected in the XML Forma dilaog box. For more information see "Customizing XML report definitions" in the Crystal Reports User's Guide

Read/Write

None

XMLFileName

String. Gets or sets the file name if the report is exported to a disk.

Read/Write

None

Remarks

For backwards compatibility the FormatDllName and DestinationDllName properties return the Internal Name property of the associated DLL. The Internal Name property of the DLL is found in the DLLs Properties Dialog box under the Version tab. For a list of export DLLs see "Export Destination" and "Export Format" in the Runtime help (Runtime.hlp).


ExportOptions Object Methods

The following methods are discussed in this section:

  • PromptForExportOptions Method (ExportOptions Object)
  • Reset Method (ExportOptions Object)


PromptForExportOptions Method (ExportOptions Object)

The PromptForExportOptions method prompts the user for export information using default Crystal Report Engine dialog boxes.

Syntax

Sub PromptForExportOptions ()


Reset Method (ExportOptions Object)

The Reset method clears all ExportOptions properties.

Syntax

Sub Reset ()


FieldDefinitions Collection

The FieldDefinitions Collection contains the various types of XXXFieldDefinition Objects (for example, DatabaseFieldDefinition, FormulaFieldDefinition, SummaryFieldDefinition). For the current release, developers can access the FieldDefinitions Collection only through the ConditionFields Property of GraphObject.

FieldDefinitions Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the collection count. | Read only | None
Item (index As Long) | A field definition object. Gets the collection item. See Remarks. | Read only | None
Parent | Report Object. Reference to the parent object. | Read only | None

Remarks

After getting the field definition object from the Item property, you can use the Kind property to determine what type of field definition object the item is. All field definition objects have the Kind property.


FieldDefinitions Collection Methods

The following methods are discussed in this section:

  • Add Method (FieldDefinitions Collection)
  • Delete Method (FieldDefinitions Collection)


Add Method (FieldDefinitions Collection)

Use the Add method to add the specified Field to the FieldDefinitions Collection.

Syntax

Sub Add (Field)

Parameter

Parameter | Description
Field | Specifies the Field that you want to add to the Collection.


Delete Method (FieldDefinitions Collection)

Use the Delete method to remove the specified Field from the FieldDefinitions Collection.

Syntax

Sub Delete (Field)

Parameter

Parameter | Description
Field | Specifies the Field that you want to delete from the Collection.


FieldElement Object

The FieldElement Object represents a field object embedded in a text field. This object provides properties for retrieving field element information from a text object (for example, line spacing, the number of decimal places, font color). A FieldElement Object is obtained from the Item property of the FieldElements Collection.

FieldElement Object Properties

Property | Description | Read/Write | Restriction in event handler
AmPmType | CRAMPMType. Gets or sets the AM/PM type option. | Read/Write | Can be written only when formatting idle or active.
AmString | String. Gets or sets the AM string. | Read/Write | Can be written only when formatting idle or active.
BooleanOutputType | CRBooleanOutputType. Gets or sets the Boolean output type. | Read/Write | Can be written only when formatting idle or active.
CharacterSpacing | Long. Gets or sets the character spacing. OLE_COLOR. Gets or sets the object background color. | Read/Write | Can be written only when formatting idle.
Color | OLE_COLOR. Gets or sets the font color. | Read/Write | Can be written only when formatting idle or active.
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
CurrencyPositionType | CRCurrencyPositionType. Gets or sets the currency position type. | Read/Write | Can be written only when formatting idle or active.
CurrencySymbol | String. Gets or sets the currency symbol. | Read/Write | Can be written only when formatting idle or active.
CurrencySymbolType | CRCurrencySymbolType. Gets or sets the currency symbol type. | Read/Write | Can be written only when formatting idle or active.
DateCalendarType | CRDateCalendarType. Gets or sets the date calendar type. | Read/Write | Can be written only when formatting idle.
DateEraType | CRDateEraType. Gets or sets the date era type. | Read/Write | Can be written only when formatting idle.
DateFirstSeparator | String. Gets or sets the date first separator. | Read/Write | Can be written only when formatting idle or active.
DateOrder | CRDateOrder. Gets or sets the date order. | Read/Write | Can be written only when formatting idle or active.
DatePrefixSeparator | String. Gets or sets the date prefix separator. | Read/Write | Can be written only when formatting idle or active.
DateSecondSeparator | String. Gets or sets the date second separator. | Read/Write | Can be written only when formatting idle or active.
DateSuffixSeparator | String. Gets or sets the date suffix separator | Read/Write | Can be written only when formatting idle or active.
DateWindowsDefaultType | CRDateTimeFieldFormatConditionFormulaType. Gets or sets the date windows default type. | Read/Write | Can be written only when formatting idle.
DayType | CRDayType. Gets or sets the day type. | Read/Write | Can be written only when formatting idle or active.
DecimalPlaces | Integer. Gets or sets the number decimal places. | Read/Write | Can be written only when formatting idle or active.
DecimalSymbol | String. Gets or sets the decimal symbol. | Read/Write | Can be written only when formatting idle or active.
DisplayReverseSign | Boolean. Gets or sets the reverse sign option. | Read/Write | Can be written only when formatting idle or active.
FieldDefinition | A field definition object. Gets the field definition. See Remarks. | Read Only | None
FirstLineIndent | Long. Gets or sets the first line indent. | Read/Write | Can be written only when formatting idle.
Font | IFontDisp. Gets or sets the standard OLE font. | Read/Write | Can be written only when formatting idle or active.
HourMinuteSeparator | String. Gets or sets the hour minute separator. | Read/Write | Can be written only when formatting idle or active.
HourType | CRHourType. Gets or sets the hour type. | Read/Write | Can be written only when formatting idle or active.
LeadingDayPosition | CRLeadingDayPosition. Gets or sets the leading day position option. | Read/Write | Can be written only when formatting idle.
LeadingDaySeparator | String. Gets or sets the leading day separator. | Read/Write | Can be written only when formatting idle or active.
LeadingDayType | CRLeadingDayType. Gets or sets the leading day type. | Read/Write | Can be written only when formatting idle or active.
LeftIndent | Long. Gets or sets the left indent, in twips. | Read/Write | Can be written only when formatting idle.
LineSpacing | Double. Gets the line spacing. | Read Only | None
LineSpacingType | CRLineSpacingType. Gets the line spacing type. | Read Only | None
MaxNumberOfLines | Integer. Gets or sets the maximum number of line for a string memo field. | Read/Write | Can be written only when formatting idle or active.
MinuteSecondSeparator | String. Gets or sets minute second separator. | Read/Write | Can be written only when formatting idle or active.
MinuteType | CRMinuteType. Gets or sets the minute type. | Read/Write | Can be written only when formatting idle or active.
MonthType | CRMonthType. Gets or sets month type. | Read/Write | Can be written only when formatting idle or active.
NegativeType | CRNegativeType. Gets or sets number negative type. | Read/Write | Can be written only when formatting idle or active.
Parent | TextObject Object. Reference to the parent object. | Read only | Can be written only when formatting idle or active.
PmString | String. Gets or sets the PM string. | Read/Write | Can be written only when formatting idle or active.
RightIndent | Long. Gets or sets the right indent, in twips. | Read/Write | Can be written only when formatting idle.
RoundingType | CRRoundingType. Gets or sets the number rounding type. | Read/Write | Can be written only when formatting idle or active.
SecondType | CRSecondType. Gets or sets the seconds type. | Read/Write | Can be written only when formatting idle or active.
Suppress | Boolean. Gets or sets the object visibility. | Read/Write | Can be written only when formatting idle or active.
SuppressIfDuplicated | Boolean. Gets or sets the suppress if duplicate option. | Read/Write | Can be written only when formatting idle or active.
SuppressIfZero | Boolean. Gets or sets the suppress if zero option. | Read/Write | Can be written only when formatting idle or active.
TextFormat | CRTextFormat. Gets or sets the text format option for string memo fields. | Read/Write | Can be written only when formatting idle.
ThousandsSeparators | Boolean. Gets or sets the enable thousands separators option. | Read/Write | Can be written only when formatting idle or active.
ThousandSymbol | String. Gets or sets the thousand separator symbol. | Read/Write | Can be written only when formatting idle or active.
TimeBase | CRTimeBase. Gets or sets the time base. | Read/Write | Can be written only when formatting idle or active.
UseLeadingZero | Boolean. Gets or sets the number uses leading zero option. | Read/Write | Can be written only when formatting idle or active.
UseOneSymbolPerPage | Boolean. Gets or sets the use one symbol per page option. | Read/Write | Can be written only when formatting idle or active.
UseSystemDefaults | Boolean. Gets or sets the use system defaults formatting option. | Read/Write | Can be written only when formatting idle or active.
YearType | CRYearType. Gets or sets the year type. | Read/Write | Can be written only when formatting idle or active.
ZeroValueString | String. Gets or sets the zero value string for number field format. | Read/Write | Can be written only when formatting idle or active.

Remarks

After getting the field definition object from the FieldDefiniton property, you can use the Kind property to determine what type of field definition object it is. All field definition objects have the Kind property.


FieldElement Object Methods

The following method is discussed in this section:

  • SetLineSpacing Method (FieldElement Object)


SetLineSpacing Method (FieldElement Object)

Use the SetLineSpacing method to get and set the line spacing and line spacing type.

Syntax

Sub SetLineSpacing (LineSpacing As Double,

LineSpacingType As CRLineSpacingType)

Parameters

Parameter | Description
LineSpacing | Specifies the line spacing.
LineSpacingType | Specifies the line spacing type. Use one of CRLineSpacingType.


FieldElements Collection

The FieldElements collection contains the FieldElement objects defined in a text field. Access a specific object in the collection using the Item property.

FieldElements Collection Properties

Property | Definition | Read/Write | Restriction in event handler
Count | Long. Gets the number of objects in the collection. | Read only | None
Item (indexAs Long) | FieldElement Object. Gets an item from the Collection specified by the parameter index. | Read only | None
Parent | TextObject Object. Gets reference to the parent object. | Read only | None


FieldElements Collection Methods

The following methods are discussed in this section:

  • Add Method (FieldElements Collection)
  • Delete Method (FieldElements Collection)


Add Method (FieldElements Collection)

The Add method is used to add a FieldElement object to the Collection.

Syntax

Function Add (position As Long, Field)

Parameter | Description
position | Specifies the index where you would like to add the FieldElement to the Collection.
Field | Specifies the FieldElement that you want to add to the Collection.


Delete Method (FieldElements Collection)

Use the Delete method to remove a FieldElement Object from the Collection.

Syntax

Sub Delete (index)

Parameter

Parameter | Description
index | Specifies the index number of the Object that you want to remove from the Collection.


FieldMappingData Object

The FieldMappingData Object provides information related to FieldMapping Events. This Object can be accessed through the Report Object FieldMapping Event.

FieldMappingData Object Properties

Property | Description | Read/Write | Restriction in event handler
FieldName | String. Gets or sets the field name. | Read/Write | None
MappingToFieldIndex | Integer. Gets or sets the index of the mapping to field index in the field list of the new database. | Read/Write | None
TableName | String. Gets or sets field's table name. | Read/Write | None
ValueType | CRFieldValueType. Gets the value type that is in the field. | Read only | None


FieldObject Object

The FieldObject Object represents a field found in a report (for example, special field, database field, parameter field, etc.). This object provides properties for retrieving information for a field in your report. A FieldObject Object is obtained from the Item property of the ReportObjects Collection, (for example, ReportObjects.Item(Index), where the index can be the 1-based index number of the item or an Object name).

FieldObject Object Properties

Property | Description | Read/Write | Restriction in event handler
AmPmType | CRAMPMType. Gets or sets the AM/PM type option. | Read/Write | Can be written only when formatting idle or active.
AmString | String. Gets or sets the AM string. | Read/Write | Can be written only when formatting idle or active.
BackColor | OLE_COLOR. Gets or sets the object background color. | Read/Write | Can be written only when formatting idle or active.
BooleanOutputType | CRBooleanFieldFormatConditionFormulaType. Gets or sets the Boolean output type. | Read/Write | Can be written only when formatting idle or active.
BorderColor | OLE_COLOR. Gets or sets the object border color. | Read/Write | Can be written only when formatting idle or active.
BottomLineStyle | CRLineStyle. Gets or sets bottom line style. | Read/Write | Can be written only when formatting idle or active.
CanGrow | Boolean. Gets or sets can the grow option. | Read/Write | Can be written only when formatting idle or active.
CharacterSpacing | Long. Gets or sets the character spacing. | Read/Write | Can be written only when formatting idle.
CloseAtPageBreak | Boolean. Gets or sets the close border on page break option. | Read/Write | Can be written only when formatting idle or active.
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
CssClass | String. Gets or sets the cascading style sheet Class. | Read/Write | Can be written only when formatting idle.
CurrencyPositionType | CRCurrencyPositionType. Gets or sets the currency position type. | Read/Write | Can be written only when formatting idle or active.
CurrencySymbol | String. Gets or sets the currency symbol. | Read/Write | Can be written only when formatting idle or active.
CurrencySymbolType | CRCurrencySymbolType. Gets or sets the currency symbol type. | Read/Write | Can be written only when formatting idle or active.
DateCalendarType | CRDateCalendarType. Gets or sets the date calendar type. | Read/Write | Can be written only when formatting idle.
DateEraType | CRDateEraType. Gets or sets the date era type. | Read/Write | Can be written only when formatting idle.
DateFirstSeparator | String. Gets or sets the date first separator. | Read/Write | Can be written only when formatting idle or active.
DateOrder | CRDateOrder. Gets or sets the date order. | Read/Write | Can be written only when formatting idle or active.
DatePrefixSeparator | String. Gets or sets the date prefix separator. | Read/Write | Can be written only when formatting idle or active.
DateSecondSeparator | String. Gets or sets the date second separator. | Read/Write | Can be written only when formatting idle or active.
DateSuffixSeparator | String. Gets or sets the date suffix separator | Read/Write | Can be written only when formatting idle or active.
DateWindowsDefaultType | CRDateTimeFieldFormatConditionFormulaType. Gets or sets the date windows default type. | Read/Write | Can be written only when formatting idle.
DayType | CRDayType. Gets or sets the day type. | Read/Write | Can be written only when formatting idle or active.
DecimalPlaces | Integer. Gets or sets the number decimal places. | Read/Write | Can be written only when formatting idle or active.
DecimalSymbol | String. Gets or sets the decimal symbol. | Read/Write | Can be written only when formatting idle or active.
DisplayReverseSign | Boolean. Gets or sets the reverse sign option. | Read/Write | Can be written only when formatting idle or active.
EnableTightHorizontal | Boolean. Gets or sets the tight horizontal option. | Read/Write | Can be written only when formatting idle or active.
Field | Object. Gets the field definition object (for example, ParameterFieldDefinition Object). | Read only | None
FirstLineIndent | Long. Gets or sets the first line indent. | Read/Write | Can be written only when formatting idle.
Font | IFontDisp. Gets or sets the standard OLE font. | Read/Write | Can be written only when formatting idle or active.
HasDropShadow | Boolean. Gets or sets the border drop shadow option. | Read/Write | Can be written only when formatting idle or active.
Height | Long. Gets or sets object height, in twips. | Read/Write | Can be written only when formatting idle or active.
HorAlignment | CRAlignment. Gets or sets the horizontal alignment. | Read/Write | Can be written only when formatting idle or active.
HourMinuteSeparator | String. Gets or sets the hour minute separator. | Read/Write | Can be written only when formatting idle or active.
HourType | CRHourType. Gets or sets the hour type. | Read/Write | Can be written only when formatting idle or active.
KeepTogether | Boolean. Gets or sets the keep object together option. | Read/Write | Can be written only when formatting idle or active.
Kind | CRObjectKind. Gets which kind of object (for example, box, cross-tab, field.) | Read only | None
LeadingDayPosition | CRLeadingDayPosition. Gets or sets the leading day position option. | Read/Write | Can be written only when formatting idle.
LeadingDaySeparator | String. Gets or sets the leading day separator. | Read/Write | Can be written only when formatting idle or active.
LeadingDayType | CRLeadingDayType. Gets or sets the leading day type. | Read/Write | Can be written only when formatting idle or active.
Left | Long. Gets or sets the object upper left position, in twips. | Read/Write | Can be written only when formatting idle or active.
LeftIndent | Long. Gets or sets the left indent, in twips. | Read/Write | Can be written only when formatting idle.
LeftLineStyle | CRLineStyle. Gets or sets the left line style. | Read/Write | Can be written only when formatting idle or active.
LineSpacing | Double. Gets the line spacing. | Read Only | None
LineSpacingType | CRLineSpacingType. Gets the line spacing type. | Read Only | None
MaxNumberOfLines | Integer. Gets or sets the maximum number of line for a string memo field. | Read/Write | Can be written only when formatting idle or active.
MinuteSecondSeparator | String. Gets or sets minute second separator. | Read/Write | Can be written only when formatting idle or active.
MinuteType | CRMinuteType. Gets or sets the minute type. | Read/Write | Can be written only when formatting idle or active.
MonthType | CRMonthType. Gets or sets month type. | Read/Write | Can be written only when formatting idle or active.
Name | String. Gets or sets the object name. | Read/Write | Can be written only when formatting idle or active.
NegativeType | CRNegativeType. Gets or sets number negative type. | Read/Write | Can be written only when formatting idle or active.
NextValue | Variant. Gets the field next value. | Read only | Can be written only when formatting idle or active.
Parent | Section Object. Reference to the parent object. | Read only | Can be written only when formatting idle or active.
PmString | String. Gets or sets the PM string. | Read/Write | Can be written only when formatting idle or active.
PreviousValue | Variant. Gets the field previous value. | Read only | Can be written only when formatting idle or active.
RightIndent | Long. Gets or sets the right indent, in twips. | Read/Write | Can be written only when formatting idle.
RightLineStyle | CRLineStyle. Gets or sets the right line style. | Read/Write | Can be written only when formatting idle or active.
RoundingType | CRRoundingType. Gets or sets the number rounding type. | Read/Write | Can be written only when formatting idle or active.
SecondType | CRSecondType. Gets or sets the seconds type. | Read/Write | Can be written only when formatting idle or active.
Suppress | Boolean. Gets or sets the object visibility. | Read/Write | Can be written only when formatting idle or active.
SuppressIfDuplicated | Boolean. Gets or sets the suppress if duplicate option. | Read/Write | Can be written only when formatting idle or active.
SuppressIfZero | Boolean. Gets or sets the suppress if zero option. | Read/Write | Can be written only when formatting idle or active.
TextColor | OLE_COLOR. Gets or sets the object text color. | Read/Write | Can be written only when formatting idle or active.
TextFormat | CRTextFormat. Gets or sets the text format option for string memo fields. | Read/Write | Can be written only when formatting idle.
TextRotationAngle | CRRotationAngle. Gets or sets the text rotation angle. | Read/Write | Can be written only when formatting idle.
ThousandsSeparators | Boolean. Gets or sets the enable thousands separators option. | Read/Write | Can be written only when formatting idle or active.
ThousandSymbol | String. Gets or sets the thousand separator symbol. | Read/Write | Can be written only when formatting idle or active.
TimeBase | CRTimeBase. Gets or sets the time base. | Read/Write | Can be written only when formatting idle or active.
Top | Long. Gets or sets the object upper top position, in twips. | Read/Write | Can be written only when formatting idle or active.
TopLineStyle | CRLineStyle. Gets or sets the top line style. | Read/Write | Can be written only when formatting idle or active.
UseLeadingZero | Boolean. Gets or sets the number uses leading zero option. | Read/Write | Can be written only when formatting idle or active.
UseOneSymbolPerPage | Boolean. Gets or sets the use one symbol per page option. | Read/Write | Can be written only when formatting idle or active.
UseSystemDefaults | Boolean. Gets or sets the use system defaults formatting option. | Read/Write | Can be written only when formatting idle or active.
Value | Variant. Gets the field current value. | Read Only | Can be written only when formatting idle or active.
Width | Long. Gets or sets the object width, in twips. | Read/Write | Can be written only when formatting idle or active.
YearType | CRYearType. Gets or sets the year type. | Read/Write | Can be written only when formatting idle or active.
ZeroValueString | String. Gets or sets the zero value string for number field format. | Read/Write | Can be written only when formatting idle or active.


FieldObject Object Methods

The following methods are discussed in this section:

  • SetLineSpacing Method (FieldObject Object)
  • SetUnboundFieldSource Method (FieldObject Object)


SetLineSpacing Method (FieldObject Object)

Use the SetLineSpacing method to get and set the line spacing and line spacing type.

Syntax

Sub SetLineSpacing (LineSpacing As Double,

LineSpacingType As CRLineSpacingType)

Parameters

Parameter | Description
LineSpacing | Specifies the line spacing.
LineSpacingType | Specifies the line spacing type. Use one of CRLineSpacingType.


SetUnboundFieldSource Method (FieldObject Object)

Use the SetUnbound FieldSource Method to bind a DataSource to an unbound field.

Syntax

Sub SetUnboundFieldSource (pUnboundFieldSource As String)

Parameter

Parameter | Description
pUnboundFieldSource | BSTR specifies the datasouce, Crystal formula format. See Remarks below.

Remarks

For example:

object.SetUnboundFieldSource("{Customer.CustomerID}")


FormattingInfo Object

The FormattingInfo object contains information about the section currently being formatted.

FormattingInfo Object Properties

Property | Description | Read/Write | Restriction in event handler
IsEndOfGroup | Boolean. Gets whether the current formatting section is the end of a group. | Read only | None
IsRepeatedGroupHeader | Boolean. Gets whether the current formatting section is a repeated group header. | Read only | None
IsStartOfGroup | Boolean. Gets whether the current formatting section is the start of a group. | Read only | None


FormulaFieldDefinition Object

The FormulaFieldDefinition Object provides properties and methods for retrieving information and setting options for any named formula field in a report.

FormulaFieldDefinition Object Properties

Property | Description | Read/Write | Restriction in event handler
FormulaFieldName | String. Gets the formula field name as it appears in the RDC Dataview Panel. | Read only | None
Kind | CRFieldKind. Gets what kind of field (for example, database, summary, formula, etc.). | Read only | None
Name | String. Gets the unique name of the formula field in Crystal formula format as it would be referenced in the report (for example, {@ExampleFormula}). | Read only | None
NextValue | Variant. Gets the field next value. | Read only | Can be read only when top-level Report object is formatting active.
NumberOfBytes | Integer. Gets the number of bytes required to store the field data in memory. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None
PreviousValue | Variant. Gets the field previous value. | Read only | Can be read only when top-level Report object is formatting active.
Text | String. Gets or sets the text of the formula. The formula text is changed immediately in the report. If you generate a report with an invalid formula, you may receive an exception error. Syntax can be Crystal Refort or Visual Basic. See Remarks below. | Read/Write | Can be written only when formatting idle.
Value | Variant. Gets the field current value. | Read only | Can be read only when top-level Report object is formatting active.
ValueType | CRFieldValueType. Gets which type of value is found in the field. | Read only | None

Remarks

Crystal Reports 9 and higher supports formulas in Crystal Reports syntax and Visual Basic syntax. When setting text to a formula, the syntax is determined by the FormulaSyntax property of the parent Report Object. The default syntax is Crystal Report syntax (crCrystalSyntaxFormula).


FormulaFieldDefinition Object Methods

The following method is discussed in this section:

  • Check Method (FormulaFieldDefinition Object)

Check Method (FormulaFieldDefinition Object)

The Check method checks formulas for errors (syntax errors).

Syntax

Sub Check (pBool As Boolean, ppErrorString As String)

Parameters

Parameter | Description
pBool | Boolean value indicating the condition of the formula string. Will be set to TRUE if the formula is valid and FALSE if the formula contains one or more errors.
ppErrorString | Specifies the error message string if the formula contains an error.


FormulaFieldDefinitions Collection

The FormulaFieldDefinitions Collection is a collection of named formulas in the report. Access a specific FormulaFieldDefinition Object, in the collection using the Item property.


FormulaFieldDefinitions Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of formula field definitions in the collection. | Read only | None
Item (index As Long) | FormulaFieldDefinitions Collection. Gets collection item. See Remarks below. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None

Remarks

Instead of using the Item property as shown, you can reference a formula field directly (for example, FormulaFieldDefinitions(1)).


FormulaFieldDefinitions Collection Methods

The following methods are discussed in this section:

  • Add Method (FormulaFieldDefinitions Collection)
  • Delete Method (FormulaFieldDefinitions Collection)
  • GetItemByName Method (FormulaFieldDefinitions Collection)


Add Method (FormulaFieldDefinitions Collection)

Use the Add method to add the specified formula field to the FormulaFieldDefinitions Collection.

Syntax

Function Add (formulaName As String,

Text As String) As FormulaFieldDefinition

Parameters

Parameter | Description
formulaName | Specifies the formula field that you want to add to the Collection.
Text | Specifies the text of the formula field that you want to add.

Returns

Returns a FormulaFieldDefinition member of the Collection.


Delete Method (FormulaFieldDefinitions Collection)

Use the Delete method to remove the specified formula field from the FormulaFieldDefinitions Collection.

Syntax

Sub Delete (index)

Parameter

Parameter | Description
index | Specifies the formula field that you want to delete from the Collection.


GetItemByName Method (FormulaFieldDefinitions Collection)

Use the GetItemByName method to retrieve a FormulaFieldDefinition object by name.

Syntax

Sub GetItemByName(name As String, formulaFieldDefinition)

Parameters

Parameter | Description
name | The item's unique name.
formulaFieldDefinition | A FormulaFieldDefinition object to hold the retrieved item.


GraphObject Object

The GraphObject object represents a graph/chart found in a report. This object provides properties for retrieving information and setting options for a graph in your report (that is, graph data type — group, detail or graph display type — bar, pie, and so on.).

GraphObject Object Properties

Examples

Property | Description | Read/Write | Restriction in event handler
AutoRangeData2Axis | Boolean. Gets or sets the auto range option for data2 axis. See Remarks below. | Read/Write | Can be written only when formatting idle.
AutoRangeDataAxis | Boolean. Gets or sets the auto range option for data axis. See Remarks below. | Read/Write | Can be written only when formatting idle.
AutoRangeSeriesAxis | Boolean. Gets or sets the auto range option for series axis. | Read/Write | Can be written only when formatting idle.
BackColor | OLE_COLOR. Gets or sets the object background color. | Read/Write | Can be written only when formatting idle or active.
BarSize | CRBarSize. Gets or sets the bar size. | Read/Write | Can be written only when formatting idle.
BorderColor | OLE_COLOR. Gets or sets the object border color. | Read/Write | Can be written only when formatting idle or active.
BottomLineStyle | CRLineStyle. Gets or sets the bottom line style. | Read/Write | Can be written only when formatting idle or active.
CloseAtPageBreak | Boolean. Gets or sets the close border on page break option. | Read/Write | Can be written only when formatting idle or active.
ConditionFields | FieldDefinitions Collection. Gets the condition fields Collection. | Read only | None
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
CrossTabObject | CrossTabObject Object. Gets the crosstab object if this is a CrossTab chart. | Read only | None
CssClass | String. Gets or sets the cascading style sheet Class. | Read/Write | Can be written only when formatting idle.
Data2AxisDivisionMethod | CRDivisionMethod. Gets or sets the data2 axis division method. | Read/Write | Can be written only when formatting idle.
Data2AxisDivisionNumber | Long. Gets or sets the data2 axis division number. | Read/Write | Can be written only when formatting idle.
Data2AxisGridline | CRGridlineType. Gets or sets the data2 axis grid line type. | Read/Write | Can be written only when formatting idle.
Data2AxisNumberFormat | CRNumberFormat. Gets or sets the data2 axis number format. | Read/Write | Can be written only when formatting idle.
DataAxisDivisionMethod | CRDivisionMethod. Gets or sets the data axis division method. | Read/Write | Can be written only when formatting idle.
DataAxisDivisionNumber | Long. Gets or sets the data axis division number. | Read/Write | Can be written only when formatting idle.
DataAxisGridline | CRGridlineType. Gets or sets the data axis grid line type. | Read/Write | Can be written only when formatting idle.
DataAxisNumberFormat | CRNumberFormat. Gets or sets the data axis number format. | Read/Write | Can be written only when formatting idle.
DataLabelFont | IFontDisp. Gets or sets standard OLE font for chart data labels. | Read/Write | Can be written only when formatting idle.
DataPoint | CRGraphDataPoint. Gets or sets the graph data points on risers. | Read/Write | Can be written only when formatting idle.
DataTitle | String. Gets or sets the data title. | Read/Write | Can be written only when formatting idle.
DataTitleFont | IFontDisp. Gets or sets standard OLE font for chart data title. | Read/Write | Can be written only when formatting idle.
DataType | CRGraphDataType. Returns which type of data used in the graph. | Read only | None
DataValueNumberFormat | CRNumberFormat. Gets or sets the data value number format. | Read/Write | Can be written only when formatting idle.
EnableAutoScaleDataAxis | Boolean. Gets or sets the data axis auto-scale option. | Read/Write | Can be written only when formatting idle.
EnableAutoScaleData2Axis | Boolean. Gets or sets the data2 axis auto-scale option. | Read/Write | Can be written only when formatting idle.
EnableAutoScaleSeriesAxis | Boolean. Gets or sets the series axis auto-scale option. | Read/Write | Can be written only when formatting idle.
EnableForEachRecord | Boolean. Gets or sets the enable for each record option. | Read/Write | Can be written only when formatting idle.
EnableShowLegend | Boolean. Gets or sets the show legend option. | Read/Write | Can be written only when formatting idle.
EnableSummarizeValues | Boolean. Gets or sets the enable summarize values option. | Read/Write | Can be written only when formatting idle.
FootNote | String. Gets or sets the footnote. | Read/Write | Can be written only when formatting idle.
FootnoteFont | IFontDisp. Gets or sets standard OLE font for chart footnote. | Read/Write | Can be written only when formatting idle.
GraphColor | crgraphcolor. Gets or sets the graph color. | Read/Write | Can be written only when formatting idle.
GraphDirection | CRGraphDirection. Gets or sets the graph direction. | Read/Write | Can be written only when formatting idle.
GraphType | CRGraphType. Gets or sets the graph type. | Read/Write | Can be written only when formatting idle.
GroupAxisGridline | CRGridlineType. Gets or sets the group axis grid line type. | Read/Write | Can be written only when formatting idle.
GroupLabelFont | IFontDisp. Gets or sets standard OLE font for chart group labels. | Read/Write | Can be written only when formatting idle.
GroupsTitle | String. Gets or sets the groups title. | Read/Write | Can be written only when formatting idle.
GroupTitleFont | IFontDisp. Gets or sets standard OLE font for chart group title. | Read/Write | Can be written only when formatting idle.
HasDropShadow | Boolean. Gets or sets the border drop shadow option. | Read/Write | Can be written only when formatting idle or active.
Height | Long. Gets or sets the object height, in twips. | Read/Write | Can be written only when formatting idle or active.
IsFootnoteByDefault | Boolean. Gets or sets footnote default flag. | Read/Write | Can be written only when formatting idle or active.
IsGroupsTitleByDefault | Boolean. Gets or set groups title default flag. | Read/Write | Can be written only when formatting idle or active.
IsSeriesTitleByDefault | Boolean. Gets or sets series title default flag. | Read/Write | Can be written only when formatting idle or active.
IsSubTitleByDefault | Boolean. Get or sets subtitle default flag. | Read/Write | Can be written only when formatting idle or active.
IsTitleByDefault | Boolean. Gets or sets title default flag. | Read/Write | Can be written only when formatting idle or active.
IsXAxisTitleByDefault | Boolean. Gets or sets X axis title default flag. | Read/Write | Can be written only when formatting idle or active.
IsYAxisTitleByDefault | Boolean. Gets or sets Y axis title default flag. | Read/Write | Can be written only when formatting idle or active.
IsZAxisTitleByDefault | Boolean. Gets or sets Z axis title default flag. | Read/Write | Can be written only when formatting idle or active.
KeepTogether | Boolean. Gets or sets keep object together option. | Read/Write | Can be written only when formatting idle or active.
Kind | CRObjectKind. Gets which kind of object (for example, box, cross-tab). | Read only | None
Left | Long. Gets or sets the object upper left position, in twips. | Read/Write | Can be written only when formatting idle or active.
LeftLineStyle | CRLineStyle. Gets or sets the left line style. | Read/Write | Can be written only when formatting idle or active.
LegendFont | IFontDisp. Gets or sets standard OLE font for legend. | Read/Write | Can be written only when formatting idle.
LegendLayout | CRPieLegendLayout. Gets or sets the legend layout for a pie chart. | Read/Write | Can be written only when formatting idle.
LegendPosition | CRLegendPosition. Gets or sets the legend position. | Read/Write | Can be written only when formatting idle.
MarkerShape | CRMarkerShape. Gets or sets the marker shape. | Read/Write | Can be written only when formatting idle.
MarkerSize | CRMarkerSize. Gets or sets the marker size. | Read/Write | Can be written only when formatting idle.
MaxData2AxisValue | Double. Gets or sets data2-axis max value. See Remarks below. | Read/Write | Can be written only when formatting idle.
MaxDataAxisValue | Double. Gets or sets data-axis max value. See Remarks below. | Read/Write | Can be written only when formatting idle.
MaxSeriesAxisValue | Double. Gets or sets series axis max value. See Remarks below. | Read/Write | Can be written only when formatting idle.
MinData2AxisValue | Double. Gets or sets data2-axis min value. See Remarks below. | Read/Write | Can be written only when formatting idle.
MinDataAxisValue | Double. Gets or sets data-axis min value. See Remarks below. | Read/Write | Can be written only when formatting idle.
MinSeriesAxisValue | Double. Gets or sets series axis min value. See Remarks below. | Read/Write | Can be written only when formatting idle.
Name | String. Gets or sets the object name. | Read/Write | Can be written only when formatting idle.
Parent | Section Object. Gets reference to the parent object. | Read only | None
PieSize | CRPieSize. Gets or sets the size for pie charts. | Read/Write | Can be written only when formatting idle.
RightLineStyle | CRLineStyle. Gets or sets the right line style. | Read/Write | Can be written only when formatting idle or active.
SeriesAxisDivisionMethod | CRDivisionMethod. Gets or sets the series axis division method. | Read/Write | Can be written only when formatting idle.
SeriesAxisDivisionNumber | Long. Gets or sets the series axis division number. | Read/Write | Can be written only when formatting idle.
SeriesAxisNumberFormat | CRNumberFormat. Gets or sets the series axis number format. | Read/Write | Can be written only when formatting idle.
SeriesAxisGridline | CRGridlineType. Gets or sets the series axis grid line type. | Read/Write | Can be written only when formatting idle.
SeriesLabelFont | IFontDisp. Gets or sets standard OLE font for chart series labels. | Read/Write | Can be written only when formatting idle.
SeriesTitle | String. Gets or sets the series title. | Read/Write | Can be written only when formatting idle.
SeriesTitleFont | IFontDisp. Gets or sets standard OLE font for chart series title. | Read/Write | Can be written only when formatting idle.
SliceDetachment | CRSliceDetachment. Gets or sets the slice detachment. | Read/Write | Can be written only when formatting idle.
SpecifiedGroups | Long. Gets or sets the specified groups. | Read/Write | Can be written only when formatting idle.
SubTitle | String. Gets or sets subtitle. | Read/Write | Can be written only when formatting idle.
SubTitleFont | IFontDisp. Gets or sets standard OLE font for chart subtitle. | Read/Write | Can be written only when formatting idle.
SummaryFields | SummaryFieldDefinitions Collection. Gets the summary fields Collection. | Read only | None
Suppress | Boolean. Gets or sets the object visibility. | Read/Write | Can be written only when formatting idle or active.
Title | String. Gets or sets the title. | Read/Write | Can be written only when formatting idle.
TitleFont | IFontDisp. Gets or sets standard OLE font for chart title. | Read/Write | Can be written only when formatting idle.
Top | Long. Gets or sets the object upper top position, in twips. | Read/Write | Can be written only when formatting idle or active.
TopLineStyle | CRLineStyle. Gets or sets the top line style. | Read/Write | Can be written only when formatting idle or active.
ViewingAngle | CRViewingAngle. Gets or sets the viewing angle. | Read/Write | Can be written only when formatting idle.
Width | Long. Gets or sets the object width, in twips. | Read/Write | Can be written only when formatting idle or active.
XAxisTitle | String. Gets or sets the title for X axis. | Read/Write | Can be written only when formatting idle.
Y2AxisTitle | String. Gets or sets the title Y2 axis. | Read/Write | Can be written only when formatting idle.
YAxisTitle | String. Gets or sets the title for Y axis. | Read/Write | Can be written only when formatting idle.
ZAxisTitle | String. Gets or sets the title for Z axis. | Read/Write | Can be written only when formatting idle.

Remarks

Properties Max/MinData/SeriesAxisValue will be ignored if the corresponding AutoRangeData/SeriesAxis property is set to TRUE. If the Max/MinDataDataAxis/Series properties are set at runtime, then the corresponding AutoRangeData/SeriesAxis must be set to FALSE.

This property must be set to FALSE... | ...or this property will be ignored
AutoRangeData2Axis | MaxData2AxisValue
AutoRangeDataAxis | MaxDataAxisValue
AutoRangeData2Axis | MinData2AxisValue
AutoRangeDataAxis | MinDataAxisValue
AutoRangeSeriesAxis | MaxSeriesAxisValue
AutoRangeSeriesAxis | MinSeriesAxisValue


GroupNameFieldDefinition Object

The GroupNameFieldDefinition object provides properties and methods for retrieving information on a group name field found in a report (for example, number of group, value type). A GroupNameFieldDefinition object can be obtained from the Field property of the FieldMappingData Object when the specified field is a group name field or from a GroupNameFieldDefinitions Collection retrieved from the GroupNameFields property of the Report Object.

GroupNameFieldDefinition Object Properties

Examples

Property | Description | Read/Write | Restriction in event handler
GroupNameConditionFormula | String. Gets or sets the group name condition formula. | Read/Write | Can be written only when formatting idle.
GroupNameFieldName | String. Gets the group name field name. | Read only | None
GroupNumber | Integer. If the area is a group, this gets the group number. Otherwise, exception is thrown. | Read only | None
Kind | CRFieldKind. Gets which kind of field (for example, database, summary, formula). | Read only | None
Name | String. Gets the field definition unique formula name in Crystal Report formula syntax. | Read only | None
NextValue | Variant. Gets the field next value. | Read only | Can be read only when top-level Report object is formatting active.
NumberOfBytes | Integer. Gets the number of bytes required to store the field data in memory. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None
PreviousValue | Variant. Gets the field previous value. | Read only | Can be read only when top-level Report object is formatting active.
Value | Variant. Gets the field current value. | Read only | Can be read only when top-level Report object is formatting active.
ValueType | CRFieldValueType. Gets which type of value is found in the field. | Read only | None


GroupNameFieldDefinitions Collection

The GroupNameFieldDefinitions Collection is a collection of named groups in the report. Access a specific GroupNameFieldDefinition Object in the collection using the Item property.

GroupNameFieldDefinitions Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of group name field definitions in the Collection. | Read only | None
Item (indexAs Long) | GroupNameFieldDefinition Object. Gets the specified object from the Collection. Item has an index parameter that is the 1-based index number of the object in the Collection. The items in the collection are indexed in the order they were added to the report. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None

Remarks

Instead of using the Item property as shown, you can reference a group name field directly (for example, GroupNameFieldDefinitions(1)).


LineObject Object

The LineObject object represents a line drawn on a report. This object provides properties for getting information for lines on a report.

LineObject Object Properties

Property | Description | Read/Write | Restriction in event handler
Bottom | Long. Gets or sets the line lower bottom position, in twips. | Read/Write | Can be written only when formatting idle.
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
CssClass | String. Gets or sets the cascading style sheet Class. | Read/Write | Can be written only when formatting idle.
EndSection | Section Object. Gets the end section. | Read only | None
ExtendToBottomOfSection | Boolean. Gets or sets the extend to bottom of section option. | Read/Write | Can be written only when formatting idle.
Kind | CRObjectKind. Gets which kind of object (for example, box, cross-tab, field). | Read only | None
Left | Long. Gets or sets the object upper left position, in twips. | Read/Write | Can be written only when formatting idle.
LineColor | OLE_COLOR. Gets or sets the line color. | Read/Write | Can be written only when formatting idle.
LineStyle | CRLineStyle. Gets or sets the line style. See Remarks below. | Read/Write | Can be written only when formatting idle.
LineThickness | Long. Gets or sets the line thickness, in twips. | Read/Write | Can be written only when formatting idle.
Name | String. Gets or sets object name. | Read/Write | Can be written only when formatting idle.
Parent | Section Object. Gets reference to the parent object. | Read only | None
Right | Long. Gets or sets the line lower right position, in twips. | Read/Write | Can be written only when formatting idle.
Suppress | Boolean. Gets or sets the object visibility. | Read/Write | Can be written only when formatting idle.
Top | Long. Gets or sets the object upper top position, in twips. | Read/Write | Can be written only when formatting idle.

Remarks

For property LineStyle, crLSDoubleLine and crLSNoLine are not valid.


MapObject Object

The MapObject object represents a geographic map object in a report. This object provides properties for getting information for Map objects in a report.

MapObject Object Properties

Examples

Property | Description | Read/Write | Restriction in event handler
BackColor | OLE_COLOR. Gets or sets the object background color. | Read/Write | Can be written only when formatting idle or active.
BorderColor | OLE_COLOR. Gets or sets the object border color. | Read/Write | Can be written only when formatting idle or active.
BottomLineStyle | CRLineStyle. Gets or sets the bottom line style. | Read/Write | Can be written only when formatting idle or active.
CloseAtPageBreak | Boolean. Gets or sets the close border on page break option. | Read/Write | Can be written only when formatting idle or active.
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
CssClass | String. Gets or sets the cascading style sheet Class. | Read/Write | Can be written only when formatting idle.
HasDropShadow | Boolean. Gets or sets the border drop shadow option. | Read/Write | Can be written only when formatting idle or active.
Height | Long. Gets or sets the object height, in twips. | Read/Write | Can be written only when formatting idle or active.
KeepTogether | Boolean. Gets or sets the keep object together option. | Read/Write | Can be written only when formatting idle or active.
Kind | CRObjectKind. Gets which kind of object (for example, box, cross-tab, field). | Read only | None
Left | Long. Gets or sets the object upper left position, in twips. | Read/Write | Can be written only when formatting idle or active.
LeftLineStyle | CRLineStyle. Gets or sets the left line style. | Read/Write | Can be written only when formatting idle or active.
Name | String. Gets or sets the object name. | Read/Write | Can be written only when formatting idle.
Parent | Section Object. Gets reference to the parent object. | Read only | None
RightLineStyle | CRLineStyle. Gets or sets the right line style. | Read/Write | Can be written only when formatting idle or active.
Suppress | Boolean. Gets or sets the object visibility. | Read/Write | Can be written only when formatting idle or active.
Top | Long. Gets or sets the object upper top position, in twips. | Read/Write | Can be written only when formatting idle or active.
TopLineStyle | CRLineStyle. Gets or sets the top line style. | Read/Write | Can be written only when formatting idle or active.
Width | Long. Gets or sets the object width, in twips. | Read/Write | Can be written only when formatting idle or active.


ObjectSummaryFieldDefinitions Collection

ObjectSummaryFieldDefinitions is a Collection of SummaryFieldDefinition Object objects.

ObjectSummaryFieldDefinitions Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of object summary field definitions in the Collection. | Read only | None
Item (indexAs Long) | SummaryFieldDefinition Object. Gets the specified object from the Collection. Item has an index parameter that is the 1-based index number of the object in the Collection. The items in the collection are indexed in the order they were added to the report. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None


ObjectSummaryFieldDefinitions Collection Methods

The following methods are discussed in this section:

  • Add Method (ObjectSummaryFieldDefinitions Collection)
  • Delete Method (ObjectSummaryFieldDefinitions Collection)


Add Method (ObjectSummaryFieldDefinitions Collection)

Use the Add method to add the specified object summary field to the ObjectSummaryFieldDefinitions Collection.

Syntax

Sub Add (summaryField)

Parameter

Parameter | Description
summaryField | Specifies the object summary field that you want to add to the Collection.


Delete Method (ObjectSummaryFieldDefinitions Collection)

Use the Delete method to remove the specified object summary field from the ObjectSummaryFieldDefinitions Collection.

Syntax

Sub Delete (index As Long)

Parameter

Parameter | Description
index | Specifies the object summary field that you want to delete from the Collection.


OlapGridObject Object

The OlapGridObject object represents an Olap object in a report.

OlapGridObject Object Properties

Examples

Property | Description | Read/Write | Restriction in event handler
BackColor | OLE_COLOR. Gets or sets the object background color. | Read/Write | Can be written only when formatting idle or active.
BorderColor | OLE_COLOR. Gets or sets the object border color. | Read/Write | Can be written only when formatting idle or active.
BottomLineStyle | CRLineStyle. Gets or sets the bottom line style. | Read/Write | Can be written only when formatting idle or active.
CloseAtPageBreak | Boolean. Gets or sets the close border on page break option. | Read/Write | Can be written only when formatting idle or active.
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
HasDropShadow | Boolean. Gets or sets the border drop shadow option. | Read/Write | Can be written only when formatting idle or active.
Height | Long. Gets the object height, in twips. | Read only | Can be written only when formatting idle or active.
KeepTogether | Boolean. Gets or sets the keep object together option. | Read/Write | Can be written only when formatting idle or active.
Kind | CRObjectKind. Gets report object kind. | Read only | None
Left | Long. Gets or sets the object upper left position, in twips. | Read/Write | Can be written only when formatting idle or active.
LeftLineStyle | CRLineStyle. Gets or sets the left line style. | Read/Write | Can be written only when formatting idle or active.
Name | String. Gets or sets the object name. | Read/Write | Can be written only when formatting idle or active.
Parent | Section Object. Gets reference to the parent object. | Read only | None
RightLineStyle | CRLineStyle. Gets or sets the right line style. | Read/Write | Can be written only when formatting idle or active.
Suppress | Boolean. Gets or sets the object visibility. | Read/Write | Can be written only when formatting idle or active.
Top | Long. Gets or sets the object upper top position, in twips. | Read/Write | Can be written only when formatting idle or active.
TopLineStyle | CRLineStyle. Gets or sets the top line style. | Read/Write | Can be written only when formatting idle or active.
Width | Long. Gets the object width, in twips. | Read only | Can be written only when formatting idle or active.


OleObject Object

The OleObject object represents an OLE object in a report. This object provides properties for getting information for OLE objects in a report.

OleObject Object Properties

Examples

Property | Description | Read/Write | Restriction in event handler
BackColor | OLE_COLOR. Gets or sets the object background color. | Read/Write | Can be written only when formatting idle or active.
BorderColor | OLE_COLOR. Gets or sets the object border color. | Read/Write | Can be written only when formatting idle or active.
BottomCropping | Long. Gets or sets the bottom cropping size, in twips. | Read/Write | Can be written only when formatting idle.
BottomLineStyle | CRLineStyle. Gets or sets the bottom line style. | Read/Write | Can be written only when formatting idle or active.
CloseAtPageBreak | Boolean. Gets or sets the close border on page break option. | Read/Write | Can be written only when formatting idle or active.
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
CssClass | String. Gets or sets the cascading style sheet Class. | Read/Write | Can be written only when formatting idle.
Formatted Picture | IPictureDisp. Gets or sets the specified picture during formatting. | Read/Write | Can be read or written only when top-level Report object is formatting active.
HasDropShadow | Boolean. Gets or sets the border drop shadow option. | Read/Write | Can be written only when formatting idle or active.
Height | Long. Gets or sets the object height, in twips. | Read/Write | Can be written only when formatting idle or active.
KeepTogether | Boolean. Gets or sets the keep object together option. | Read/Write | Can be written only when formatting idle or active.
Kind | CRObjectKind. Gets which kind of object (for example, box, cross-tab, field). | Read only | None
Left | Long. Gets or sets the object upper left position, in twips. | Read/Write | Can be written only when formatting idle or active.
LeftCropping | Long. Gets or sets the left cropping size, in twips. | Read/Write | Can be written only when formatting idle.
LeftLineStyle | CRLineStyle. Gets or sets the left line style. | Read/Write | Can be written only when formatting idle or active.
Name | String. Gets or sets the object name. | Read/Write | Can be written only when formatting idle.
Parent | Section Object. Gets reference to the parent object. | Read only | None
RightCropping | Long. Gets or sets the right cropping size, in twips. | Read/Write | Can be written only when formatting idle.
RightLineStyle | CRLineStyle. Gets or sets the right line style. | Read/Write | Can be written only when formatting idle or active.
Suppress | Boolean. Gets or sets the object visibility. | Read/Write | Can be written only when formatting idle or active.
Top | Long. Gets or sets the object upper top position, in twips. | Read/Write | Can be written only when formatting idle or active.
TopCropping | Long. Gets or sets the top cropping size, in twips. | Read/Write | Can be written only when formatting idle.
TopLineStyle | CRLineStyle. Gets or sets the top line style. | Read/Write | Can be written only when formatting idle or active.
Width | Long. Gets or sets the object width, in twips. | Read/Write | Can be written only when formatting idle or active.
XScaling | Double. Gets or sets the width scaling factor. For example, 1 means 100%, 2 means 200%, 0.5 means 50%. The scaling factor may range from 0.01 to 100. | Read/Write | Can be written only when formatting idle.
YScaling | Double. Gets or sets height scaling factor. For example, 1 means 100%, 2 means 200%, 0.5 means 50% etc. The scaling factor may range from 0.01 to 100. | Read/Write | Can be written only when formatting idle.


OleObject Object Methods

The following method is discussed in this section:

  • SetOleLocation Method (OleObject Object)
  • GetLinkSource Method (OleObject Object)


SetOleLocation Method (OleObject Object)

Use the SetOleLocation method to specify the location of an OLE object.

Syntax

Sub SetOleLocation (pLocation As String)

Parameter

Parameter | Description
pLocation | Specifies the location of the OLE object.

Remarks

SetOleLocation must be called from the Format Event of the Section object, and only when formatting active. For more more information see Format Event (Section Object).


GetLinkSource Method (OleObject Object)

Use the GetLinkSource method to retrieve the linked OLE object path and file name.

Syntax

Function GetLinkSource() As String


Page Object

The Page object is part of the Page Engine. Use the Page Engine when designing web sites using Active Server Pages, the Crystal Report Engine Automation Server, and the Crystal Design-Time ActiveX Control. Unless you are experienced with the Crystal Report Engine Object Library, you should allow the Crystal Design-Time ActiveX Control to generate VBScript code in your Active Server Pages that controls the Page Engine objects.

The Page Engine generates pages of a report on the web server and sends the pages to client web browsers as they are requested. For example, when a user first requests a report, only the first page is sent to the web browser. If the user pages forward or backward in the report, or requests a specific page, only that page is sent. This limits the resources required by the web server and reduces download time for the client browser. A Page object is a single generated page that is sent to the browser.

Page Object Properties

Property | Description | Read/Write | Restriction in event handler
IsLastPage | Boolean. Gets whether the page generated is the last page of the report. | Read only | None
IsMissingTotalPageCount | Boolean. Gets whether the page misses the total page count. | Read only | None
PageNumber | Long. Gets the page number. | Read only | None
Parent | PageGenerator Object. Gets reference to the parent object. | Read only | None


Page Object Methods

The following methods are discussed in this section:

  • RenderEPF Method (Page Object)
  • RenderHTML Method (Page Object)


RenderEPF Method (Page Object)

The RenderEPF method returns a variant that contains EPF data for the report page. This method can be invoked only when in formatting idle mode.

Syntax

Function RenderEPF (resultType As CRRenderResultType)

Parameter

Parameter | Description
ResultType | CRRenderResultType. Specifies whether the page will be rendered using strings or arrays. See Remarks below.

Returns

Returns the EPF stream.

Remarks

Currently only arrays are supported.


RenderHTML Method (Page Object)

The RenderHTML method returns a variant that contains HTML data for the report page. This method can be invoked only when in formatting idle mode.

Syntax

Function RenderHTML (includeDrillDownLinks As Boolean,

pageStyle As CRHTMLPageStyle, toolbarStyle As CRHTMLToolbarStyle,

baseURL As String, resultType As CRRenderResultType)

Parameters

Parameter | Description
includeDrillDownLinks | Indicates whether or not the HTML page will include hyperlinks for drilling-down on summary data.
pageStyle | CRHTMLPageStyle. Specifies the style of the HTML page to be rendered.
toolbarStyle | CRHTMLToolbarStyle. Bitwise constant specifies the style of the toolbar to be used. Constants can be XOR'd.
baseURL | The URL used to access the report when it is first generated.
resultType | CRRenderResultType. Specifies whether the page will be rendered using strings or arrays. See Remarks below.

Returns

Returns the HTML stream.

Remarks

Currently only arrays are supported.


PageEngine Object

Use the PageEngine object when designing web sites using Active Server Pages, the Crystal Report Engine Automation Server, and the Crystal Design-Time ActiveX Control. Unless you are experienced with the Crystal Report Engine Object Library, you should allow the Crystal Design-Time ActiveX Control to generate VBScript code in your Active Server Pages that controls the Page Engine objects.

The Page Engine generates pages of a report on the web server and sends the pages to client web browsers as they are requested. For example, when a user first requests a report, only the first page is sent to the web browser. If the user pages forward or backward in the report, or requests a specific page, only that page is sent. This limits the resources required by the web server and reduces download time for the client browser.

PageEngine Object Properties

Property | Description | Read/Write | Restriction in event handler
ImageOptions | CRImageType. Gets or sets the image type for EPF format. | Read/Write | Can be written only when formatting idle.
Parent | Report Object. Gets reference to the parent object. | Read only | None
PlaceHolderOptions | CRPlaceHolderType. Gets or sets the EPF place holder options. | Read/Write | Can be written only when formatting idle.
ValueFormatOptions | CRValueFormatType. Gets or sets the EPF value format options. | Read/Write | Can be written only when formatting idle.


PageEngine Object Methods

The following methods are discussed in this section:

  • CreatePageGenerator Method (PageEngine Object)
  • RenderTotallerETF Method (PageEngine Object)
  • RenderTotallerHTML Method (PageEngine Object)


CreatePageGenerator Method (PageEngine Object)

The CreatePageGenerator method returns a PageGenerator Object, allowing you to get pages from the view of the report, specified by the GroupPath parameter. This method can be invoked only when in formatting idle mode.

Syntax

Function CreatePageGenerator (GroupPath, [DrillDownLevel]) As PageGenerator

Parameter

Parameter | Description
GroupPath | Specifies an integer array that represents the group path. An empty array would represent the entire report, an array (0, 1) would represent a drill down on the second group member within the first group member where 0 = first group in Group #1 and 1 = second group in Group #2.
[DrillDownLevel] | Reserved. Do not use.

Returns

Returns a PageGenerator Object.


RenderTotallerETF Method (PageEngine Object)

The RenderTotallerETF method returns a variant that contains ETF data for the Group Tree. This method can be invoked only when in formatting idle mode.

Syntax

Function RenderTotallerETF (rootGroupPath, startingChildNumber As Long,

pastRootLevels As Integer, maxNodeCount,

resultType As CRRenderResultType)

Parameters

Parameter | Description
rootGroupPath | Specifies an integer array that represents the group path. An empty array would represent the entire report, an array (0, 1) would represent a drill down on the second group member within the first group member where 0 = first group in Group #1 and 1 = second group in Group #2.
startingChildNumber | The start child number to display.
pastRootLevels | Past root levels.
maxNodeCount | The maximum number of nodes for each group level in the Group Tree.
resultType | CRRenderResultType. Specifies whether the page will be rendered using strings or arrays. See Remarks below.

Returns

Returns the Totaller ETF stream.

Remarks

Currently only arrays are supported.


RenderTotallerHTML Method (PageEngine Object)

The RenderTotallerHTML method returns a variant that contains HTML data for the Group Tree. This method can be invoked only when in formatting idle mode.

Syntax

Function RenderTotallerHTML (rootGroupPath, startingChildNumber As Long,

pastRootLevels As Integer, maxNodeCount, openGroupPath,

includeDrillDownLinks As Boolean, baseURL As String,

resultType As CRRenderResultType)

Parameters

Parameter | Description
rootGroupPath | Specifies the base URL string.
startingChildNumber | The start child number to display.
pastRootLevels | A value indicating the number of past root levels.
maxNodeCount | The maximum number of nodes to display for each group level in the Group Tree.
openGroupPath | An array of groups to be opened in the report.
includeDrillDownLinks | Indicates whether or not drill down hyperlinks are generated for summary values in the report.
baseURL | The URL used to access the report when it is first generated.
resultType | CRRenderResultType. Specifies whether the page will be rendered using strings or arrays. See Remarks below.

Returns

Returns the HTML stream.

Remarks

Currently only arrays are supported.


PageGenerator Object

The PageGenerator object is part of the Page Engine. Use the Page Engine when designing web sites using Active Server Pages, the Crystal Report Engine Automation Server, and the Crystal Design-Time ActiveX Control. Unless you are experienced with the Crystal Report Engine Object Library, you should allow the Crystal Design-Time ActiveX Control to generate VBScript code in your Active Server Pages that controls the Page Engine objects.

The Page Engine generates pages of a report on the web server and sends the pages to client web browsers as they are requested. For example, when a user first requests a report, only the first page is sent to the web browser. If the user pages forward or backward in the report, or requests a specific page, only that page is sent. This limits the resources required by the web server and reduces download time for the client browser. A PageGenerator object generates Page Object as they are requested and allows options for manipulating the report as a whole.

PageGenerator Object Properties

Property | Description | Read/Write | Restriction in event handler
ContainingGroupName | String. Gets containing group name for out of place subreport view. | Read only | None
ContainingGroupPath | Variant. Gets containing group path for out of place subreport view. | Read only | None
ContainingPageNumber | Long. Gets containing page number for out of place subreport view. | Read only | None
DrillDownLevel | Ignore. This property is currently reserved. | Read only | None
GroupName | String. Gets the group name for drill down on graph view. | Read only | None
GroupPath | Variant. Gets the GroupPath parameter set by CreatePageGenerator Method (PageEngine Object). | Read only | None
Pages | Pages Collection. Gets the collection of pages for a specified view. | Read only | None
Parent | PageEngine Object. Gets reference to the parent object. | Read only | None
ReportName | String. Gets the report name for drill down on out of place subreport view. | Read only | None
xOffset | Long. Gets the object x-offset. | Read only | None
yOffset | Long. Gets the object y-offset. | Read only | None


PageGenerator Object Methods

The following methods are discussed in this section:

  • CreateSubreportPageGenerator Method (PageGenerator Object)
  • DrillOnGraph Method (PageGenerator Object)
  • DrillOnMap Method (PageGenerator Object)
  • DrillOnSubreport Method (PageGenerator Object)
  • Export Method (PageGenerator Object)
  • FindText Method (PageGenerator Object)
  • GetPageNumberForGroup Method (PageGenerator Object)
  • RenderTotallerETF Method (PageGenerator Object)
  • RenderTotallerHTML Method (PageGenerator Object)


CreateSubreportPageGenerator Method (PageGenerator Object)

Use the CreateSubreportPageGenerator method to create a page generator that contains the subreport view context.

Syntax

Function CreateSubreportPageGenerator (GroupPath, _

[DrillDownLevel]) As PageGenerator

Parameters

Parameter | Description
GroupPath | Specifies an integer array that represents the group path. An empty array would represent the entire report, an array (0, 1) would represent a drill down on the second group member within the first group member where 0 = first group in Group #1 and 1 = second group in Group #2.
[DrillDownLevel] | Reserved. Do not use.


DrillOnGraph Method (PageGenerator Object)

The DrillOnGraph method creates a new PageGenerator Object that results from drilling down on the specified point in a graph on the given page. This method can be invoked only when in formatting idle mode.

Syntax

Function DrillOnGraph (PageNumber As Long, xOffset As Long, _

yOffset As Long) As PageGenerator

Parameters

Parameter | Description
PageNumber | Specifies the page number.
xOffset | Specifies the X coordinate on page, in twips, where the drill down occurred.
yYOffset | Specifies the Y coordinate on page, in twips, where the drill down occurred.

Returns

Returns a PageGenerator Object.


DrillOnMap Method (PageGenerator Object)

The DrillOnMap method creates a newPageGenerator Object that results from drilling down on the specified point in a map on the given page. This method can be invoked only when in formatting idle mode.

Syntax

Function DrillOnMap (PageNumber As Long, xOffset As Long, _

yOffset As Long) As PageGenerator

Parameters

Parameter | Description
PageNumber | Specifies the page number.
xOffset | Specifies the X coordinate on page, in twips, where the drill down occurred.
yOffset | Specifies the Y coordinate on page, in twips, where the drill down occurred.

Returns

Returns a PageGenerator Object.


DrillOnSubreport Method (PageGenerator Object)

The DrillOnSubreport method creates a new PageGenerator Object that results from drilling down on the specified point in a real-time subreport on the given page. This method can be invoked only when in formatting idle mode.

Syntax

Function DrillOnSubreport (PageNumber As Long, xOffset As Long,_

yOffset As Long) As PageGenerator

Parameters

Parameter | Description
PageNumber | Specifies the page number.
xOffset | Specifies the X coordinate on page, in twips, where the drill down occurred.
yOffset | Specifies the Y coordinate on page, in twips, where the drill down occurred.

Returns

Returns a PageGenerator Object.


Export Method (PageGenerator Object)

Use the Export method to obtain an export stream.

Syntax

Function Export (resultType As CRRenderResultType)

Parameter

Parameter | Description
resultType | CRRenderResultType. Specifies the result type.

Returns

Returns the export data stream.


FindText Method (PageGenerator Object)

Use the FindText method to search for a text string in the specified direction starting on the specified page in the current drill down view.

Syntax

Function FindText (Text As String, direction As CRSearchDirection,_

pPageNumber) As Boolean

Parameters

Parameter | Description
Text | Specifies the text string that you want to search for.
direction | CRSearchDirection. Specifies the direction that you want to search.
pPageNumber | Specifies the page on which you want to start the search.

Returns
  • TRUE if the specified text string is found.
  • FALSE if the specified text string is not found.


GetPageNumberForGroup Method (PageGenerator Object)

The GetPageNumberForGroup method returns the page number on which the specified group starts. This method can be invoked only when in formatting idle mode.

Syntax

Function GetPageNumberForGroup (GroupPath) As Long

Parameters

Parameter | Description
GroupPath | Specifies an integer array that represents the group path. An empty array would represent the entire report, an array (0, 1) would represent a drill down on the second group member within the first group memberwhere 0 = first group in Group #1 and 1 = second group in Group #2.

Returns

Returns the page number on which the specified group starts.


RenderTotallerETF Method (PageGenerator Object)

The RenderTotallerETF method returns a variant that contains ETF data for the Group Tree. This method can be invoked only when in formatting idle mode.

Syntax

Function RenderTotallerETF (rootGroupPath, startingChildNumber As Long, _

pastRootLevels As Integer, maxNodeCount, _

resultType As CRRenderResultType)

Parameters

Parameter | Description
rootGroupPath | Specifies an integer array that represents the root group path. An empty array would represent the entire report, an array (0, 1) would represent a drill down on the second group member within the first group member where 0 = first group in Group #1 and 1 = second group in Group #2.
startingChildNumber | The starting child level to display the report grouping at.
pastRootLevels | Specifies the number of past root levels.
maxNodeCount | The maximum number of nodes for each group level in the Group Tree.
resultType | CRRenderResultType. Specifies whether the page will be rendered using strings or arrays. See Remarks below.

Returns

Returns the Totaller ETF stream.

Remarks

Currently only arrays are supported.


RenderTotallerHTML Method (PageGenerator Object)

The RenderTotallerHTML method returns a variant that contains HTML data for the Group Tree. This method can be invoked only when in formatting idle mode.

Syntax

Function RenderTotallerHTML (rootGroupPath, startingChildNumber As Long, _

pastRootLevels As Integer, maxNodeCount, openGroupPath, _

includeDrillDownLinks As Boolean, baseURL As String, _

resultType As CRRenderResultType)

Parameters

Parameter | Description
rootGroupPath | Specifies an integer array that represents the root group path. An empty array would represent the entire report, an array (0, 1) would represent a drill down on the second group member within the first group member where 0 = first group in Group #1 and 1 = second group in Group #2.
startingChildNumber | The starting child level to display the report grouping at.
pastRootLevels | A value indicating the number of past root levels.
maxNodeCount | The maximum number of nodes to display for each group level in the Group Tree.
openGroupPath | An array of groups to be opened in the report.
includeDrillDownLinks | Indicates whether or not drill down hyperlinks are generated for summary values in the report.
baseURL | The URL used to access the report when it is first generated.
resultType | CRRenderResultType. Specifies whether the page will be rendered using strings or arrays. See Remarks below.

Returns

Returns the HTML stream.

Remarks

Currently only arrays are supported.


Pages Collection

The Pages Collection is part of the Page Engine. Use the Page Engine when designing web sites using Active Server Pages, the Crystal Report Engine Automation Server, and the Crystal Design-Time ActiveX Control. Unless you are experienced with the Crystal Report Engine Object Library, you should allow the Crystal Design-Time ActiveX Control to generate VBScript code in your Active Server Pages that controls the Page Engine objects.

The Page Engine generates pages of a report on the web server and sends the pages to client web browsers as they are requested. For example, when a user first requests a report, only the first page is sent to the web browser. If the user pages forward or backward in the report, or requests a specific page, only that page is sent. This limits the resources required by the web server and reduces download time for the client browser.

The Pages Collection is a collection of Page Object. Access a specific Page object in the collection using the Item property.

Pages Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of page objects in the collection. | Read only | None
Item (index As Long) | Page Object. Gets the collection item based on the 1-based index number. | Read only | None
Parent | PageGenerator Object. Gets reference to the parent object. | Read only | None

Remarks

Item is a default property. You can reference a page directly, for example, Pages(1).


ParameterFieldDefinition Object

The ParameterFieldDefinition object represents a parameter field in the report. This object provides properties and methods for retrieving information and setting options for a parameter field in your report (that is, current value, default value). A ParameterFieldDefinition object is obtain from the Field property of the FieldMappingData Object, when the specified field is a parameter field or from the ParameterFieldDefinitions Collection object under Report.

ParameterFieldDefinition Object Properties

Property | Description | Read/Write | Restriction in event handler
DisallowEditing | Boolean. Gets or sets the disallowing editing option. | Read/Write | Can be written only when formatting idle.
DiscreteOrRangeKind | CRDiscreteOrRangeKind. Gets or sets the parameter value kind (discrete and/or range). | Read/Write | Can be written only when formatting idle.
EditMask | String. Gets or sets edit mask for string parameter. See Remarks below for additional information. | Read/Write | Can be written only when formatting idle.
EnableExclusiveGroup | Boolean. Works in conjunction with property PlaceInGroup. If EnableExclusiveGroup is TRUE, a Bool parameter group can have only one value set to TRUE; if FALSE, then the group can have multiple values set to TRUE. | Read/Write | Can be written only when formatting idle.
EnableMultipleValues | Boolean. Gets or sets the allow multiple values option. | Read/Write | Can be written only when formatting idle.
EnableNullValue | Boolean. Gets or sets the value nullable option for Stored Procedure parameters. | Read/Write | Can be written only when formatting idle.
EnableRangeLimit | Boolean. Gets or sets the option which specifies if this parameter field value should be in the specified range. | Read/Write | Can be written only when formatting idle.
EnableShowDescriptionOnly | Boolean. Gets or sets the show description for pick list option. | Read/Write | Can be written only when formatting idle.
EnableSortBasedOnDesc | Boolean. Gets or sets the sort based on description in pick list option. | Read/Write | Can be written only when formatting idle.
GroupNumber | Integer. Gets or sets boolean group number. | Read/Write | Can be written only when formatting idle.
IsCurrentValueSet | Boolean. Gets whether the current value has been set. | Read only | None
IsDefaultValueSet | Boolean. Gets whether the default value has been set. | Read only | None
Kind | CRFieldKind. Gets which kind of field (database, summary, formula, etc.). | Read only | None
MaximumValue | Variant. Gets or sets the maximum value. See Remarks below for additional comments. | Read/Write | Can be written only when formatting idle.
MinimumValue | Variant. Gets or sets minimum value. See Remarks below for additional comments. | Read/Write | Can be written only when formatting idle.
Name | String. Gets the unique formula name of the parameter field as it appears in the Parameter Field list (RDC DataView). | Read only | None
NeedsCurrentValue | Boolean. Gets whether the field needs a current value. | Read only | None
NextValue | Variant. Gets the next field value. | Read only | Can be read only when top-level Report object is formatting active.
NthValueDescription (index As Integer) | String. Gets or sets nth value description. | Read/Write | Can be written only when formatting idle.
NumberOfBytes | Integer. Gets the number of bytes required to store the field data in memory. | Read only | None
NumberOfCurrentRanges | Integer. Gets total number of current ranges. | Read only | None
NumberOfCurrentValues | Integer. Gets the total number of current values. | Read only | None
NumberOfDefaultValues | Integer. Gets the total number of default values. | Read only | None
ParameterFieldName | String. Gets the name of the parameter field as it is displayed (referenced) in the report (RDC DataView). | Read only | None
ParameterType | CRParameterFieldType. Gets parameter type. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None
PickListSortMethod | CRParameterPickListSortMethod. Gets or sets the sort method in pick list option. | Read/Write | Can be written only when formatting idle.
PlaceInGroup | Boolean. Gets or sets, when prompting for values, whether a Boolean parameter field should appear as part of a Boolean parameter group or individually. Used in conjunction with Boolean property EnableExclusiveGroup. | Read/Write | Can be written only when formatting idle.
PreviousValue | Variant. Gets the field previous value. | Read only | Can be read only when top-level Report object is formattiong active.
Prompt | String. Gets or sets the parameter field prompting string. | Read/Write | None
ReportName | String. Gets the report name the parameter field is in. If it is a main report, the ReportName is empty. | Read only | None
Value | Variant. Gets the current value of the field. | Read only | Can be read only when top-level Report object is formatting active.
ValueType | CRFieldValueType. Gets which type of value is found in the field. | Read only | None

Remarks
  • Regarding property EditMask, please see the additional information available in Crystal Reports Online Help. Search for "Edit Parameter Field dialog box" in the SCR Online Help index.
  • Regarding properties MaximumValue and MinimumValue, the following comments apply.
    • All parameter field types: EnableRangeLimit property must be set to TRUE for MaximumValue and Minimum Value properties to have an effect.
    • String parameter fields: The properties provide the maximum and minimum lengths of the string, not a value range.
    • Boolean parameter fields: The properties do not apply.
  • Regarding properties EditMask, MaximumValue and MinimumValue, changing values associated with one or more of these properties may result in the loss of default values that do not fall within the scope of the new EditMask, MaximumValue or MinimumValue properties.


ParameterFieldDefinition Object Methods

The following methods are discussed in this section:

  • AddCurrentRange Method (ParameterFieldDefinition Object)
  • AddCurrentValue Method (ParameterFieldDefinition Object)
  • AddDefaultValue Method (ParameterFieldDefinition Object)
  • ClearCurrentValueAndRange Method(ParameterFieldDefinition Object)
  • DeleteNthDefaultValue Method (ParameterFieldDefinition Object)
  • GetNthCurrentRange Method (ParameterFieldDefinition Object)
  • GetNthCurrentValue Method (ParameterFieldDefinition Object)
  • GetNthDefaultValue Method (ParameterFieldDefinition Object)
  • SetNthDefaultValue Method (ParameterFieldDefinition Object)


AddCurrentRange Method (ParameterFieldDefinition Object)

The AddCurrentRange method adds the current parameter range to the specified parameter field of a report. When this method is used, property DiscreteOrRangeKind must be crRangeValue.

Syntax

Sub AddCurrentRange (start, end, rangeInfo As CRRangeInfo)

Parameters

Parameter | Description
start | Sets start of the value range.
end | Sets end of the value range.
rangeInfo | CRRangeInfo. Use this bitwise value to indicate whether the upper and/or lower bound of the range should be included.


AddCurrentValue Method (ParameterFieldDefinition Object)

The AddCurrentValue method adds a value to the specified parameter field of a report. When this method is used, property DiscreteOrRangeKind must be crDiscreteValue.

Syntax

Sub AddCurrentValue (CurrentValue)

Parameter

Parameter | Description
CurrentValue | Specifies the current value to be added.


AddDefaultValue Method (ParameterFieldDefinition Object)

The AddDefaultValue method adds a value to the group of default values for a specified parameter in a report. The default value set should fall within the scope of properties EditMask and MaximumValue and MinimumValue, if set. Use this method instead of SetDefaultValue if the parameter field allows multiple values.

Syntax

Sub AddDefaultValue (DefaultValue)

Parameter

Parameter | Description
DefaultValue | Specifies the default value to be added.


ClearCurrentValueAndRange Method(ParameterFieldDefinition Object)

The ClearCurrentValueAndRange method clears the specified parameter field of all current values and ranges.

Syntax

Sub ClearCurrentValueAndRange ()


DeleteNthDefaultValue Method (ParameterFieldDefinition Object)

The DeleteNthDefaultValue method deletes the nth default value of the parameter field.

Syntax

Sub DeleteNthDefaultValue(index As Integer)

Parameter

Parameter | Description
index | Index of the value to be deleted.


GetNthCurrentRange Method (ParameterFieldDefinition Object)

The GetNthCurrentRange method retrieves a value range from the specified parameter field in a report.

Syntax

Sub GetNthCurrentRange (index As Integer, pStart, pEnd, _

pRangeInfo As CRRangeInfo)

Parameters

Parameter | Description
index | Index of the value range to be retrieved.
pStart | Sets start of the value range.
pEnd | Sets end of the value range.
pRangeInfo | CRRangeInfo. Use this bitwise value to indicate whether the upper and/or lower bound of the range should be included.


GetNthCurrentValue Method (ParameterFieldDefinition Object)

The GetNthCurrentValue method returns a value from the specified parameter field of a report.

Syntax

Function GetNthCurrentValue (index As Integer)

Parameter

Parameter | Description
index | Index number of the current value to be retrieved.

Returns

Returns the current value specified by the index parameter.


GetNthDefaultValue Method (ParameterFieldDefinition Object)

Get NthDefaultValue method retrieves a default value for a specified parameter field in a report.

Syntax

Function GetNthDefaultValue (index As Integer)

Parameter

Parameter | Description
index | The index number of the default value to be retrieved.

Returns

Returns the default value specified by the index parameter.


SetNthDefaultValue Method (ParameterFieldDefinition Object)

The SetNthDefaultValue method sets a default value for a specified parameter field in a report. The default value set should fall within range and property EditMask if a string field, if set.

Syntax

Sub SetNthDefaultValue (index As Integer, nthDefaultValue)

Parameters

Parameter | Description
index | The index number of the default value to be set.
nthDefaultValue | Specifies the default value that you want to set for parameter field.


ParameterFieldDefinitions Collection

The ParameterFieldDefinitions Collection is a collection of parameter fields in the report. If the report contains any subreports, parameter fields for the subreports will not be included in the collection. Each subreport that has parameter fields will have its own collection.

ParameterFieldDefinitions Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of parameter fields in either the main report or the subreport. | Read only | None
Item (index As Long) | ParameterFieldDefinition Object. Gets the item in the Collection specified by parameter index. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None

Remarks

Item is a default property. You can reference a parameter field directly, for example, ParameterFieldDefinitions(1).


ParameterFieldDefinitions Collection Method

The following method is discussed in this section:

  • GetItemByName Method (ParameterFieldDefinitions Collection)


GetItemByName Method (ParameterFieldDefinitions Collection)

Use the GetItemByName method to retrieve a DatabaseFieldDefinition object by name.

Syntax

Sub GetItemByName(name As String, parameterFieldDefinition)

Parameters

Parameter | Description
name | The item's unique name index.
parameterFieldDefinition | A ParameterFieldDefinition object to hold the retrieved item.


ParameterValue Object

The ParameterValue object represents the initial value of a stored procedure parameter that will eventually be passed to the AddStoredProcedure Method (DatabaseTables Collection).

Note: The Prog Id CrystalRuntime.ParameterValue can be used with the CreateObject function in Visual Basic to create an instance of a ParameterValue object at runtime.

dim pv as Variant

set pv = CreateObject("CrystalRuntime.ParameterValue")

ParameterValue Object Properties

Property | Description | Read/Write | Restriction in event handler
StartValue | Gets or sets the start value of the range. | Read/Write | None
EndValue | Gets or sets the end value of the range. | Read/Write | None
RangeValue | Boolean. True if it is a range value. | Read/Write | None
RangeInfo | CRRangeInfo. Use this bitwise value to indicate whether the upper and/or lower bound of the range should be included. | Read/Write | None


ParameterValues Collection

The ParameterValues Collection is a collection of ParameterValue objects that will eventually be passed to the AddStoredProcedure Method (DatabaseTables Collection).

Note: The Prog Id CrystalRuntime.ParameterValues can be used with the CreateObject function in Visual Basic to create an instance of a ParameterValues collection at runtime.

dim pv as Variant

set pv = CreateObject("CrystalRuntime.ParameterValues")

ParameterValues Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of parameter fields in the collection. | Read only | None
Item (index As Long) | ParameterValue Object. Gets the item in the Collection specified by parameter index. | Read only | None


ParameterValues Collection Methods

The following methods are discussed in this section:

  • Add Method (ParameterValues Collection)
  • Delete Method (ParameterValues Collection)


Add Method (ParameterValues Collection)

Use the Add method to add a ParameterValue Object to the ParameterValues Collection.

Syntax

Sub Add(pValue As ParameterValue)

Parameter

Parameter | Description
pValue | The ParameterValue object to add to the Collection.


Delete Method (ParameterValues Collection)

Use the Delete method to remove a ParameterValue object from the Collection.

Syntax

Sub Delete (index)

Parameter

Parameter | Description
index | Specifies the index number of the item that you want to delete from the Collection.


ParameterValueInfo Object

The ParameterValueInfo object is comprised of ParameterValues Collections. ParameterValueInfo objects are eventually passed to the AddStoredProcedure Method (DatabaseTables Collection).

Note: The Prog Id CrystalRuntime.ParameterValueInfo can be used with the CreateObject function in Visual Basic to create an instance of a ParameterValueInfo object at runtime.

dim pv as Variant

set pv = CreateObject("CrystalRuntime.ParameterValueInfo")

ParameterValueInfo Object Properties

Property | Description | Read/Write | Restriction in event handler
ParameterValues | Gets or sets the value of a parameter. | Read/Write | None
ParameterName | Gets or sets the name of a parameter. | Read/Write | None


ParameterValueInfos Collection

ParameterValueInfos is a collection of ParameterValueInfo objects which is passed to the AddStoredProcedure Method (DatabaseTables Collection).

Note: The Prog Id CrystalRuntime.ParameterValueInfos can be used with the CreateObject function in Visual Basic to create an instance of a ParameterValueInfos object at runtime.

dim pv as Variant

set pv = CreateObject("CrystalRuntime.ParameterValueInfos")

ParameterValueInfos Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of parameter fields in the collection. | Read only | None
Item (index As Long) | ParameterValueInfo Object. Gets the item in the Collection specified by parameter index. | Read only | None


ParameterValueInfos Collection Methods

The following methods are discussed in this section:

  • Add Method (ParameterValueInfos Collection)
  • Delete Method (ParameterValueInfos Collection)


Add Method (ParameterValueInfos Collection)

Use the Add method to add a ParameterValueInfo Object to the ParameterValueInfos Collection.

Syntax

Sub Add(pValueInfo As ParameterValueInfo)

Parameter

Parameter | Description
pValueInfo | The ParameterValueInfo object to add to the Collection.

Returns

Returns the ParameterValueInfo object added to the Collection.


Delete Method (ParameterValueInfos Collection)

Use the Delete method to remove a ParameterValueInfo object from the Collection.

Syntax

Sub Delete (index)

Parameter

Parameter | Description
index | Specifies the index number of the item that you want to delete from the Collection.


PrintingStatus Object

The PrintingStatus object provides properties for retrieving information and setting options for the printing status of a report (for example, number of pages, latest page to be printed). A PrintingStatus object is obtained from the PrintingStatus property of the Report Object.

PrintingStatus Object Properties

Property | Description | Read/Write | Restriction in event handler
NumberOfPages | Long. Gets the total number of pages in the report. | Read only | None
NumberOfRecordPrinted | Long. Gets the number of records printed. | Read only | None
NumberOfRecordRead | Long. Gets the number of records read. | Read only | None
NumberOfRecordSelected | Long. Gets the number of records selected. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None
Progress | CRPrintingProgress. Gets the printing progress. | Read only | None


Report Object

A report corresponds to a print job in the Crystal Report Engine. When the report object is destroyed, or goes out of focus, it closes the print job. It holds on to Application Object. When a Report object gets destroyed, it releases the application.

Access to the Report object is dependent on the object variable you create. If the object variable goes out of scope, you will lose access to the Report object and, therefore, the report. You may want to declare your Report object variable as Global.

Report Object Properties

Property | Description | Read/Write | Restriction in event handler
Application | Application Object. Gets reference to the Application object that the Report object is associated with. | Read only | None
ApplicationName | String. Gets or sets the application name. | Read/Write | None
Areas | Areas Collection. Gets reference to the Areas Collection, a collection of all the areas in the report which can be indexed by a number or by a string, such as "RH", "GF1". The areas are in the same order as on the Crystal Reports Design Tab. For Example: RH, PH, GH1,...GHn, D, GFn,...GF1, RF, PF. The abbreviations for areas are case sensitive. | Read only | None
BottomMargin | Long. Gets or sets the page bottom margin, in twips. | Read/Write | Can be written only when formatting idle.
CanPerformGroupingOnServer | Boolean. Gets whether the report can perform grouping on the server. | Read only | None
CaseInsensitiveSQLData | Boolean. Gets or sets the report option that indicates whether the SQL data used in the report becomes case sensitive. | Read/Write | Can be written only when formatting idle.
ConvertDateTimeType | CRCommonFieldFormatConditionFormulaType. Gets or sets the report option that specifies the format to be converted for date/time fields. | Read/Write | Can be written only when formatting idle.
ConvertNullFieldToDefault | Boolean. Gets or sets the report option that indicates whether to convert any null values to the database field default. | Read/Write | Can be written only when formatting idle.
Database | Database Object. Gets reference to the Database object which represents the database used in the report. | Read only | None
DisplayProgressDialog | Boolean. Enable or disable the progress dialog. | Read/Write | Can be written only when formatting idle.
DriverName | String. Gets the printer driver name used by the current report. Gets an empty string if default printer is used. | Read only | Can be written only when formatting idle.
EnableAsyncQuery | Boolean. Gets or sets the enable AsyncQuery. | Read/Write | Can be written only when formatting idle.
EnableGeneratingDataForHiddenObject | Boolean. Gets or sets the Enable Generating Data For Hidden object option. | Read/Write | Can be written only when formatting idle.
EnableParameterPrompting | Boolean. Gets or sets the prompting for parameter fields option. | Read/Write | Can be written only when formatting idle.
EnablePerformQueriesAsynchronously | Boolean. Gets or sets the perform queries asynchronously option. | Read/Write | Can be written only when formatting idle.
EnableSelectDistinctRecords | Boolean. Gets or sets the select distinct records option | Read/Write | Can be written only when formatting idle.
ExportOptions | ExportOptions Object. Gets reference to ExportOptions object for the report. | Read only | None
FieldMappingType | CRFieldMappingType. Gets or sets the field mapping type. | Read/Write | Can be written only when formatting idle.
FormulaFields | FormulaFieldDefinitions Collection. Gets reference to Collection of all the named FormulaFieldDefinitions defined in the Report. | Read only | None
FormulaSyntax | CRFontColorConditionFormulaType. Gets or sets report formula syntax. | Read/Write | Can be written only when formatting idle.
GroupNameFields | GroupNameFieldDefinitions Collection. Gets reference to a collection of all the group name fields defined in the report. | Read only | None
GroupSelectionFormula | String. Gets or sets the group selection formula. | Read/Write | Can be written only when formatting idle.
GroupSortFields | SortFields Collection. Gets reference to group sort field collection. | Read only | None
HasSavedData | Boolean. Gets whether the report has data saved in memory. | Read only | None
KeywordsInReport | String. Gets or sets the keywords in the report. | Read/Write | Can be written only when formatting idle.
Kind | CRReportKind. Gets what kind of report. | Read only | None
LastGetFormulaSyntax | CRFontColorConditionFormulaType. Gets the formula syntax of the last formula text returned. | Read only | None
LeftMargin | Long. Gets or sets the page left margin, in twips. | Read/Write | Can be written only when formatting idle.
NeedUpdatedPages | Gets whether the user needs to update pages for display due to changes in the report. | Read only | None
NumberOfGroup | Long. Gets the number of groups in the report. | Read only | None
PageEngine | PageEngine Object. Gets reference to the PageEngine object. | Read only | None
PaperOrientation | CROpenReportMethod. Gets or sets the current printer paper orientation. For the default printer, crDefaultPaperOrientation is returned. | Read/Write | Can be written only when formatting idle.
PaperSize | CRPaperSize. Gets or sets the current printer paper size. For the default printer, crDefaultPaperSize is returned. | Read/Write | Can be read or written only when formatting idle.
PaperSource | CRPaperSource. Gets or sets the current printer paper source. | Read/Write | Can be written only when formatting idle.
ParameterFields | ParameterFieldDefinitions Collection. Gets reference to the collection of all the ParameterFieldDefinitions defined in the report. This property will return parameter fields found in the main report as well as any subreports included in the report (for example, if the main report has 3 parameters and a subreport included within the report has an additional 2 parameters, the number of parameter fields in the collection returned by Report.ParameterFields would be 5). | Read only | None
Parent | Report Object. Gets reference to the parent object for subreports. (NULL for main report). | Read only | None
PerformGroupingOnServer | Boolean. Gets or sets the performing grouping on server option. | Read/Write | Can be written only when formatting idle.
PortName | String. Gets the printer port name used by the current report. Gets an empty string if the default printer is used. | Read only | None
PrintDate | Date. Gets or sets the print date for the report. By default, the current date will be used. | Read/Write | Can be written only when formatting idle.
PrinterDuplex | CRPrinterDuplexType. Gets or sets the current printer duplex option. | Read/Write | Can be written only when formatting idle.
PrinterName | String. Gets the printer name used by the report. Gets an empty string if the default printer is used. | Read only | None
PrintingStatus | PrintingStatus Object. Gets PrintingStatus object for the report. | Read only | None
RecordSelectionFormula | String. Gets or sets record selection formula. | Read/Write | Can be written only when formatting idle.
RecordSortFields | SortFields Collection. Gets a collection of record sort fields. | Read only | None
ReportAlerts | ReportAlerts Collection. Gets reference to Collection of all the named Report Alerts defined in the Report. | Read only | None
ReportAuthor | String. Gets or sets the report author. | Read/Write | Can be written only when formatting idle.
ReportComments | String. Gets or sets report comments. | Read/Write | Can be written only when formatting idle.
ReportSubject | String. Gets or sets the report subject. | Read/Write | Can be written only when formatting idle.
ReportFormatStyle | CRReportFormatStyle. Gets or sets a report format style. | Read/Write | Can be written only when formatting idle.
ReportTemplate | String. Gets or sets the report template. | Read/Write | Can be written only when formatting idle.
ReportTitle | String. Gets or sets the report title. | Read/Write | Can be written only when formatting idle.
RightMargin | Long. Gets or sets the page right margin, in twips. | Read/Write | Can be written only when formatting idle.
RunningTotalFields | RunningTotalFieldDefinitions Collection. Gets running total fields collection. | Read only | None
SavePreviewPicture | Boolean. Gets or sets save preview picture with report option. | Read/Write | None
Sections | Sections Collection. Gets collection of all the sections in the report. | Read only | None
SQLExpressionFields | SQLExpressionFieldDefinitions Collection. Gets SQL expression field collection. | Read only | None
SQLQueryString | String. Gets or sets SQL query string. | Read/Write | Can be written only when formatting idle.
SummaryFields | SummaryFieldDefinitions Collection. Gets collection for group and report summaries (cross-tab summaries not available using this property). | Read only | None
TopMargin | Long. Gets or sets the page top margin, in twips. | Read/Write | Can be written only when formatting idle.
UseIndexForSpeed | Boolean. Gets or sets the use index for speed during record selection report option. | Read/Write | Can be written only when formatting idle.
VerifyOnEveryPrint | Boolean. Gets or sets the report option that indicates whether to verify the database every time the report is printed. | Read/Write | Can be written only when formatting idle.


Report Object Methods

The following methods are discussed in this section:

  • AddGroup Method (Report Object)—RDC Object Model
  • AddReportVariable Method (Report Object)
  • AutoSetUnboundFieldSource Method (Report Object)
  • CancelPrinting Method (Report Object)
  • DeleteGroup Method (Report Object
  • DiscardSavedData Method (Report Object)
  • Export Method (Report Object)
  • GetNextRows Method (Report Object)
  • GetReportVariableValue Method (Report Object)
  • OpenSubreport Method (Report Object)
  • PrinterSetup Method (Report Object)
  • PrintOut Method (Report Object)
  • PrintOutEx Method (Report Object)
  • ReadRecords Method (Report Object)
  • SaveAs Method (Report Object)
  • SelectPrinter Method (Report Object)
  • SetDialogParentWindow Method (Report Object)
  • SetReportVariableValue Method (Report Object)
  • SetUnboundFieldSource Method (FieldObject Object)


AddGroup Method (Report Object)—RDC Object Model

The AddGroup Method adds a group to the report. ConditionField indicates the field for grouping, Condition indicates a change in a field value that generates a grouping, and SortDirection specifies the direction in which groups are sorted.

Syntax

Sub AddGroup (GroupNumber As Integer, pConditionField As Object, _

Condition As CRGroupCondition, SortDirection As CRSortDirection)

Parameters

Parameter | Description
GroupNumber | Specifies the number of the group to be added (the position of the group in relation to existing groups). For example, to add a group to the first position, set GroupNumber=1.
pConditionField | Specifies the field to be grouped. The field can be a database field definition object or the field name.
Condition | CRGroupCondition. Specifies CRGroupCondition indicating the grouping condition (for example, group on any value or group dates weekly).
SortDirection | CRSortDirection. Specifies the sort direction for the group.


AddReportVariable Method (Report Object)

Use the AddReportVariable method to add a report variable to the report. This variable can then be used to provide a calculated field value in the Format Event. You can add as many report variables to your report as you need. Each report variable is identified by its name, which must be unique.

Syntax

Sub AddReportVariable (type As CRReportVariableValueType, _

pName As String, [arraySize As Long], [reserved])

Parameters

Parameter | Description
type | CRReportVariableValueType. Specifies the type of variable that you want to add to the report.
pName | Specifies the unique name for the report variable that you want to add.
[arraySize As Long] | Reserved. Do not use.
[reserved] | Reserved. Do not use.


AutoSetUnboundFieldSource Method (Report Object)

Use the AutoSetUnboundFieldSource method to automatically bind unbound report fields to database fields based on the unbound field's name or name and value type.

Syntax

Sub AutoSetUnboundFieldSource (matchType As CRBindingMatchType, _

[bindSubReports])

Parameters

Parameter | Description
matchType | CRBindingMatchType. Specifies whether to match name alone or name and data type.
[bindSubReports] | Specifies whether or not to bind subreport unbound fields.


CancelPrinting Method (Report Object)

Use the CancelPrinting method to cancel the printing of a report.

Syntax

Sub CancelPrinting ()


DeleteGroup Method (Report Object

Use the DeleteGroup method to remove a group from a report.

Syntax

Sub DeleteGroup (GroupNumber As Integer)

Parameter

Parameter | Description
GroupNumber | Specifies the index number of the group that you want to delete from the report.


DiscardSavedData Method (Report Object)

Use the DiscardSavedData method to discard any saved data with the report before previewing. This method can be invoked only when in formatting idle mode.

Syntax

Sub DiscardSavedData ()


Export Method (Report Object)

Use the Export method to export reports to a format and destination specified with ExportOptions Object.

Syntax

Sub Export ([promptUser])

Parameters

Parameter | Description
[promptUser] | Specifies Boolean value indicating if user should be prompted for export options. If you don't want to prompt the user, then you must set all necessary export options. The application will prompt automatically for any missing export options, even if promptUser = FALSE. Default value = TRUE (prompt user).


GetNextRows Method (Report Object)

Use the GetNextRows method to get the specified rowset.

Syntax

Function GetNextRows (startRowN As Long, pRowN As Long)

Parameters

Parameter | Description
startRowN | Specifies the row number to start the rowset on.
pRowN | Specifies the number of rows to return to the rowset.

Returns

Returns the specified rowset.


GetReportVariableValue Method (Report Object)

Use the GetReportVariableValue method to get the value of the specified uniquely named report variable. This call can only be made in the formatting active mode.

Syntax

Function GetReportVariableValue (pName As String)

Parameters

Parameter | Description
pName | Specifies the unique name of the report variable for which you want to get the value.

Returns

Returns value of the specified report variable.


OpenSubreport Method (Report Object)

The OpenSubreport method opens a subreport contained in the report and returns a Report object corresponding to the named subreport.

Syntax

Function OpenSubreport (pSubreportName As String) As Report

Parameter

Parameter | Description
pSubreportName | Specifies the file name of the subreport to be opened.

Returns

Returns the specified subreport as a Report object.


PrinterSetup Method (Report Object)

Use the PrinterSetup method to open the printer setup dialog box so that the user can change printers or printer settings for the report.

Syntax

Sub PrinterSetup (hWnd As Long)

Parameter

Parameter | Description
hWnd | Specifies the handle of the printer setup dialog box parent window. If you pass 0, the top level application window will be the parent.


PrintOut Method (Report Object)

Use the PrintOut method to print out the specified pages of the report to the printer selected using the SelectPrinter Method (Report Object). If no printer is selected, the default printer specified in the report will be used. This method can be invoked only when in formatting idle mode.

Syntax

Sub PrintOut ([promptUser], [numberOfCopy], [collated], _

[startPageN], [stopPageN])

Parameters

Parameter | Description
[promptUser] | Specifies Boolean value indicating if the user should be prompted for printer options.
[numberOfCopy] | Specifies the number of report copies you want printed.
[collated] | Specifies Boolean value specifying whether or not you want the report copies collated.
[startPageN] | Specifies the first page that you want printed.
[stopPageN] | Specifies the last page that you want printed.


PrintOutEx Method (Report Object)

Use the PrintOutEx method to export the specified pages of the report to the printer selected using the SelectPrinter Method (Report Object). If no printer is selected, the default printer specified in the report will be used. This method can be invoked only when in formatting idle mode.

Syntax

Sub PrintOutEx ([promptUser], [numberOfCopy], [collated], [startPageN], [stopPageN], [printFileName As String])

Parameters

Parameter | Description
[promptUser] | Specifies Boolean value indicating if the user should be prompted for printer options.
[numberOfCopy] | Specifies the number of report copies you want printed.
[collated] | Specifies Boolean value specifying whether or not you want the report copies collated.
[startPageN] | Specifies the first page that you want printed.
[stopPageN] | Specifies the last page that you want printed.
[printFileName] | String. Specifies the name of the export print file.


ReadRecords Method (Report Object)

Use the ReadRecords method to force the report to read all records in the report from the database.

Syntax

Sub ReadRecords ()


SaveAs Method (Report Object)

Use the SaveAs method to save a report with the ability to specify Crystal Reports 8 or 7 version file format. The user can specify which format to use when saving the report. This call can only be made in formatting idle mode.

Syntax

Sub SaveAs (pFilePath As String, fileFormat As CRReportFileFormat)

Parameters

Parameter | Description
pFilePath | Specifies the file path and name that you want to use to save the report.
fileFormat | CRReportFileFormat. Specifies the file format that you want to use to save the report.


SelectPrinter Method (Report Object)

The SelectPrinter method selects a different printer for the report. This method can be invoked only when in formatting idle mode.

Syntax

Sub SelectPrinter (pDriverName As String, pPrinterName As String, _

pPortName As String)

Parameters

Parameter | Description
pDriverName | Specifies the name of the printer driver for the selected printer.
pPrinterName | Specifies the printer name for the selected printer.
pPortName | Specifies the port name for the port to which the selected printer is attached.


SetDialogParentWindow Method (Report Object)

The SetDialogParentWindow method sets the dialog parent window.

Syntax

Sub SetDialogParentWindow (hWnd As Long)

Parameter

Parameter | Description
hWnd | Specifies the handle of the parent window.


SetReportVariableValue Method (Report Object)

Use the SetReportVariableValue method to set the value of a report variable into the Print Engine. The report variable is designed to be used in Format Event to do calculated fields. However, you should not depend on how many times an event is fired to do total calculations—make sure that the calculation for the report variable is correct. The Print Engine keeps track of the status. This call can be made only in formatting active mode.

Syntax

Sub SetReportVariableValue (pName As String, var)

Parameters

Property | Description
pName | Specifies the name of the variable for which you want to set the value.
var | Specifies the value that you want to set.


SetUserPaperSize Method (Report Object)

Use the SetUserPaperSize method to set the paper length and width for the report.

Syntax

Sub SetUserPaperSize (length As Integer, Width As Integer)

Parameters

Parameter | Description
length | Integer. Specifies the length of the report in pixels.
Width | Integer. Specifies the width of the report in pixels.


Report Object Events

The following events are discussed in this section:

  • AfterFormatPage Event (Report Object)
  • BeforeFormatPage Event (Report Object)
  • FieldMapping Event (Report Object)
  • NoData Event (Report Object)


AfterFormatPage Event (Report Object)

The AfterFormatPage event is fired after formatting a page.

Syntax

Event AfterFormatPage (PageNumber As Long)

Parameter

Parameter | Description
PageNumber | Specifies the number of the report page triggering the event.


BeforeFormatPage Event (Report Object)

The BeforeFormatPage event is fired before formatting a page.

Syntax

Event BeforeFormatPage (PageNumber As Long)

Parameter

Parameter | Description
PageNumber | Specifies the number of the report page triggering the event.


FieldMapping Event (Report Object)

The FieldMapping event fires if the database is changed while verifying database.

Syntax

Event FieldMapping (reportFieldArray, databaseFieldArray, _

useDefault As Boolean)

Parameters

Parameter | Description
reportFieldArray | Specifies the report field array to map.
databaseFieldArray | Specifies the database field array to map.
useDefault | If TRUE, the values passed with parameters reportFieldArray and databaseFieldArray will be ignored and the default values used; if FALSE, the values passed with reportFieldArray and databaseFieldArray will be used.


NoData Event (Report Object)

The NoData event fires when there is no data for the report.

Syntax

Event NoData (pCancel As Boolean)

Parameter

Parameter | Description
pCancel | Specifies whether to cancel the report.


ReportAlert Object

The ReportAlert object represents a Report Alert contained in a report. This object provides properties for getting and setting information on Report Alerts in the report.

Report Alerts are custom messages created in either the Crystal Reports Designer, the Report Designer Component, or the Embeddable Crystal Reports Designer Control. Report Alerts may indicate action to be taken by the user or information about report data. For more information, see "Report Alerts" in the Crystal Reports User's Guide.

ReportAlert Object Properties

Property | Definition | Read/Write | Restriction in event handler
AlertInstances | ReportAlertInstances Collection. Gets a reference to a collection of all the Report Alert instances created when the Report Alert is run. | Read only | None
ConditionFormula | String. Gets or sets the condition formula for the Report Alert. The condition formula can be based on recurring records or on summary fields, but cannot be based on print-time fields, such as running totals or print time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
DefaultMessage | String. Gets or sets the default message for the Report Alert. | Read/Write | Can be written only when formatting idle.
IsEnabled | Boolean. Gets or sets whether or not the Report Alert is enabled. | Read/Write | Can be written only when formatting idle.
MessageFormula | String. Gets or sets the message when the Report Alert is triggered. The result of the formula must be a string, and is created by combining a string with a report field. If MessageFormula is set it will override the value set for DefaultMessage. | Read/Write | Can be written only when formatting idle.
Name | String. Gets or sets the name of the Report Alert. | Read/Write | Can be written only when formatting idle.
Parent | Report Object. Gets reference to the parent object. | Read only | None


ReportAlerts Collection

The ReportAlerts collection contains the Report Alert objects defined in a report. Access a specific ReportAlert Object in the collection using the Item property.

ReportAlerts Collection Properties

Property | Definition | Read/Write | Restriction in event handler
Count | Long. Gets the number of ReportAlert Object, in the collection. | Read only | None
Item (indexAs Long) | ReportAlert Object. Gets an item from the Collection. Item has an index parameter that is a 1-based index (for example, Item(1) for the first Report Alert in the collection). The items in the collection are indexed in the order that they were added to the report. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None

ReportAlerts Collection Methods

The following methods are discussed in this section:

  • Add Method (ReportAlerts Collection)
  • Delete Method (ReportAlerts Collection)


Add Method (ReportAlerts Collection)

The Add method is used to add a Report Alert object to the report.

Syntax

Function Add (Name As String, DefaultMessage As String, IsEnabled As Boolean, ConditionFormula As String, [MessageFormula as String]) As ReportAlert

Parameter | Description
Name | Specifies the name of the Report Alert.
DefaultMessage | Specifies the default message created by the Report Alert.
IsEnabled | Specifies whether or not the Report Alert is enabled when the report is run.
ConditionFormula | Specifies the conditional formula that evaluates when the Report Alert is triggered.
MessageFormula | Optional. Formula used to create the message when the Report Alert is triggered. The result of the formula must be a string, and is created by combining a string with a report field. If MessageFormula is set it will override the value set for DefaultMessage.

Sample

In this example a report is grouped by country and contains a summary of last year's sales per country. The Report Alert will be triggered when the summary of last year's sales exceeds $25,000.00. When the Report Alert is triggered a message is created from the default message and the country name.

Dim name, defaultMessage, conditionFormula, messageFormula As String

'Name of the Report Alert

name = "Sales Alert"

defaultMessage = "Great sales in "

' Conditional formula used to evaluate the Report Alert.

conditionFormula = "Sum ({Customer.Last Year's Sales}, {Customer.Country}) > 25000"

' Replaces the default message set for the Report Alert. The message is

' created in a formula by concatenating the value set in the

' DefaultMessage parameter, and the group name of the country that

' triggers the Report Alert.

' DefaultAttribute is a function used by the Formula Editor to return

' the default message set for the Report Alert.

messageFormula = "DefaultAttribute & GroupName ({Customer.Country})"

Report.ReportAlerts.Add _

name, defaultMessage, True, conditionFormula, messageFormula


Delete Method (ReportAlerts Collection)

Use the Delete method to remove a ReportAlert object from the Collection.

Syntax

Sub Delete (index)

Parameter

Parameter | Description
index | Specifies the index number of the object that you want to remove from the Collection.


ReportAlertInstance Object

A ReportAlertInstance object is created each time a Report Alert is triggered. This object contains a property for getting the message created for that specific instance of the Report Alert.

Note: In the present build only the first ReportAlertInstance is created at runtime. This limitation will be addressed in a future release.

ReportAlertInstance Object Properties

Property | Definition | Read/Write | Restriction in event handler
AlertMessage | String. Gets the message returned at the time the Report Alert is triggered. | Read only | None
Parent | ReportAlert Object. Gets reference to the parent object. | Read only | None


ReportAlertInstances Collection

The ReportAlertInstances collection contains the ReportAlertInstance objects created when a Report Alert is triggered. Access a specific ReportAlertInstance Object in the collection using the Item property.

Note: In the present build only the first ReportAlertInstance is created at runtime. This limitation will be addressed in a future release.

ReportAlertInstances Properties

Property Definition Read/Write Restriction in event handler

Count

Long. Gets the number of ReportAlertInstance Object in the collection.

Read only

None

Item (indexAs Long)

ReportAlertInstance Object. Gets an item from the Collection. Item has an index parameter that is a 1-based index (for example, Item(1) for the first ReportAlertInstance in the collection). The items in the collection are indexed in the order that they were added to the report.

Note: In the present build only the first ReportAlertInstance is created at runtime. This limitation will be addressed in a future release.

Read only

None

Parent

ReportAlert Object. Gets reference to the parent object.

Read only

None


ReportObjects Collection

The ReportObjects Collection is a collection of report objects in a section. Report objects can be a field, text, OLE, cross-tab, subreport, BLOB field, Box, Graph, Line, Map, or OlapGrid objects. Access a specific object in the collection using the Item property.

ReportObjects Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of report objects in the collection. | Read only | None
Item (index) As Object | Gets a report object. Depending on the type of item referenced, this can be a BlobFieldObject Object, FieldMappingData Object, TextObject Object,Page Object, CrossTabObject Object, BoxObject Object, Remarks, GraphObject Object, LineObject Object, MapObject Object, OlapGridObject Object. Item has an index parameter that is a numeric, 1-based index (that is, Item (1)). The items in the collection are indexed in the order they were added to the report. | Read only | None
Parent | Section Object. Gets reference to the parent object. | Read only | None

Remarks

Item is a default property. You can reference a report object directly, for example, ReportObjects(1).


RunningTotalFieldDefinition Object

The RunningTotalFieldDefinition object represents a running total field used in the report. This object provides properties for getting information on running total fields in the report.

RunningTotalFieldDefinition Object Properties

Property | Definition | Read/Write | Restriction in event handler
EvaluateCondition | CRRunningTotalCondition. Gets evaluate condition. | Read only | None
EvaluateConditionField | Object. Gets evaluate condition field. | Read only | None
EvaluateConditionFormula | String. Gets or sets evaluate condition formula. | Read/Write | Can be written only when formatting idle.
EvaluateGroupNumber | Integer. Gets or sets evaluate group number. | Read/Write | Can be written only when formatting idle.
HierarchicalSummaryType | CRHierarchicalSummaryType. Gets or sets whether or not to calculate the running total across the hierarchy in a hierarchically grouped report. | Read/Write | Can be written only when formatting idle.
Kind | CRFieldKind. Gets which kind of field (that is, database, summary, formula, etc.). | Read only | None
Name | String. Gets the unique formula name of the field within the report (table.FIELD). For example, {#Test}. | Read only | None
NextValue | Variant. Gets the field next value. | Read only | Can be read only when top-level Report object is formatting active.
NumberOfBytes | Integer. Gets the number of bytes required to store the field data in memory. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None
PreviousValue | Variant. Gets the field previous value. | Read only | Can be read only when top-level Report object is formatting active.
ResetCondition | CRRunningTotalCondition. Gets the reset condition. | Read only | None
ResetConditionField | Object. Gets reset condition field. | Read only | None
ResetConditionFormula | String. Gets or sets the reset condition formula. | Read/Write | Can be written only when formatting idle.
ResetGroupNumber | Integer. Gets or sets the reset group number. | Read/Write | Can be written only when formatting idle.
RunningTotalFieldName | String. Gets the running total field name. | Read only | None
SecondarySummarizedField | Object. Gets the secondary summarized field. | Read only | Can be written only when formatting idle.
SummarizedField | Object. Gets the summarized field. | Read only | Can be written only when formatting idle.
SummaryOperationParameter | Long. Gets or sets summary operation parameter. | Read/Write | Can be written only when formatting idle.
SummaryType | CRSummaryType. Gets or sets summary type. | Read/Write | Can be written only when formatting idle.
Value | Variant. Gets the field current value. | Read only | Can be read only when top-level Report object is formatting active.
ValueType | CRFieldValueType. Gets which type of value is found in the field. | Read only | None


RunningTotalFieldDefinition Object Methods

The following methods are discussed in this section:

  • SetEvaluateConditionField Method(RunningTotalFieldDefinition Object)
  • SetNoEvaluateCondition Method (RunningTotalFieldDefinition Object)
  • SetNoResetCondition Method (RunningTotalFieldDefinition Object)
  • SetResetConditionField Method (RunningTotalFieldDefinition Object)
  • SetSecondarySummarizedField Method (RunningTotalFieldDefinition Object)
  • SetSummarizedField Method (RunningTotalFieldDefinition Object)


SetEvaluateConditionField Method(RunningTotalFieldDefinition Object)

Use the SetEvaluateConditionField to set the evaluate condition field.

Syntax

Sub SetEvaluateConditionField (pEvaluateConditionField)

Parameter

Parameter | Description
pEvaluateConditionField | Specifies the condition field that you want to use.


SetNoEvaluateCondition Method (RunningTotalFieldDefinition Object)

Use the SetNoEvaluateCondition method to specify no evaluate condition for the RunningTotalFieldDefinition object.

Syntax

Sub SetNoEvaluateCondition ()


SetNoResetCondition Method (RunningTotalFieldDefinition Object)

Use the SetNoResetCondition method to specify no reset condition for the RunningTotalFieldDefinition object.

Syntax

Sub SetNoResetCondition ()


SetResetConditionField Method (RunningTotalFieldDefinition Object)

Use the SetResetConditionField to specify the reset condition field to use with the RunningTotalFieldDefinition object.

Syntax

Sub SetResetConditionField (pResetConditionField)

Parameter

Parameter | Description
pResetConditionField | Specifies the condition field that you want to use.


SetSecondarySummarizedField Method (RunningTotalFieldDefinition Object)

Use the SetSecondarySummarizedField method to specify which condition field you want to use as the second summarized field for the RunningTotalFieldDefinition object.

Syntax

Sub SetSecondarySummarizedField (secondarySummariedField)

Parameter

Parameter | Description
SecondarySummarizedField | Specifies the condition field that you want to use.


SetSummarizedField Method (RunningTotalFieldDefinition Object)

Use the SetSummarizedField method to specify a second summarized field for the RunningTotalFieldDefinition object.

Syntax

Sub SetSummarizedField (SummarizedField)

Parameter

Parameter | Description
SummarizedField | Specifies the condition field that you want to use.


RunningTotalFieldDefinitions Collection

The RunningTotalFieldDefinitions Collection is a collection of running total field definition objects. One object exists in the collection for every running total field accessed by the report. Access a specific RunningTotalFieldDefinition Object in the collection using the Item property.

RunningTotalFieldDefinitions Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of RunningTotalFieldDefinition Object in the collection. | Read only | None
Item (indexAs Long) | RunningTotalFieldDefinition Object. Gets an item from the Collection. Item has an index parameter that is a 1-based index (for example, Item(1) for the first database field in the collection). The items in the collection are indexed in the order that they were added to the report. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None

Remarks

Instead of using the Item property as shown, you can reference a database directly, for example, RunningTotalFieldDefinitions(1).


RunningTotalFieldDefinitions Collection Methods

The following methods are discussed in this section:

  • Add Method (RunningTotalFieldDefinitions Collection)
  • Delete Method (RunningTotalFieldDefinitions Collection)
  • GetItemByName Method (RunningTotalFieldDefinitions Collection)


Add Method (RunningTotalFieldDefinitions Collection)

Use the Add method to add a RunningTotalFieldDefinition Object to the Collection.

Syntax

Function Add (runningTotalName As String) As RunningTotalFieldDefinition

Parameter

Parameter | Description
runningTotalName | Specifies the name of the RunningTotal field that you want to add.

Returns

Returns a RunningTotalFieldDefinition Object member of the Collection.


Delete Method (RunningTotalFieldDefinitions Collection)

Use the Delete method to remove a RunningTotalFieldDefinition object from the Collection.

Syntax

Sub Delete (index)

Parameter

Parameter | Description
index | Specifies the index number of the object that you want to remove from the Collection.


GetItemByName Method (RunningTotalFieldDefinitions Collection)

Use the GetItemByName method to retrieve a RunningTotalFieldDefinition object by name.

Syntax

Sub GetItemByName(name As String, runningTotalFieldDefinition)

Parameters

Parameter | Description
name | The item's unique name.
runningTotalFieldDefinition | A RunningTotalFieldDefinition object to hold the retrieved item.


Section Object

Report areas contain at least one section. The Section object includes properties for accessing information regarding a section of your report. This object holds on to a report object, then releases the report object when it is destroyed.

Section Object Properties

Property | Description | Read/Write | Restriction in event handler
BackColor | OLE_COLOR. Gets or sets the section background color. | Read/Write | Can be written only when formatting idle or active.
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
CssClass | String. Gets or sets the cascading style sheet Class. | Read/Write | Can be written only when formatting idle.
Height | Long. Gets or sets the height of the section, in twips. | Read/Write | Can be written only when formatting idle or active.
KeepTogether | Boolean. Gets or sets the option that indicates whether to keep the entire section on the same page if it is split into two pages. | Read/Write | Can be written only when formatting idle or active.
MinimumHeight | Long. Gets the minimum section height, in twips. | Read only | None
Name | String. Gets or sets the name of the section. | Read/Write | Can be written only when formatting idle.
NewPageAfter | Boolean. Gets or sets the option that indicates whether to start a new page after the current section. | Read/Write | Can be written only when formatting idle or active.
NewPageBefore | Boolean. Gets or sets the option that indicates whether to start a new page before the current section. | Read/Write | Can be written only when formatting idle or active.
Number | Integer. Gets the index number associated with the section in the area (for example, if the first section in an area, the number returned is 1). | Read only | None
Parent | Area Object. Gets reference to the parent object. | Read only | None
PrintAtBottomOfPage | Boolean. Gets or sets the option that indicates whether to print the current section at the bottom of the page. | Read/Write | Can be written only when formatting idle or active.
ReportObjects | ReportObjects Collection. Gets reference to the heterogeneous collection of report objects for the section. | Read only | None
ResetPageNumberAfter | Boolean. Gets or sets the option that indicates whether to reset the page number after the current section. | Read/Write | Can be written only when formatting idle or active.
Suppress | Boolean. Gets or sets the section visibility. | Read/Write | Can be written only when formatting idle or active.
SuppressIfBlank | Boolean. Gets or sets the option that indicates whether to suppress the current section if it is blank. | Read/Write | Can be written only when formatting idle or active.
UnderlaySection | Boolean. Gets or sets the underlay following section option. | Read/Write | Can be written only when formatting idle or active.
Width | Long. Gets the width of the section, in twips. | Read only | None


Section Object Methods

The following methods are discussed in this section:

  • AddBlobFieldObject Method (Section Object)
  • AddBoxObject Method (Section Object)
  • AddCrossTabObject Method (Section Object)
  • AddFieldObject Method (Section Object)
  • AddGraphObject Method (Section Object)
  • AddLineObject Method (Section Object)
  • AddPictureObject Method (Section Object)
  • AddSpecialVarFieldObject Method (Section Object)
  • AddSubreportObject Method (Section Object)
  • AddSummaryFieldObject Method (Section Object)
  • AddTextObject Method (Section Object)
  • AddUnboundFieldObject Method (Section Object)
  • DeleteObject Method (Section Object)
  • ImportSubreport Method (Section Object)


AddBlobFieldObject Method (Section Object)

The AddBlobFieldObject method adds a BlobFieldObject Object to the Section object.

Syntax

Function AddBlobFieldObject (Field, Left As Long, Top As Long _

) As BlobFieldObject

Parameters

Parameter | Description
Field | Variant. Can be formula form name or any field definition that specifies the field that you want to add.
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.

Returns

Returns a BlobFieldObject Object.


AddBoxObject Method (Section Object)

The AddBoxObject method adds a BoxObject Object to the Section object.

Syntax

Function AddBoxObject (Left As Long, Top As Long, Right As Long, _

Bottom As Long, [pEndSection]) As BoxObject

Parameters

Parameter | Description
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Right | Specifies the offset of the bottom right corner of the object that you are adding relative to the bottom right corner of the parent (or end) Section, in twips.
Bottom | Specifies the offset of the bottom right corner of the object that you are adding relative to the bottom right corner of the parent (or end) Section, in twips.
[pEndSection] | Specifies the Section in which the end of the Box object will be placed, if not the parent Section.

Returns

Returns a BoxObject Object.


AddCrossTabObject Method (Section Object)

The AddCrossTabObject method adds a CrossTabObject Object to the Section object. This method creates an empty CrossTabObject. Use the CrossTabObject properties and methods to add grouping and summary info.

Syntax

Function AddCrossTabObject (Left As Long, Top As Long) As CrossTabObject

Parameters

Parameter | Description
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.

Returns

Returns a CrossTabObject Object.


AddFieldObject Method (Section Object)

The AddFieldObject method adds a FieldMappingData Object to the Section object. The FieldObject can be reference to a database field definition, formula field definition, running total field definition, SQL expression field definition, or parameter field definition.

Syntax

Function AddFieldObject (Field, Left As Long, Top As Long) As FieldObject

Parameters

Parameter | Description
Field | Specifies the field that you want to add to the Section.
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.

Returns

Returns a FieldMappingData Object.


AddGraphObject Method (Section Object)

The AddGraphObject method adds a GraphObject Object (Chart) to the Section object. The inserted GraphObject is empty. Use the GraphObject properties and methods to add data, groups and settings. If optional parameter [pCrossTabObject] is passed, you can insert a CrossTab Chart.

Syntax

Function AddGraphObject (graphDataType As CRGraphDataType, _

Left As Long, Top As Long, [pCrossTabObject]) As GraphObject

Parameters

Parameter | Description
graphDataType | CRGraphDataType. Specifies the data type for the graph that you want to add.
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
[pCrossTabObject] | If graphDataType=crCrossTabGraph, this parameter specifies the CrossTabObject to associate with the chart.

Returns

Returns a GraphObject Object.


AddLineObject Method (Section Object)

The AddLineObject method adds a LineObject Object to the Section object. If optional parameter [pEndSection] is passed different from the current section, you can add a vertical line across sections.

Syntax

Function AddLineObject (Left As Long, Top As Long, _

Right As Long, Bottom As Long, [pEndSection]) As LineObject

Parameters

Parameter | Description
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Right | Specifies the offset of the bottom right corner of the object that you are adding relative to the bottom right corner of the parent (or end) Section, in twips.
Bottom | Specifies the offset of the bottom right corner of the object that you are adding relative to the bottom right corner of the parent (or end) Section, in twips.
[pEndSection] | Specifies the Section in which the end of the Line object will be placed, if not the parent Section.

Returns

Returns a LineObject Object.


AddPictureObject Method (Section Object)

The AddLineObject method adds a picture object from an image in the form of an OleObject Object to the Section object.

Syntax

Function AddPictureObject (pImageFilePath As String, Left As Long, _

Top As Long) As OleObject

Parameters

Parameter | Description
pImageFilePath | Specifies the image file path and name that you want to add.
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.

Returns

Returns an OleObject Object.


AddSpecialVarFieldObject Method (Section Object)

The SpecialVarFieldObject Method adds a SpecialVar FieldMappingData Object to the Section object.

Syntax

Function AddSpecialVarFieldObject (specialVarType As CRSpecialVarType, _

Left As Long, Top As Long) As FieldObject

Parameters

Parameter | Description
specialVarType | CRSpecialVarType. Specifies the SpecialVar type.
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.

Returns

Returns a FieldMappingData Object.


AddSubreportObject Method (Section Object)

The SubReportObject method adds a SubreportObject Object to the Section object. This method adds an empty subreport to the Section. You can then add objects and sections to the SubreportObject.

Syntax

Function AddSubreportObject (pSubreportName As String, _

Left As Long, Top As Long) As SubreportObject

Parameters

Parameter | Description
pSubreportName | Specifies the name of the subreport that you want to add.
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.

Returns

Returns a SubreportObject Object.


AddSummaryFieldObject Method (Section Object)

The AddSummaryField method adds a summary FieldMappingData Object to the Section object.

Syntax

Function AddSummaryFieldObject (Field, SummaryType As CRSummaryType, _

Left As Long, Top As Long, [secondSummaryFieldOrFactor]) As FieldObject

Parameters

Parameter | Description
Field | Specifies the summary field that you want to add.
SummaryType | CRSummaryType. Specifies the type of summary field.
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
[secondSummaryFieldOrFactor] | Specifies the second summary field or factor, if required by the summary type.

Returns

Returns a FieldMappingData Object.


AddTextObject Method (Section Object)

The AddTextObject method adds a TextObject Object to the Section object. String parameter pText can contain formatting information such as tab stops and carriage returns.

Syntax

Function AddTextObject (pText As String, Left As Long, Top As Long, _

[formatText]) As TextObject

Parameters

Parameter | Description
pText | Specifies the text that you want to add.
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
[formatText] | Boolean. If TRUE, the text will be formatted according to the formatting characters included in the text string (for example, carriage returns, tabs). If FALSE, formatting characters in the text string will be ignored.

Returns

Returns a FieldMappingData Object.


AddUnboundFieldObject Method (Section Object)

The AddUnboundFieldObject method adds an unbound FieldMappingData Object to the Section object. The unbound field can be bound to a Crystal Report formula or a data source at runtime.

Syntax

Function AddUnboundFieldObject (ValueType As CRFieldValueType, _

Left As Long, Top As Long) As FieldObject

Parameters

Parameter | Description
ValueType | CRFieldValueType. Specifies the type of value in the field.
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.

Returns

Returns a FieldMappingData Object.


DeleteObject Method (Section Object)

The DeleteObject method removes an object from the Section object.

Syntax

Sub DeleteObject (reportObject)

Parameter

Parameter | Description
reportObject | Specifies the report object that you want to remove from the Section.


ImportSubreport Method (Section Object)

Examples

The ImportSubreport method imports a SubreportObject Object into the Section object. With this call you can insert a subreport object obtained from an existing report file. The inserted Subreport object will have all of the objects and sections of the original (source) report, except for Page Header and Page Footer sections.

Syntax

Function ImportSubreport (subreportFileName As String, _

Left As Long, Top As Long) As SubreportObject

Parameters

Parameter | Description
subreportFileName | Specifies the name of the subreport that you want to import.
Left | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.
Top | Specifies the offset of the top left corner of the object that you are adding relative to the top left corner of the parent Section, in twips.

Returns

Returns a SubreportObject Object.


Section Object Events

The following event is discussed in this section:

  • Format Event (Section Object)


Format Event (Section Object)

Examples

The Format event is fired before the print engine starts formatting a section. In the Format event handler you can use the object model to write some code to change the outcome of the formatted section. Be aware, however, that not all of the properties and methods provided in the object model are accessible at all times in the event handler. Specifically, only those properties and methods that have been marked "formatting active" or "no restrictions" can be used in the Event.

Syntax

Event Format (FormattingInfo As Object)

Parameter

Parameter | Description
FormattingInfo | The FormattingInfo object which will contain formatting information to be used by the Format event handler.

Remarks

The following comments regarding Restrictions and Rules apply to Format Event:

Restrictions

The Format event handler should not have any state. No matter when or how many times it is called it should always behave the same way. It should not keep track of how many times it is called and then, for example, change the background color based on how many times it has been called. The print engine formatting procedure is very complicated and one section can be formatted many times depending on different situations.

Note: Because the Format event for each section may be fired more than once during page printing you should not use it to do any totaling in which values are carried over from one section to another. However, you can use report variables to do calculated fields.

There are three formatting modes:

FormattingIdle | No formatting occurs. This can be before going to preview or print or between changing pages in the viewer.
FormattingActive | The start of formatting an object. The object mode is marked as formatting active.
FormattingInactive | When the print engine is formatting and one object is in FormattingActive mode the rest of the objects are in FormattingInactive mode.

Since there is only one section Format event when one section is formatting all of the objects in that section are in FormattingActive mode and all the rest of the sections and objects are in FormattingInactive mode.

Rules
  • The read property can be accessed in any formatting mode. (There are a few exceptions, please see the object model reference section.)
  • Top level Report, Areas and Area write properties and methods can only be accessed in formatting idle mode, aside from a few exceptions.
  • When in FormattingIdle mode you should make changes before going to preview or print. Making changes between changing pages may result in an unexpected result.
  • For sections and objects within sections write property or method access is denied when the section is in FormattingInactive mode.
  • For sections and objects within sections some write property or method access is permitted and some denied while the section is in FormattingActive mode. Please refer the object model reference for details.


Sections Collection

Sections can come from either the Report Object or Area Object. The Sections Collection is a collection of section objects. Access a specific Section object in the collection using the Item property.

  • When from the Report object, the sections object will contain all the sections in the report.
  • When from the Area object, the sections object will contain all the sections in the area only.

Sections Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of section in the collection. | Read only | None
Item(index) | Section Object. Gets reference to an item in the Collection. Item has an index parameter that can be either a string reference to the area section (i.e., for areas with one section: "RH", "PH", "GHn", "D", "GFn", "PF", or "RF") or a numeric, 1-based index (i.e., Item (1)) for the Report Header area. Numeric index for sections starts at 1 for first section in the area/report and continues in order of appearance. If the area has multiple sections, they are represented using a lowercase letter (for example, "Da", "Db). | Read only | None
Parent | Report Object or Area Object. Gets reference to the parent object. | Read only | None

Remarks

Instead of using the Item property as shown, you can reference a section directly, for example, Sections ("Da").


Sections Collection Methods

The following methods are discussed in this section:

  • Add Method (Sections Collection)
  • Delete Method (Sections Collection)


Add Method (Sections Collection)

Use Add method to add a Section Object to the Sections Collection.

Syntax

Function Add ([index]) As Section

Parameter

Parameter | Description
[index] | Specifies the index where you would like to add the Section to the Collection.

Returns

Returns a Section Object member of the Sections Collection.


Delete Method (Sections Collection)

Use Delete method to remove a Section Object from the Sections Collection.

Syntax

Sub Delete(index)

Parameter

Parameter | Description
index | Specifies the index of the Section that you want to delete from the Collection.


SortField Object

The SortField object includes properties for accessing information for record or group sort fields. It holds on to Report object, then releases the report object when destroyed. This object has an index instance variable to indicate its index.

SortField Object Properties

Property | Description | Read/Write | Restriction in event handler
Field | Object. Gets or sets the sorting field definition object. | Read/Write | Can be read or written only when formatting idle.
Parent | Report Object. Gets reference to the parent object. | Read only | None
SortDirection | CRSortDirection. Gets or sets the sort direction. | Read/Write | Can be written only when formatting idle.


SortFields Collection

The SortFields Collection is a collection of sort fields; can be either record sort field or group sort field. Access a specific SortField object in the collection using the Item property.

SortFields Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of sort fields in the collection. | Read only | None
Item (index As Long) | SortField Object. Gets reference to an item in the Collection. Item has an index parameter that is a numeric, 1-based index (that is, Item (1)). The sort fields in the collection are indexed in the order they were added as sort fields to the report. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None

Remarks

Instead of using the Item property as shown, you can reference a sort field directly, for example, SortFields(1).


SortFields Collection Methods

The following methods are discussed in this section:

  • Add Method (SortFields Collection)
  • Delete Method (SortFields Collection)


Add Method (SortFields Collection)

The Add method adds a record or group sort field to the Collection.

Syntax

Sub Add (pFieldDefinition As IFieldDefinition, _

SortDirection As CRSortDirection)

Parameters

Parameter | Description
pFieldDefinition | A field definition object. Specifies the field definition or field name.
SortDirection | CRSortDirection. Specifies the direction in which the field data should be sorted (that is, ascending, descending, etc.).


Delete Method (SortFields Collection)

The Delete method deletes a record or group sort field from the Collection.

Syntax

Sub Delete (index As Long)

Parameter

Parameter | Description
index | Specifies the 1-based index number of the sort field in the collection that you want to delete.


SpecialVarFieldDefinition Object

The SpecialVarFieldDefinition object provides properties for retrieving information and setting options for a special field found in your report (for example, last modification date, print date). A SpecialVarFieldDefinition object is obtained from the Field property of the FieldMappingData Object.

SpecialVarFieldDefinition Object Properties

Property | Description | Read/Write | Restriction in event handler
Kind | CRFieldKind. Gets which kind of field (database, summary, formula, etc.). | Read only | None
Name | String. Gets the field definition unique formula name of the special var. field. | Read only | None
NextValue | Variant. Gets the field next value. | Read only | Can be read only when top-level Report object is formatting active.
NumberOfBytes | Integer. Gets the number of bytes required to store the field data in memory. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None
PreviousValue | Variant. Gets the field previous value. | Read only | Can be read only when top-level Report object is formatting active.
SpecialVarType | CRSpecialVarType. Gets what the type of special field (for example, ReportTitle, PageNumber). | Read only | None
Value | Variant. Gets the field current value. | Read only | Can be read only when top-level Report object is formatting active.
ValueType | CRFieldValueType. Gets which type of value is found in the field. | Read only | None


SQLExpressionFieldDefinition Object

The SQLExpressionFieldDefinition object represents a SQL expression field used in the report. This object provides properties for getting information on SQL expression fields in the report.

SQLExpressionFieldDefinition Object Properties

Property | Definition | Read/Write | Restriction in event handler
Kind | CRFieldKind. Gets which kind of field (that is, database, summary, formula, etc.). | Read only | None
Name | String. Gets the field definition unique formula name of the field within the report, Crystal formula syntax. | Read only | None
NextValue | Variant. Gets the field next value. | Read only | Can be read only when top-level Report object is formatting active.
NumberOfBytes | Integer. Gets the number of bytes required to store the field data in memory. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None
PreviousValue | Variant. Gets the field previous value. | Read only | Can be read only when top-level Report object is formatting active.
SQLExpressionFieldName | String. Gets the SQL expression field name. | Read only | None
Text | String. Gets or sets the SQL expression text. | Read/Write | Can be written only when formatting idle.
Value | Variant. Gets the field current value. | Read only | Can be read only when top-level Report object is formatting active.
ValueType | CRFieldValueType. Gets which type of value is found in the field. | Read only | None


SQLExpressionFieldDefinition Object Methods

The following method is discussed in this section:

  • Check Method (SQLExpressionFieldDefinition Object)


Check Method (SQLExpressionFieldDefinition Object)

Use Check method to check whether a SQL expression is valid.

Syntax

Sub Check (pBool As Boolean, ppErrorString As String)

Parameters

Parameter | Description
pBool | Boolean value indicating the condition of the formula string. Will be set to TRUE if the formula is valid and FALSE if the formula contains one or more errors.
ppErrorString | Specifies the error message string if the formula contains an error.


SQLExpressionFieldDefinitions Collection

The SQLExpressionFieldDefinitions Collection is a collection of SQL expression field definition objects. One object exists in the collection for every SQL expression field accessed by the report. Access a specific SQLExpressionFieldDefinition Object in the collection using the Item property.

SQLExpressionFieldDefinitions Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of items in the Collection. | Read only | None
Item (index As Long) | SQLExpressionFieldDefinition Object. Gets an item from the Collection. Item has an index parameter that is a 1-based index (that is, Item (1) for the first SQL Expression field in the collection). The items in the collection are indexed in the order they were added to the report. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None

Remarks

Instead of using the Item property as shown, you can reference a database directly, for example, SQLExpressionFieldDefinitions(1).


SQLExpressionFieldDefinitions Collection Methods

The following methods are discussed in this section:

  • Add Method (SQLExpressionFieldDefinitions Collection)
  • Delete Method (SQLExpressionFieldDefinitions Collection)
  • GetItemByName Method (SQLExpressionFieldDefinitions Collection)


Add Method (SQLExpressionFieldDefinitions Collection)

Use Add method to add a SQLExpressionFieldDefinition Object to the Collection.

Syntax

Function Add (SQLExpressionName As String, _

Text As String) As SQLExpressionFieldDefinition

Parameters

Parameter | Description
SQLExpressionName | Specifies the name of the SQL expression that you want to add to the Collection.
Text | Specifies the text of the SQL expression that you want to add to the Collection.

Returns

Returns a SQLExpressionFieldDefinition Object member of the Collection.


Delete Method (SQLExpressionFieldDefinitions Collection)

Use Delete method to remove a SQLExpressionFieldDefinition Object from the Collection.

Syntax

Sub Delete (index)

Parameter

Parameter | Description
index | Specifies the index number of the SQLExpressionFieldDefinition object that you want to remove from the Collection.


GetItemByName Method (SQLExpressionFieldDefinitions Collection)

Use GetItemByName method to retrieve an SQLExpressionFieldDefinition object by name.

Syntax

Sub GetItemByName(name As String, sqlExpressionFieldDefinition)

Parameters

Parameter | Description
name | The item's unique name.
sqlExpressionFieldDefinition | An SQLExpressionFieldDefinition object to hold the retrieved item.


SubreportLink Object

The SubreportLink object provides information about Subreport Links to the main report.

SubreportLink Object Properties

Property | Description | Read/Write | Restriction in event handler
MainReportField | A field definition object. Gets the main report field to which the subreport field is linked. See Remarks. | Read only | None
Parent | SubreportObject Object. Gets the subreport link's parent object. | Read only | None
SubReportField | A field definition object. Gets the subreport field. See Remarks. | Read only | None

Remarks

After getting the field definition object from the MainReportField or the SubReportField property, you can use the Kind property to determine what type of field definition object it is. All field definition objects have the Kind property.


SubreportLinks Collection

The SubreportLinks Collection contains the SubreportLink Object related to the report.

SubreportLinks Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets a count of the items in the Collection. | Read only | None
Item (index As Long) | SubreportLink Object. Gets an item from the Collection. | Read only | None
Parent | SubreportObject Object. Gets reference to the subreport link's parent object. | Read only | None


SubreportLinks Collection Methods

The following methods are discussed in this section:

  • Add Method (SubreportLinks Collection)
  • Delete Method (SubreportLinks Collection)


Add Method (SubreportLinks Collection)

Examples

Use Add method to add a SubreportLink Object to the Collection.

Syntax

Function Add (MainReportField, SubreportField) As SubreportLink

Parameters

Parameter | Description
MainReportField | Specifies the field in the main report that you want the new object in the Collection to link.
SubreportField | Specifies the field in the subreport that you want the new object in the Collection to link.

Returns

Returns a SubreportLink Object member of the Collection.


Delete Method (SubreportLinks Collection)

Use Delete method to remove a SubreportLink Object from the Collection.

Syntax

Sub Delete (index As Long)

Parameter

Parameter | Description
index | Specifies the index number of the object in the Collection that you want to remove.


SubreportObject Object

The SubreportObject object represents a subreport placed in a report. A subreport is a free-standing or linked report found within the main report. This object provides properties for retrieving information on the subreport (for example, name, formatting options).

SubreportObject Object Properties

Examples

Property | Description | Read/Write | Restriction in event handler
BackColor | OLE_COLOR. Gets or sets the object background color. | Read/Write | Can be written only when formatting idle or active.
BorderColor | OLE_COLOR. Gets or sets the object border color. | Read/Write | Can be written only when formatting idle or active.
BottomLineStyle | CRLineStyle. Gets or sets the bottom line style. | Read/Write | Can be written only when formatting idle or active.
CanGrow | Boolean. Gets or sets the can grow option. | Read/Write | Can be written only when formatting idle or active.
CloseAtPageBreak | Boolean. Gets or sets close border on page break. | Read/Write | Can be written only when formatting idle or active.
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
EnableOnDemand | Boolean. Gets the real-time subreport option. | Read only | None
HasDropShadow | Boolean. Gets or sets the border drop shadow option. | Read/Write | Can be written only when formatting idle or active.
Height | Long. Gets or sets the object height, in twips. | Read/Write | Can be written only when formatting idle or active.
KeepTogether | Boolean. Gets or sets the keep object together option. | Read/Write | Can be written only when formatting idle or active.
Kind | CRObjectKind. Gets what kind of object (for example, box, cross-tab, field). | Read only | None
Left | Long. Gets or sets the object upper left position, in twips. | Read/Write | Can be written only when formatting idle or active.
LeftLineStyle | CRLineStyle. Gets or sets the left line style. | Read/Write | Can be written only when formatting idle or active.
Links | Remarks. Gets reference to the Collection. | Read Only | None
Name | String. Gets or sets the object name. | Read/Write | Can be written only when formatting idle or active.
Parent | Section Object. Gets reference to the parent object. | Read only | None
RightLineStyle | CRLineStyle. Gets or sets the right line style. | Read/Write | Can be written only when formatting idle or active.
SubreportName | String. Gets or sets the name of the subreport. | Read/Write | Can be written only when formatting idle.
Suppress | Boolean. Gets or sets the object visibility option. | Read/Write | Can be written only when formatting idle or active.
Top | Long. Gets or sets the object upper top position, in twips. | Read/Write | Can be written only when formatting idle or active.
TopLineStyle | CRLineStyle. Gets or sets the top line style. | Read/Write | Can be written only when formatting idle or active.
Width | Long. Gets or sets the object width, in twips. | Read/Write | Can be written only when formatting idle or active.


SubreportObject Object Methods

The following methods are discussed in this section:

  • OpenSubreport Method (SubreportObject Object)
  • ReImportSubreport Method (SubreportObject Object)


OpenSubreport Method (SubreportObject Object)

Every subreport has a pointer to its parent report. Subreports hold on to their parent reports until they are destroyed. The OpenSubreport method opens a subreport contained in the report and returns a Report object corresponding to the named subreport. It corresponds to PEOpenSubreport of the Crystal Report Engine. This method can be invoked only in FormattingIdle or FormattingActive mode.

Syntax

Function OpenSubreport () As Report

Returns

Returns a SubreportObject Object.


ReImportSubreport Method (SubreportObject Object)

Examples

Subreports can be newly created in the main report or imported from an existing report file. If the subreport is imported from an existing report file, it can be re-imported at runtime using the ReImportSubreport method. When previewed, printed, or exported, a re-imported subreport will reflect all changes made to the formatting, grouping, and structure of the existing report file.

Syntax

Sub ReImportSubreport (pReimported as Boolean)

Parameter

Parameter | Description
pReimported | Boolean value indicating success or failure when re-importing the subreport. Will be set to TRUE if re-importing the subreport succeeds and FALSE if re-importing the subreport fails. See remarks below.

Remarks

pReimported is an output parameter. Create a variable to hold the result of pReimported and check the value of the variable to see if the method is successful.


SummaryFieldDefinition Object

The SummaryFieldDefinition object represents the summary used in a cross-tab, group, or report.

SummaryFieldDefinition Object Properties

Property | Description | Read/Write | Restriction in event handler
FooterArea | Area Object. Gets the area pair that the summary is in. | Read only | None
ForCrossTab | Boolean. Gets for-cross-tab. | Read only | None
HeaderArea | Area Object. Gets the area pair that the summary is in. | Read only | None
HierarchicalSummaryType | CRHierarchicalSummaryType. Gets or sets whether or not to calculate the summary across the hierarchy in a hierarchically grouped report. | Read/Write | Can be written only when formatting idle.
Kind | CRFieldKind. Gets which kind of field (database, summary, formula, etc.). | Read only | None
Name | String. Gets the field definition unique formula name of the summary field for a group or report summary field. Cross-tab summaries do not have a unique name so an empty string will be returned. | Read only | None
NextValue | Variant. Gets the field next value. | Read only | Can be read only when top-level Report object is formatting.
NumberOfBytes | Integer. Gets the number of bytes required to store the field data in memory. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None
PreviousValue | Variant. Gets the field previous value. | Read only | Can be read only when top-level Report object is formatting.
SecondarySummarizedField | Object. Gets the secondary summarized field. | Read only | None
SummarizedField | Object. Gets the summarized field. | Read only | None
SummaryOperationParameter | Long. Gets or sets the summary operation parameter. | Read/Write | Can be written only when formatting idle.
SummaryType | CRSummaryType. Gets or sets the type of summary (for example, sum, average). | Read/Write | Can be written only when formatting idle.
Value | Variant. Gets the field current value. | Read only | Can be read only when top-level Report object is formatting active.
ValueType | CRFieldValueType. Gets which type of value is found in the field. | Read only | None


SummaryFieldDefinition Object Methods

The following methods are discussed in this section:

  • SetSecondarySummarizedField Method (SummaryFieldDefinition Object)
  • SetSummarizedField Method (SummaryFieldDefinition Object)


SetSecondarySummarizedField Method (SummaryFieldDefinition Object)

Use SetSecondarySummarizedField method to set the secondary summarized field for a report.

Syntax

Sub SetSecondarySummarizedField (secondarySummariedField)

Parameter

Parameter | Description
secondarySummariedField | Specifies the field that you want to set.


SetSummarizedField Method (SummaryFieldDefinition Object)

Syntax

Sub SetSummarizedField (SummarizedField)

Parameter

Parameter | Description
SummarizedField | Specifies the field that you want to set.


SummaryFieldDefinitions Collection

The SummaryFieldDefinitions Collection is a collection of summary field definitions. Can be from either CrossTabObject object or Report object. Access a specific SummaryFieldDefinition object in the collection using the Item property.

SummaryFieldDefinitions Collection Properties

Property | Description | Read/Write | Restriction in event handler
Count | Long. Gets the number of summary fields in the collection. | Read only | None
Item (index As Long) | SummaryFieldDefinition Object. Gets an item from the Collection. Item has an index parameter that is a numeric, 1-based index (for example, Item (1)). The items in the collection are indexed in the order they were added to the report. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None

Remarks

Instead of using the Item property as shown, you can reference a summary field directly, for example, SummaryFieldDefinitions(1).


SummaryFieldDefinitions Collection Methods

The following methods are discussed in this section:

  • Add Method (SummaryFieldDefinitions Collection)
  • Delete Method (SummaryFieldDefinitions Collection)


Add Method (SummaryFieldDefinitions Collection)

Use Add method to add a SummaryFieldDefinition Object to the Collection.

Syntax

Function Add (groupLevel As Long, Field, _

SummaryType As CRSummaryType, [secondSummaryFieldOrFactor] _

) As SummaryFieldDefinition

Parameters

Parameter | Description
groupLevel | Specifies the group level for the summary.
Field | Specifies the summary field.
SummaryType | CRSummaryType. Specifies the summary type.
[secondSummaryFieldOrFactor] | Specifies the second summary field or factor.

Returns

Returns a SummaryFieldDefinition Object member of the Collection.


Delete Method (SummaryFieldDefinitions Collection)

Use delete method to delete a SummaryFieldDefinition Object from the Collection.

Syntax

Sub Delete (index)

Parameter

Parameter | Description
index | Specifies the index number of the object that you want to delete from the Collection.


TableLink Object

The TableLink object provides information about database table links.

TableLink Object Properties

Examples

Property | Description | Read/Write | Restriction in event handler
DestinationFields | DatabaseFieldDefinition Object. Gets reference to table link destination field definitions Collection. | Read only | None
DestinationTable | DatabaseTable Object. Gets reference to the table link destination table. | Read only | None
JoinType | CRLinkJoinType. Gets the table link join type. | Read only | None
LookupType | CRLinkLookUpType. Gets table link lookup type. | Read only | None
Parent | Database Object. Gets reference to the parent object. | Read only | None
SourceFields | DatabaseFieldDefinition Object. Gets the table link source field definitions. | Read only | None
SourceTable | DatabaseTable Object. Gets table link source table. | Read only | None


TableLinks Collection

The TableLinks Collection contains the TableLink Object objects associated with the report.

TableLinks Collection Properties

Property | Definition | Read/Write | Restriction in event handler
Count | Long. Gets a count of the collection items. | Read only | None
Item (index As Long) | TableLink Object. Gets an item from the Collection. | Read only | None
Parent | Database Object. Gets reference to the parent object. | Read only | None


TableLinks Collection Methods

The following methods are discussed in this section:

  • Add Method (TableLinks Collection)
  • Delete Method (TableLinks Collection)


Add Method (TableLinks Collection)

Examples

Use Add method to add a TableLink Object to the Collection.

Syntax

Function Add (psrcTable As DatabaseTable, pDestTable As DatabaseTable, _

srcFields, destFields, _

JoinType As CRLinkJoinType, LookupType As CRLinkLookUpType, _

PartialMatchEnabled As Boolean, indexInUse As Integer) As TableLink

Parameters

Parameter | Description
psrcTable | DatabaseTable Object. Specifies the source database table.
pDestTable | DatabaseTable Object. Specifies the destination database table.
srcFields | Specifies the source fields.
destFields | Specifies th destination fields.
JoinType | CRLinkJoinType. Specifies the link join type.
LookupType | CRLinkLookUpType. Specifies the link lookup type.
PartialMatchEnabled | Specifies whether the PartialMatchEnabled option has been set.
indexInUse | Specifies index in use.

Returns

Returns a TableLink Object member of the Collection.


Delete Method (TableLinks Collection)

Examples

Use Delete method to remove a TableLink Object from the Collection.

Syntax

Sub Delete (index As Long)

Parameter

Parameter | Description
index | Specifies the index number of the item that you want to remove from the Collection.


TextObject Object

The Text object represents a text object found in a report. This object provides properties for retrieving information and setting options for a text object in your report.

TextObject Object Properties

Examples

Property | Description | Read/Write | Restriction in event handler
BackColor | OLE_COLOR. Gets or sets the object background color. | Read/Write | Can be written only when formatting idle or active.
BorderColor | OLE_COLOR. Gets or sets the object border color. | Read/Write | Can be written only when formatting idle or active.
BottomLineStyle | CRLineStyle. Gets or sets the bottom line style. | Read/Write | Can be written only when formatting idle or active.
CanGrow | Boolean. Gets or sets the can grow option. | Read/Write | Can be written only when formatting idle or active.
CharacterSpacing | Long. Gets or sets the character spacing. | Read/Write | Can be written only when formatting idle.
CloseAtPageBreak | Boolean. Gets or sets th close border on page break option. | Read/Write | Can be written only when formatting idle or active.
ConditionFormula | String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables. | Read/Write | Can be written only when formatting idle.
CssClass | String. Gets or sets the cascading style sheet Class. | Read/Write | Can be written only when formatting idle.
FieldElements | SetUnboundFieldSource Method (FieldObject Object). Gets the field elements Collection. | Read Only | None
FirstLineIndent | Long. Gets or sets first line indent, in twips. | Read/Write | Can be written only when formatting idle.
Font | IFontDisp. Gets or sets the standard OLE font of the text object. | Read/Write | Can be written only when formatting idle or active.
HasDropShadow | Boolean. Gets or sets the border drop shadow option. | Read/Write | Can be written only when formatting idle or active.
Height | Long. Gets or sets the object height, in twips. | Read/Write | Can be written only when formatting idle or active.
HorAlignment | CRAlignment. Gets or sets the horizontal alignment. | Read/Write | Can be written only when formatting idle or active.
KeepTogether | Boolean. Gets or sets the keep area together option. | Read/Write | Can be written only when formatting idle or active.
Kind | CRObjectKind. Gets what kind of object (for example, box, cross-tab, field). | Read only | None
Left | Long. Gets or sets the object upper left position, in twips. | Read/Write | Can be written only when formatting idle or active.
LeftIndent | Long. Gets or sets left indent, in twips. | Read/Write | Can be written only when formatting idle.
LeftLineStyle | CRLineStyle. Gets or sets the left line style. | Read/Write | Can be written only when formatting idle or active.
LineSpacing | Double. Gets the line spacing. | Read only | Can be written only when formattin idle.
LineSpacingType | CRLineSpacingType. Gets the line spacing type. | Read only |
MaxNumberOfLines | Integer. Gets or sets the maximum number of line for a string memo field. | Read/Write | Can be written only when formatting idle or active.
Name | String. Gets or sets area name. | Read/Write | Can be written only when formatting idle.
Parent | Section Object. Gets reference to the parent object. | Read only | None
RightIndent | Long. Gets or sets the right indent. | Read/Write | Can be written only when formatting idle.
RightLineStyle | CRLineStyle. Gets or sets the right line style. | Read/Write | Can be written only when formatting idle or active.
Suppress | Boolean. Gets or sets object visibility. | Read/Write | Can be written only when formatting idle or active.
SuppressIfDuplicated | Boolean. Gets or sets the suppress if duplicated option. | Read/Write | Can be written only when formatting idle or active.
Text | String. Gets the text within the text object. If it has embedded fields, [] is used to represent the embedded field. | Read only | None
TextColor | OLE_COLOR. Gets or sets the object text color. | Read/Write | Can be written only when formatting idle or active.
TextRotationAngle | CRRotationAngle. Gets or sets text rotation angle. | Read/Write | Can be written only when formatting idle or active.
Top | Long. Gets or sets the object upper top position, in twips. | Read/Write | Can be written only when formatting idle or active.
TopLineStyle | CRLineStyle. Gets or sets the top line style. | Read/Write | Can be written only when formatting idle or active.
Width | Long. Gets or sets the object width, in twips. | Read/Write | Can be written only when formatting idle or active.


TextObject Object Methods

The following methods are discussed in this section:

  • SetLineSpacing Method (TextObject Object)
  • SetText Method (TextObject Object)


SetLineSpacing Method (TextObject Object)

Use the SetLineSpacing method to set the line spacing for a TextObject Object. The information passed will be used during formatting.

Syntax

Sub SetLineSpacing (LineSpacing As Double, _

LineSpacingType As CRLineSpacingType)

Parameters

Parameter | Description
LineSpacing | Specifies the line spacing.
LineSpacingType | CRLineSpacingType. Specifies the line spacing type.


SetText Method (TextObject Object)

Use the SetText method to set the text object to return the specified text. This method can be invoked only in the FormattingIdle or FormattingActive mode.

Syntax

Sub SetText (pText As String)

Parameter

Parameter | Description
pText | Specifies the text string for the object. See Remarks below.

Remarks

When the SetText method is called within the sections Format event handler, the text parameter passed should not be dependent upon some state that the event handler may be tracking. For example, the event handler may hold a count and increment it each time the Format event is fired. This could should not be used directly or indirectly to create the SetText text parameter.


Examples

The following examples assume the developer is already familiar with using the RDC in Visual Basic and how to create reports. Unless noted otherwise most reports are created in the Visual Basic IDE and are named CrystalReport1. Each example gives a brief description on how the report or reports are created including tables used, grouping, charts and so on. If you need help in creating a report see the Crystal Reports Online Help (crw.chm). If you need help with using the RDC see Quick Start for using the RDC and RDC Programming.

Click the appropriate link to jump to that section.

  • How to connect to a Microsoft Access database
  • How to connect to a secured Microsoft Access database
  • How to connect to an ODBC data source
  • How to connect to an OLEDB data source
  • How to change the data source
  • How to list the connection properties and connect to a report
  • How to format a blob field object
  • How to format a box object
  • How to format a graph object (chart)
  • How to format a map object
  • How to format an olap grid object
  • How to format an OLE object
  • How to format a subreport object
  • How to format a text object
  • How to import a subreport and link to a main report
  • How to re-import a subreport and link to a main report
  • How to add and delete table links
  • How to add, delete and format groups in a crosstab
  • How to format a group in the section format event


How to connect to a Microsoft Access database

This example demonstrates three methods for changing the location of an Access database. In each example CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table. A copy of xtreme.mdb is placed in a new directory, and a copy of the Customer table (NewCustomer) is added to xtreme.mdb.

Example 1

This example uses the Location property of the DatabaseTable Object, to change the location of the database.

' Create a new instance of the report.

Dim Report As New CrystalReport1

Private Sub Form_Load()

' Declare a DatabaseTable object.

Dim DBTable As CRAXDRT.DatabaseTable

' Get the first table in the report.

Set DBTable = Report.Database.Tables(1)

' Set the new location of the database.

DBTable.Location = "C:\databases\xtreme.mdb"

Screen.MousePointer = vbHourglass

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = Report

CRViewer1.ViewReport

Screen.MousePointer = vbDefault

End Sub

Example 2

This example uses the Location property of the ConnectionProperty Object to change the location of the database.

' Create a new instance of the report.

Dim Report As New CrystalReport1

Private Sub Form_Load()

' Declare a ConnectionProperty object.

Dim CPProperty As CRAXDRT.ConnectionProperty

' Declare a DatabaseTable object.

Dim DBTable As CRAXDRT.DatabaseTable

' Get the first table in the report.

Set DBTable = Report.Database.Tables(1)

' Get the "Database Name" property from the

' ConnectionProperties collection.

Set CPProperty = DBTable.ConnectionProperties("Database Name")

' Set the new location of the database.

CPProperty.Value = "C:\databases\xtreme.mdb"

Screen.MousePointer = vbHourglass

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = Report

CRViewer1.ViewReport

Screen.MousePointer = vbDefault

End Sub

Example 3

This example uses the SetTableLocation Method (DatabaseTable Object) to change the location of the database and the name of the table.

' Create a new instance of the report.

Dim Report As New CrystalReport1

Private Sub Form_Load()

' Declare a DatabaseTable object.

Dim DBTable As CRAXDRT.DatabaseTable

' Get the first table in the report.

Set DBTable = Report.Database.Tables(1)

' Set the new database location and the new table name.

DBTable.SetTableLocation "C:\databases\xtreme.mdb", NewCustomer, ""

Screen.MousePointer = vbHourglass

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = Report

CRViewer1.ViewReport

Screen.MousePointer = vbDefault

End Sub


How to connect to a secured Microsoft Access database

This example demonstrates three methods for changing the location of an Access database and setting the password to the database. In each example CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table. A copy of xtreme.mdb is placed in a new directory, and a copy of the Customer table (NewCustomer) is added to xtreme.mdb. A password is added to the database to make it a secured Access database.

Example 1

This example uses the Location property of the DatabaseTable Object to change the location of the database, and the ConnectionProperty Object to set the password.

' Create a new instance of the report.

Dim Report As New CrystalReport1

Private Sub Form_Load()

' Declare a ConnectionProperty object.

Dim CPProperty As CRAXDRT.ConnectionProperty

' Declare a DatabaseTable object.

Dim DBTable As CRAXDRT.DatabaseTable

' Get the first table in the report.

Set DBTable = Report.Database.Tables(1)

' Set the new location of the database.

DBTable.Location = "C:\databases\xtreme.mdb"

' Get the "Database Password" property from the

' ConnectionProperties collection.

Set CPProperty = DBTable.ConnectionProperties("Database Password")

' Set the database password.

CPProperty.Value = "password"

Screen.MousePointer = vbHourglass

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = Report

CRViewer1.ViewReport

Screen.MousePointer = vbDefault

End Sub

Example 2

This example uses the ConnectionProperty Object to change the location of the database and to set the password.

' Create a new instance of the report.

Dim Report As New CrystalReport1

Private Sub Form_Load()

' Declare a ConnectionProperty object.

Dim CPProperty As CRAXDRT.ConnectionProperty

' Declare a DatabaseTable object.

Dim DBTable As CRAXDRT.DatabaseTable

' Get the first table in the report.

Set DBTable = Report.Database.Tables(1)

' Get the "Database Name" property from the

' ConnectionProperties collection.

Set CPProperty = DBTable.ConnectionProperties("Database Name")

' Set the new location of the database.

CPProperty.Value = "C:\databases\xtreme.mdb"

' Get the "Database Password" property from the

' ConnectionProperties collection.

Set CPProperty = DBTable.ConnectionProperties("Database Password")

' Set the database password.

CPProperty.Value = "password"

Screen.MousePointer = vbHourglass

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = Report

CRViewer1.ViewReport

Screen.MousePointer = vbDefault

End Sub

Example 3

This example uses the SetTableLocation Method (DatabaseTable Object) to change the location of the database and the name of the table, and the ConnectionProperty Object to set the password.

' Create a new instance of the report.

Dim Report As New CrystalReport1

Private Sub Form_Load()

' Declare a ConnectionProperty object.

Dim CPProperty As CRAXDRT.ConnectionProperty

' Declare a DatabaseTable object.

Dim DBTable As CRAXDRT.DatabaseTable

' Get the first table in the report.

Set DBTable = Report.Database.Tables(1)

' Set the new database location and the new table name.

DBTable.SetTableLocation "C:\databases\xtreme.mdb", NewCustomer, ""

' Get the "Database Password" property from the

' ConnectionProperties collection.

Set CPProperty = DBTable.ConnectionProperties("Database Password")

' Set the database password.

CPProperty.Value = "password"

Screen.MousePointer = vbHourglass

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = Report

CRViewer1.ViewReport

Screen.MousePointer = vbDefault

End Sub


How to connect to an ODBC data source

This example demonstrates how to connect to an ODBC data source by using the ConnectionProperty Object, and how to change the table name by using the Location property of the DatabaseTable Object. CrystalReport1 is created using an ODBC data source connected to the pubs database on Microsoft SQL Server. The report is based off the authors table.

' Create a new instance of the report.

Dim Report As New CrystalReport1

Private Sub Form_Load()

' Declare a ConnectionProperty object.

Dim CPProperty As CRAXDRT.ConnectionProperty

' Declare a DatabaseTable object.

Dim DBTable As CRAXDRT.DatabaseTable

' Get the first table in the report.

Set DBTable = Report.Database.Tables(1)

' Get the "DSN" property from the

' ConnectionProperties collection.

Set CPProperty = DBTable.ConnectionProperties("DSN")

' Set the ODBC data source name.

' Note: You do not need to set this property if

' you are using the same ODBC data source.

CPProperty.Value = "ODBCSQL"

' Get the "User ID" property from the

' ConnectionProperties collection.

Set CPProperty = DBTable.ConnectionProperties("User ID")

' Set the user name.

' Note: You do not need to set this property if

' you are using the same user name.

CPProperty.Value = "username"

' Get the "Password" property from the

' ConnectionProperties collection.

' Note: You must always set the password if one is

' required.

Set CPProperty = DBTable.ConnectionProperties("Password")

' Set the password.

CPProperty.Value = "password"

' Get the "Database" property from the

' ConnectionProperties collection.

Set CPProperty = DBTable.ConnectionProperties("Database")

' Set the database.

CPProperty.Value = "master"

' Set the table name.

DBTable.Location = "authors2"

Screen.MousePointer = vbHourglass

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = Report

CRViewer1.ViewReport

Screen.MousePointer = vbDefault

End Sub


How to connect to an OLEDB data source

This example demonstrates how to connect to an OLEDB (ADO) data source, change the data source, and change the database by using the ConnectionProperty Object, as well as how to change the table name by using the Location property of the DatabaseTable Object. CrystalReport1 is created using an ODBC data source connected to the pubs database on Microsoft SQL Server. The report is based off the authors table.

' Create a new instance of the report.

Dim Report As New CrystalReport1

Private Sub Form_Load()

' Declare a ConnectionProperty object.

Dim CPProperty As CRAXDRT.ConnectionProperty

' Declare a DatabaseTable object.

Dim DBTable As CRAXDRT.DatabaseTable

' Get the first table in the report.

Set DBTable = Report.Database.Tables(1)

' Get the "Data Source" property from the

' ConnectionProperties collection.

Set CPProperty = DBTable.ConnectionProperties("Data Source")

' Set the new data source (server name).

' Note: You do not need to set this property if

' you are using the same data source.

CPProperty.Value = "Server2"

' Get the "User ID" property from the

' ConnectionProperties collection.

Set CPProperty = DBTable.ConnectionProperties("User ID")

' Set the user name.

' Note: You do not need to set this property if

' you are using the same user name.

CPProperty.Value = "UserName"

' Get the "Password" property from the

' ConnectionProperties collection.

Set CPProperty = DBTable.ConnectionProperties("Password")

' Set the password.

' Note: You must always set the password if one is

' required.

CPProperty.Value = "Password"

' Get the "Initial Catalog" (database name) property from the

' ConnectionProperties collection.

' Note: You do not need to set this property if

' you are using the same database.

Set CPProperty = DBTable.ConnectionProperties("Initial Catalog")

' Set the new database name.

CPProperty.Value = "master"

' Set the new table name.

DBTable.Location = "authors2"

Screen.MousePointer = vbHourglass

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = Report

CRViewer1.ViewReport

Screen.MousePointer = vbDefault

End Sub


How to change the data source

This example demonstrates how to change the data source from native Access to an OLEDB (ADO) data source by using the ConnectionProperty Object, as well as how to change the table name by using the Location property of the DatabaseTable Object. CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table. A copy of the Customer table is added to the pubs database on Microsoft SQL Server.

' Create a new instance of the report.

Dim Report As New CrystalReport1

Private Sub Form_Load()

' Declare a ConnectionProperties collection.

Dim CPProperties As CRAXDRT.ConnectionProperties

' Declare a DatabaseTable object.

Dim DBTable As CRAXDRT.DatabaseTable

' Get the first table in the report.

Set DBTable = Report.Database.Tables(1)

' Get the collection of connection properties.

Set CPProperties = DBTable.ConnectionProperties

' Change the database DLL used by the report from

' native Access (crdb_dao.dll) to ADO/OLEDB (crdb_ado.dll).

DBTable.DllName = "crdb_ado.dll"

' The connection property bags contain the name and value

' pairs for the native Access DLL (crdb_dao.dll). So we need

' to clear them, and then add the name and value pairs that

' are required to connect to the OLEDB data source.

' Clear all the ConnectioProperty objects from the collection.

CPProperties.DeleteAll

' Add the name value pair for the provider.

CPProperties.Add "Provider", "SQLOLEDB"

' Add the name value pair for the data source (server).

CPProperties.Add "Data Source", "ServerA"

' Add the name value pair for the database.

CPProperties.Add "Initial Catalog", "pubs"

' Add the name value pair for the user name.

CPProperties.Add "User ID", "UserName"

' Add the name value pair for the password.

CPProperties.Add "Password", "password"

' Set the table name.

DBTable.Location = "Customer"

Screen.MousePointer = vbHourglass

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = Report

CRViewer1.ViewReport

Screen.MousePointer = vbDefault

End Sub


How to list the connection properties and connect to a report

This example demonstrates how to list the connection property information by using the ConnectionProperty Object. The user can then set the values for the connection properties and display the report. The example consists of two forms and a report designed in the Visual Basic IDE using the RDC. The first form allows the user to view and set the connection properties. The second form displays the report.

To use the example
  1. Create a standard application and add an additional form.
  2. Create or import a report using the RDC.
  3. Add the following controls to Form1:
    • Combo List Box (Combo1)

      • In the property window set Style to "2 - Dropdown List".

      Combo1 holds the list of connection property names.

    • Combo List Box (Combo2)

      • In the property window set Style to "1 - Simple Combo".

      Combo2 holds the list of connection property values.

    • Button (Command1)

      • Command1 sets the connection property values.

    • Button (Command2)

      • Command2 hides this form and loads the second form.

  4. Cut and paste the code that is listed under Form1 below into the code window for Form1 in your application.
  5. Add the following controls to Form2:
    • Crystal Reports Viewer Control (CRViewer1)
  6. Cut and paste the code that is listed under Form2 below into the code window for Form2 in your application.
  7. Run the application.
  8. With the application running the user can:
    • Select the connection property from Combo1.
    • Change the value in the Combo2.
    • Click Command1 to save the changes to the value.
    • Click Command2 to display the report in Form 2.
The first form (Form1)

This is the start up form and displays the name and value pairs for each connection property.

' Create a new instance of the report.

Public Report As New CrystalReport1

' Declare a ConnectionProperty object.

Dim CPProperty As CRAXDRT.ConnectionProperty

' Declare a DatabaseTable object.

Dim DBTable As CRAXDRT.DatabaseTable

' When an item in the ComboBox1(connection property name)

' is selected the corresponding item in ComboBox2

' (connection property value) is displayed.

Private Sub Combo1_Click()

Combo2.ListIndex = Combo1.ListIndex

End Sub

'Clicking this button sets the connection property

' value.

Private Sub Command1_Click()

' This variable holds the new value for the selected

' connection property.

Dim NewValue As String

' Get the selected connection property.

Set CPProperty = DBTable.ConnectionProperties(Combo1.Text)

' Get and set the new value for the connection property.

NewValue = Combo2.Text

CPProperty.Value = NewValue

' Update the combo box with the new value.

Combo2.RemoveItem Combo1.ListIndex

Combo2.AddItem NewValue, Combo1.ListIndex

End Sub

' Clicking this button displays the report

' and hides this form.

Private Sub Command2_Click()

Form2.Show

Form1.Hide

End Sub

Private Sub Form_Load()

' Get the first table in the report.

Set DBTable = Report.Database.Tables(1)

' Create a list of value and name pairs for each

' connection property in the collection.

For Each CPProperty In DBTable.ConnectionProperties

' Add the name of the connection property to the

' first combo box.

Combo1.AddItem CPProperty.Name

' Add the value of the connection property to the

' second combo box. Password is a write only

' property so set it to an empty string.

If InStr(1, CPProperty.Name, "Password", 1) > 0 Then

Combo2.AddItem ""

Else

Combo2.AddItem CPProperty.Value

End If

Next CPProperty

' Set both combo boxes to the first item.

Combo1.ListIndex = 0

Combo2.ListIndex = 0

End Sub

Private Sub Form_Unload(Cancel As Integer)

' Destroy the Report object.

Set Report = Nothing

End Sub

The second form (Form2)

This form displays the report set in Form1.

Private Sub Form_Load()

Screen.MousePointer = vbHourglass

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = Form1.Report

CRViewer1.ViewReport

Screen.MousePointer = vbDefault

End Sub

Private Sub Form_Resize()

' Resize the viewer to fit the form.

CRViewer1.Top = 0

CRViewer1.Left = 0

CRViewer1.Height = ScaleHeight

CRViewer1.Width = ScaleWidth

End Sub

Private Sub Form_Unload(Cancel As Integer)

' Show Form1.

Form1.Show

End Sub


How to format a blob field object

This example gets a blob field object and then formats the blob field object through the BlobFieldObject Object properties. CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Employees table and the Photo field is added to the details section.

' Create a new instance of the report.

Dim oReport As New CrystalReport1

Private Sub Form_Load()

' Declare an BlobFieldObject object.

Dim oBlobfield As CRAXDRT.BlobFieldObject

' Declare a generic Object.

Dim oObject As Object

' Declare a Section object.

Dim oSection As CRAXDRT.Section

' This variable is set to true once the

' blob field object is found.

Dim bBlob As Boolean

bBlob = False

' Search for all the report objects in each section.

For Each oSection In oReport.Sections

For Each oObject In oSection.ReportObjects

' Find the first blob field object.

If oObject.Kind = crBlobFieldObject Then

' Get the blob field object and exit the loop.

Set oBlobfield = oObject

bBlob = True

Exit For

End If

Next oObject

If bBlob Then Exit For

Next oSection

' Format the blobfield object.

With oBlobfield

.BackColor = vbBlue

.BorderColor = vbGreen

.BottomCropping = 250

.TopCropping = 250

.LeftCropping = 250

.RightCropping = 250

.BottomLineStyle = crLSDoubleLine

.TopLineStyle = crLSDashLine

.LeftLineStyle = crLSSingleLine

.RightLineStyle = crLSDotLine

.HasDropShadow = True

.CloseAtPageBreak = True

.KeepTogether = False

.Height = 2000

.Width = 2000

.Top = 5000

.Left = 1000

.Suppress = False

' X and Y scaling gets or sets width scaling factor.

' For example 1 means 100%, 2 means 200%, 0.5 means 50%,

' and so on. The allowable range is from 0.01 to 100.

' This will change the actual height and width of the object.

.XScaling = 2

.YScaling = 2

End With

' Set the report source of the viewer and view the report.

CRViewer91.ReportSource = oReport

CRViewer91.ViewReport

End Sub


How to format a box object

This example gets a box object and then formats the box object through the BoxObject Object properties. CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table and a box is inserted into the report.

' Create a new instance of the report.

Dim oReport As New CrystalReport1

Private Sub Form_Load()

' Declare an BoxObject object.

Dim oBox As CRAXDRT.BoxObject

' Declare a generic Object.

Dim oObject As Object

' Declare a Section object.

Dim oSection As CRAXDRT.Section

' This variable is set to true once the box object is found.

Dim bBox As Boolean

bBox = False

' Search for all the report objects in each section.

For Each oSection In oReport.Sections

For Each oObject In oSection.ReportObjects

' Find the first box object.

If oObject.Kind = crBoxObject Then

' Get the box object and exit the loop.

Set oBox = oObject

bBox = True

Exit For

End If

Next oObject

If bBox Then Exit For

Next oSection

' Format the box object.

With oBox

.Bottom = 250

' BottomRightSection refers to the report section

' containing the bottom right corner

' of this box object.

.BottomRightSection.BackColor = vbCyan

.CloseAtPageBreak = True

.CornerEllipseHeight = 500

.CornerEllipseWidth = 500

.ExtendToBottomOfSection = True

.FillColor = vbMagenta

' DropShadow cannot be set to True for a

' rounded corner box object.

.HasDropShadow = False

.Left = 250

.LineColor = vbBlue

.LineStyle = crLSDotLine

.Right = 7400

.Suppress = False

.Top = 100

End With

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = oReport

CRViewer1.ViewReport

End Sub


How to format a graph object (chart)

This example gets a graph object and then formats the graph object through the GraphObject Object properties. CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table and a chart is inserted into the report. See "Creating Charts" in the Crystal Reports Online Help (crw.chm)

' Create a new instance of the report.

Dim oReport As New CrystalReport1

Private Sub Form_Load()

' Declare an GraphObject object.

Dim oGraph As CRAXDRT.GraphObject

' Declare a generic Object.

Dim oObject As Object

' Declare a Section object.

Dim oSection As CRAXDRT.Section

' This variable is set to true once the graph object is found.

Dim bGraph As Boolean

bGraph = False

' Search for all the report objects in each section.

For Each oSection In oReport.Sections

For Each oObject In oSection.ReportObjects

' Find the first graph object.

If oObject.Kind = crGraphObject Then

' Get the graph object and exit the loop.

Set oGraph = oObject

bGraph = True

Exit For

End If

Next oObject

If bGraph Then Exit For

Next oSection

' Format the graph object.

With oGraph

.AutoRangeData2Axis = True

.AutoRangeDataAxis = True

.BackColor = vbYellow

.BarSize = crAverageBarSize

.BorderColor = vbRed

.BottomLineStyle = crLSDashLine

.CloseAtPageBreak = True

.Data2AxisDivisionMethod = crAutomaticDivision

.Data2AxisGridline = crMajorAndMinorGridlines

.Data2AxisNumberFormat = crCurrencyTwoDecimal

.Data2LabelFont.Bold = True

.Data2Title = "Not In Use"

.Data2TitleFont.Bold = False

.DataAxisDivisionMethod = crAutomaticDivision

.DataAxisGridline = crMajorAndMinorGridlines

.DataAxisNumberFormat = crCurrencyThousands

.DataLabelFont.Underline = True

.DataPoint = crShowValue

.DataTitle = "DataTitle"

.DataTitleFont.Italic = True

.DataValueNumberFormat = crCurrencyNoDecimal

.EnableAutoScaleData2Axis = True

.EnableAutoScaleDataAxis = True

.EnableShowLegend = True

.FootNote = "FootNote"

.FootnoteFont.Size = 14

.GraphColor = crColorGraph

.GraphDirection = crHorizontalGraph

.GraphType = crFaked3DStackedBarGraph

.GroupAxisGridline = crMajorAndMinorGridlines

.GroupLabelFont.Size = 8

.GroupsTitle = "GroupsTitle"

.GroupTitleFont.Weight = 999

.HasDropShadow = True

.IsData2TitleByDefault = True

.IsDataTitleByDefault = True

.IsFootnoteByDefault = False

.IsGroupsTitleByDefault = False

.IsSeriesTitleByDefault = False

.IsSubTitleByDefault = False

.IsTitleByDefault = True

.KeepTogether = True

.Left = 200

.LeftLineStyle = crLSDoubleLine

.LegendFont.Italic = True

.LegendLayout = crBothLayout

.LegendPosition = crPlaceLeft

.MarkerShape = crTriangleShape

.MaxData2AxisValue = 999999

.MaxDataAxisValue = 999999

.MinData2AxisValue = -999999

.MinDataAxisValue = -999999

.Name = "ThisIsGraph"

.PieSize = crLargePieSize

.RightLineStyle = crLSDotLine

.SeriesAxisGridline = crMajorAndMinorGridlines

.SeriesLabelFont.Strikethrough = True

.SeriesTitle = "SeriesTitle"

.SeriesTitleFont.Underline = True

.SliceDetachment = crSmallestSlice

.SubTitle = "SubTitle"

.SubTitleFont.Italic = True

.Suppress = False

.Title = "Title"

.TitleFont.Size = 18

.Top = 1100

.TopLineStyle = crLSDotLine

.ViewingAngle = crFewSeriesView

.Width = 9000

End With

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = oReport

CRViewer1.ViewReport

End Sub


How to format a map object

This example gets a map object then formats the map object through the MapObject Object properties. Create a report in the Crystal Report Designer using the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. Add a map to the report and then import the report into a Visual Basic application. For maps see "Creating Maps" in the Crystal Reports Online Help (crw.chm) and for importing reports see Open an existing report.

' Create a new instance of the report.

Dim oReport As New CrystalReport1

Private Sub Form_Load()

' Declare an MapObject object.

Dim oMap As CRAXDRT.MapObject

' Declare a generic Object.

Dim oObject As Object

' Declare a Section object.

Dim oSection As CRAXDRT.Section

' This variable is set to true once the map object is found.

Dim bMap As Boolean

bMap = False

' Search for all the report objects in each section.

For Each oSection In oReport.Sections

For Each oObject In oSection.ReportObjects

' Find the first map object.

If oObject.Kind = crMapObject Then

' Get the map object and exit the loop.

Set oMap = oObject

bMap = True

Exit For

End If

Next oObject

If bMap Then Exit For

Next oSection

' Format the map object.

With oMapObject

.BackColor = vbGreen

.BorderColor = vbRed

.BottomLineStyle = crLSDoubleLine

.CloseAtPageBreak = True

.HasDropShadow = True

.Height = 5000

.KeepTogether = True

.Left = 750

.LeftLineStyle = crLSDashLine

.RightLineStyle = crLSDotLine

.Suppress = False

.Top = 100

.TopLineStyle = crLSSingleLine

.Width = 10000

End With

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = oReport

CRViewer1.ViewReport

End Sub


How to format an olap grid object

This example gets an olap grid object in the report header and then formats the olap grid object through the OlapGridObject Object properties. Import the OLAP Cube Report.rpt in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Reports\Feature Examples folder into a Visual Basic application. See Open an existing report for information on importing reports.

' Create a new instance of the report.

Dim oReport As New CrystalReport1

Private Sub Form_Load()

' Declare an OlapGridObject object.

Dim OlapGrd As CRAXDRT.OlapGridObject

' get the OlapGridObject object from the report header.

Set OlapGrd = oReport.Sections("RH").ReportObjects(1)

' Format the olap grid object.

With OlapGrd

.BackColor = vbGreen

.BorderColor = vbRed

.BottomLineStyle = crLSDoubleLine

.TopLineStyle = crLSDashLine

.RightLineStyle = crLSNoLine

.LeftLineStyle = crLSSingleLine

.CloseAtPageBreak = True

.HasDropShadow = True

.KeepTogether = True

.Left = 300

.Suppress = False

.Top = 200

End With

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = oReport

CRViewer1.ViewReport

End Sub


How to format an OLE object

This example gets an OLE object and then formats the OLE object through the OleObject Object properties. CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table and an OLE is inserted into the report. See "Inserting OLE objects into reports" in the Crystal Reports Online Help (crw.chm).

' Create a new instance of the report.

Dim oReport As New CrystalReport1

Private Sub Form_Load()

' Declare an OLEObject object.

Dim oOleObject As craxdrt.OLEObject

' Declare a generic Object.

Dim oObject As Object

' Declare a Section object.

Dim oSection As craxdrt.Section

' This variable is set to true once the OLE object is found.

Dim bOle As Boolean

bOle = False

' Search for all the report objects in each section.

For Each oSection In oReport.Sections

For Each oObject In oSection.ReportObjects

' Find the first OLE object.

If oObject.Kind = craxdrt.crOLEObject Then

' Get the graph object and exit the loop.

Set oOleObject = oObject

bOle = True

Exit For

End If

Next oObject

If bOle Then Exit For

Next oSection

' Format the blobfield object.

With oOleObject

.BackColor = vbGreen

.BorderColor = vbRed

.TopLineStyle = crLSDoubleLine

.LeftLineStyle = crLSDoubleLine

.RightLineStyle = crLSDoubleLine

.BottomLineStyle = crLSDoubleLine

.HasDropShadow = True

.BottomCropping = 1000

.BottomLineStyle = crLSSingleLine

.Left = 1000

.Height = 10000

.LeftCropping = 300

.RightCropping = 300

.RightLineStyle = crLSDashLine

.Suppress = True

.Top = 3000

.TopCropping = 300

.Width = 15000

.XScaling = 5

.YScaling = 1

.Suppress = False

End With

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = oReport

CRViewer1.ViewReport

End Sub


How to format a subreport object

This example gets a subreport object and then formats the subreport object through the SubreportObject Object properties. CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table and a subreport using the Details table is added. See "Inserting subreports" in the Crystal Reports Online Help (crw.chm).

' Create a new instance of the report.

Dim oReport As New CrystalReport1

Private Sub Form_Load()

' Declare a SubreportObject object.

Dim oSubreportObject As CRAXDRT.SubreportObject

' Declare a generic Object.

Dim oObject As Object

' Declare a Section object.

Dim oSection As CRAXDRT.Section

' This variable is set to true once the

' subreport object is found.

Dim bSubreport As Boolean

bSubreport = False

' Search for all the report objects in each section.

For Each oSection In oReport.Sections

For Each oObject In oSection.ReportObjects

' Find the first subreport object.

If oObject.Kind = crSubreportObject Then

' Get the subreport object and exit the loop.

Set oSubreportObject = oObject

bSubreport = True

Exit For

End If

Next oObject

If bSubreport Then Exit For

Next oSection

' Format the subreport object.

With oSubreportObject

.BackColor = vbYellow

.BorderColor = vbBlue

.HasDropShadow = True

.CanGrow = True

.CloseAtPageBreak = True

.KeepTogether = True

.Height = 1200

.Left = 2000

.Top = 200

.Width = 8000

.BottomLineStyle = crLSDotLine

.LeftLineStyle = crLSDashLine

.RightLineStyle = crLSDoubleLine

.TopLineStyle = crLSSingleLine

End With

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = oReport

CRViewer1.ViewReport

End Sub


How to format a text object

This example gets a text object and then formats the text object through the TextObject Object properties. CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table.

' Create a new instance of the report.

Dim oReport As New CrystalReport1

Private Sub Form_Load()

' Declare a TextObject object.

Dim oTextObject As CRAXDRT.TextObject

' Declare a generic Object.

Dim oObject As Object

' Declare a Section object.

Dim oSection As CRAXDRT.Section

' This variable is set to true once the

' text object is found.

Dim bText As Boolean

bText = False

' Search for all the report objects in each section.

For Each oSection In oReport.Sections

For Each oObject In oSection.ReportObjects

' Find the first text object.

If oObject.Kind = crTextObject Then

' Get the text object and exit the loop.

Set oTextObject = oObject

bText = True

Exit For

End If

Next oObject

If bText Then Exit For

Next oSection

' Format the text object and change the text.

With oTextObject

.BackColor = vbYellow

.BorderColor = vbRed

.BottomLineStyle = crLSDoubleLine

.CanGrow = True

.CharacterSpacing = 125

.CloseAtPageBreak = True

.FirstLineIndent = 25

.Font.Italic = True

.Font.Bold = True

.Font.Size = 14

.HasDropShadow = True

.Height = 900

.HorAlignment = crLeftAlign

.KeepTogether = True

.Left = 200

.LeftIndent = 750

.LeftLineStyle = crLSDashLine

.MaxNumberOfLines = 16

.RightIndent = 250

.RightLineStyle = crLSDotLine

.Suppress = False

.SuppressIfDuplicated = True

.SetText "Hello World"

.TextColor = vbBlue

.TextRotationAngle = crRotate0

.Top = 25

.TopLineStyle = crLSSingleLine

.Width = 3000

End With

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = oReport

CRViewer1.ViewReport

End Sub


How to import a subreport and link to a main report

This example imports a report as a subreport using the ImportSubreport Method (Section Object) and then links the reports using the Add Method (SubreportLinks Collection). CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table. A second report is created off the same data source in Crystal Reports using the Orders table. The report is saved in the sample application directory as Orders.rpt.

Note: Some methods require licensing. See License Manager Help (License.hlp) for more information.

' Create a new instance of the main report.

Dim oReport As New CrystalReport1

' Declare the variables for adding the subreport

' and subreport links.

Dim oSubreport As CRAXDRT.Report

Dim oSection As CRAXDRT.Section

Dim oSubReportObject As CRAXDRT.SubreportObject

Dim oSubreportLinks As CRAXDRT.SubreportLinks

Dim oSubreportLink As CRAXDRT.SubreportLink

Dim oMainDBFieldObject As CRAXDRT.DatabaseFieldDefinition

Dim oSubDBFieldObject As CRAXDRT.DatabaseFieldDefinition

Private Sub Form_Load()

' Import a subreport into the main report Details "B"

' section. Get the "Db" section of the report.

Set oSection = oReport.Sections.Item("Db")

oSection.Suppress = False

' Import the subreport. The report is located in the

' application path.

' Note: The ImportSubreport method requires licensing.

Set oSubReportObject = oSection.ImportSubreport(App.Path & "\Orders.rpt", 0, 0)

' Open the subreport.

Set oSubreport = oSubReportObject.OpenSubreport

' Get the "CustomerID" field in the "Customer" table

' from the main report. This is the field that will be

' linked to the subreport.

Set oMainDBFieldObject = oReport.Database.Tables.Item(1).Fields.Item(1)

' Get the "CustomerID" field in the "Orders" table

' from the subreport. This is the field that will be

' linked to the main report.

Set oSubDBFieldObject = oSubreport.Database.Tables.Item(1).Fields.Item(3)

' Link the main report and the subreport.

Set oSubreportLinks = oSubReportObject.Links

Set oSubreportLink = oSubreportLinks.Add(oMainDBFieldObject, oSubDBFieldObject)

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = oReport

CRViewer1.ViewReport

End Sub


How to re-import a subreport and link to a main report

This example links a subreport and a main report using the Add Method (SubreportLinks Collection) and then re-imports the subreport using the ReImportSubreport Method (SubreportObject Object). CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table. A second report is created off the same data source in Crystal Reports using the Orders table. The report is saved in the sample application directory as Orders.rpt. The report "Orders.rpt" is then imported into CrystalReport1 through the Designer's user interface at design time. See "Inserting subreports" in Crystal Reports Online Help (crw.chm) for more information.

Note: Some methods require licensing. See License Manager Help (License.hlp) for more information.

' Create a new instance of the main report.

Dim oReport As New CrystalReport1

' Declare the variables needed for adding

' the subreport links and reimporting the subreport.

Dim oSubreport As CRAXDRT.Report

Dim oSection As CRAXDRT.Section

Dim oReportObjects As CRAXDRT.ReportObjects

Dim oSubreportObject As CRAXDRT.SubreportObject

Dim oSubrpt As CRAXDRT.Report

Dim oReportObject As Object

Dim bSubreport As Boolean

Dim bReimported As Boolean

Private Sub Form_Load()

' Search for all the report objects in each section.

For Each oSection In oReport.Sections

Set oReportObjects = oSection.ReportObjects

For Each oReportObject In oReportObjects

If oReportObject.Kind = crSubreportObject Then

Set oSubreportObject = oReportObject

Set oSubrpt = oSubreportObject.OpenSubreport

bSubreport = True

Exit For

End If

Next

If bSubreport Then Exit For

Next

' Link the "Customer ID" field from the Customer

' table in the main report to the "Customer ID" field

' from the Orders table in the subreport.

' Note: The Links property requires licensing.

oSubreportObject.Links.Add "{Customer.Customer ID}", "{Orders.Customer ID}"

' Import the subreport once again so that any changes

' are reflected in the main report.

' Note: The ReimportSubreport method requires licensing.

oSubreportObject.ReimportSubreport bReimported

' If bReimported is True the subreport imported successfully.

' If bReimported is False the subreport failed to import.

If bReimported Then

MsgBox "Subreport imported successfully."

Else

MsgBox "Subreport failed to import."

Exit Sub

End If

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = oReport

CRViewer1.ViewReport

End Sub


How to add and delete table links

This example Demonstrates how to display information on a table link in a report using the properties of the TableLink Object, how to delete a table link using the Delete Method (TableLinks Collection), and finally how to add a table link using the Add Method (TableLinks Collection). CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table and the Orders table. The two tables are linked on the Customer ID field.

Note: Some methods require licensing. See License Manager Help (License.hlp) for more information.

' Create a new instance of the main report.

Dim oReport As New CrystalReport1

' Declare the variables needed for adding

' the table links.

Dim oTableLinks As CRAXDRT.TableLinks

Dim oTableLink As CRAXDRT.TableLink

Dim oSourceDBTable As CRAXDRT.DatabaseTable

Dim oDestinationDBTable As CRAXDRT.DatabaseTable

Dim oSourceDBField As CRAXDRT.DatabaseFieldDefinition

Dim oDestinationDBField As CRAXDRT.DatabaseFieldDefinition

Private Sub Form_Load()

' Get the collection of table links.

Set oTableLinks = oReport.Database.Links

' Display the information on the first table link.

MsgBox " The number of Table Links in this report is: " _

& oTableLinks.Count

' Get the first table link.

Set oTableLink = oTableLinks.Item(1)

MsgBox " The Source table for the link is: " _

& oTableLink.SourceTable.Name

MsgBox " The Source field for the link is: " _

& oTableLink.SourceFields(1).Name

MsgBox " The Destination table for the link is: " _

+ oTableLink.DestinationTable.Name

MsgBox " The Destination field for the link is: " _

+ oTableLink.DestinationFields.Item(1).Name

MsgBox " The TableLink index used is: " _

& oTableLink.IndexUsed

MsgBox " The TableLink join type is: " _

& oTableLink.JoinType

MsgBox " The TableLink lookup type is: " _

& oTableLink.LookupType

MsgBox " PartialMatchEnabled (True/False): " _

& oTableLink.PartialMatchEnabled

' Delete the table link.

' Note: The Delete method requires licensing.

oTableLinks.Delete (1)

MsgBox " Table link has been deleted "

' Get the tables and fields needed to create the link.

Set oSourceDBTable = oReport.Database.Tables(1)

Set oDestinationDBTable = oReport.Database.Tables(2)

Set oSourceDBField = oSourceDBTable.Fields.Item(1)

Set oDestinationDBField = oDestinationDBTable.Fields.Item(3)

' Link the "Customer ID" field of the Customer table

' to the "Customer ID" field of the Orders table.

' Note: The Add method requires licensing.

Set oTableLink = oTableLinks.Add(oSourceDBTable, oDestinationDBTable, _

oSourceDBField, oDestinationDBField, _

crJTEqual, crLTLookupParallel, False, True)

MsgBox " {Customer.CustomerID} has been linked to {Orders.CustomerID} "

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = oReport

CRViewer1.ViewReport

End Sub


How to add, delete and format groups in a crosstab

This example demonstrates how to delete a group from a crosstab using the Delete Method (CrossTabGroups Collection), how to add a group to a crosstab using the Add Method (CrossTabGroups Collection), and finally how to format the groups in a crosstab using the CrossTabGroup Object properties. The example consists of a form and a report designed in the Visual Basic IDE using the RDC. CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table.

Note: Some methods require licensing. See License Manager Help (License.hlp) for more information.

To use the example
  1. Create a standard application.
  2. Create a report using the RDC and the data source noted in the introduction.
    • Group the report on the Country field.
    • Add a crosstab to the group header. The crosstab uses the following fields:
      • Rows:

        • Customer.Customer Name

      • Columns:

        • Customer.Country

        Customer.Region

      • Summarized Fields:

        • Sum of Last Year's Sales

  3. Add the following controls to Form1:
    • Button (Command1)

      • Command1 deletes a group from the crosstab and refreshes the viewer.

    • Button (Command2)

      • Command2 adds a group to the crosstab and refreshes the viewer.

    • Button (Command3)

      • Command3 formats the groups in the crosstab and refreshes the viewer.

  4. Cut and paste the code that is listed under Form1 below into the code window for Form1 in your application.
  5. Run the application.
  6. With the application running the user can:
    • Click Command1 to delete the Region column from the crosstab.
    • Click Command2 to add the Region column back to the crosstab.
    • Click Command3 to:
      • Change the reports grouping order to be specified by England, Canada and Germany.
      • Change the crosstabs grouping order to match the reports grouping order.
      • Format the Country group in the crosstab.

        • ' Create a new instance of the main report.

        Dim oReport As New CrystalReport1

        ' Declare the variables needed for adding

        ' deleting and formatting the crosstab groups.

        Dim oCrossTabGroups As CRAXDRT.CrossTabGroups

        Dim oCrossTabObject As CRAXDRT.CrossTabObject

        Dim oDBFieldDefinition As CRAXDRT.DatabaseFieldDefinition

        Dim oCrossTabGroup As CRAXDRT.CrossTabGroup

        Dim varSpecifiedGroups(1, 2) As Variant

        Dim sFieldName As String

        Private Sub Form_Load()

        ' Get the crosstab object and crosstab groups collection

        Set oCrossTabObject = oReport.Sections("GH").ReportObjects.Item(2)

        Set oCrossTabGroups = oCrossTabObject.ColumnGroups

        ' Set the report source of the viewer and view the report.

        CRViewer1.ReportSource = oReport

        CRViewer1.ViewReport

        End Sub

        Private Sub Command1_Click()

        ' Delete the second group in the crosstab.

        If oCrossTabGroups.Count > 1 Then

        sFieldName = oCrossTabGroups.Item(2).Field.Name

        oCrossTabGroups.Delete (2)

        MsgBox "The CrossTab Group based on the field" & sFieldName & _

        " has been deleted."

        Else

        MsgBox "There is only one CrossTab group in this CrossTab Object." _

        + "This CrossTabGroup can NOT be deleted."

        End If

        ' Refresh the viewer.

        CRViewer91.Refresh

        End Sub

        Private Sub Command2_Click()

        ' Get the Region field and add it to the cross tab.

        Set oDBFieldDefinition = oReport.Database.Tables(1).Fields(12)

        oCrossTabGroups.Add oDBFieldDefinition

        MsgBox "A new CrossTabGroup Column Group based on the " _

        & oDBFieldDefinition.Name & _

        " has been added to the CrossTab object."

        ' Refresh the viewer.

        CRViewer91.Refresh

        End Sub

        Private Sub Command3_Click()

        ' Create an array of headings and groups

        ' to use as specified groups in the report group

        ' and the crosstab group.

        ' Column headings.

        varSpecifiedGroups(0, 0) = "England"

        varSpecifiedGroups(0, 1) = "Canada"

        varSpecifiedGroups(0, 2) = "Germany"

        ' Column groups.

        varSpecifiedGroups(1, 0) = "{Customer.Country} = 'England'"

        varSpecifiedGroups(1, 1) = "{Customer.Country} = 'Canada'"

        varSpecifiedGroups(1, 2) = "{Customer.Country} = 'Germany'"

        Set oCrossTabGroup = oCrossTabGroups.Item(1)

        ' Set the group to use a specifed order and groups.

        oReport.Areas("GH").SortDirection = crSpecifiedOrder

        oReport.Areas("GH").SpecifiedGroups = varSpecifiedGroups

        ' Format the crosstab.

        With oCrossTabGroup

        .BackColor = vbGreen

        .Condition = crGCAnyValue

        .EnableSuppressLabel = False

        .EnableSuppressSubtotal = False

        .SortDirection = crSpecifiedOrder

        ' Set the crosstab group to use a specifed order and groups.

        .SortDirection = crSpecifiedOrder

        .SpecifiedGroups = varSpecifiedGroups

        MsgBox "The CrossTab Group that is being formatted is based on the " & _

        .Field.Name & " field."

        End With

        ' Refresh the viewer.

        CRViewer1.Refresh

        End Sub


How to format a group in the section format event

This example changes the color of the text displayed in the group header based on the value of the group. The value is checked through the Value and NextValue properties of the GroupNameFieldDefinition Object. The values are checked in the Format Event (Section Object). CrystalReport1 is connected to the xtreme.mdb database found in the \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases folder. The report is using the Customer table and is grouped on the Country field and then the Last Year's Sales field.

' Create a new instance of the report.

Dim oReport As New CrystalReport1

' Declare a GroupNameFieldDefinitions collection.

Dim cGroupNameFieldDefinitions As CRAXDRT.GroupNameFieldDefinitions

' Declare a GroupNameFieldDefinition object.

Dim oGroupNameFieldDefinition As CRAXDRT.GroupNameFieldDefinition

' Declare a Section object with events.

Dim WithEvents oSection As CRAXDRT.Section

Dim x As Integer

Private Sub Form_Load()

' Set the section to the Last Year's sales group header.

Set oSection = oReport.Sections("GH2")

' Get the collection of group name fields.

Set cGroupNameFieldDefinitions = oReport.GroupNameFields

' Set the report source of the viewer and view the report.

CRViewer1.ReportSource = oReport

CRViewer1.ViewReport

End Sub

' Note: You can also place code for a section format

' event in a Report form (for example CrystalReport1) found

' under the Designer folder. Double-click the desired section

' and place the code in the code window. If your report

' is a file (*.rpt) then you must decalre a section

' object with events and select the section object and then

' format in the forms code window.

Private Sub oSection_format(ByVal pFormattingInfo As Object)

' While the section is formatting check the value of the

' GroupNameFieldDefinition object. Change the text color

' based on that value.

If cGroupNameFieldDefinitions.Item(2).Value > 20000 Then

oReport.Sections("GH2").ReportObjects.Item(1).TextColor = vbGreen

Else

' If the value is less than 20000 compare the next value with the

' present value to determine the text color.

If cGroupNameFieldDefinitions.Item(2).NextValue > cGroupNameFieldDefinitions.Item(2).Value Then

oReport.Sections("GH2").ReportObjects.Item(1).TextColor = vbBlue

Else: oReport.Sections("GH2").ReportObjects.Item(1).TextColor = vbRed

End If

End If

End Sub


Enumerated Types

CRAlignment

Constant | Value
crDefaultAlign | 0
crHorCenterAlign | 2
crJustified | 4
crLeftAlign | 1
crRightAlign | 3


CRAMPMType

Constant | Value
crAmPmAfter | 1
crAmPmBefore | 0


CRAreaKind

Constant | Value
crDetail | 4
crGroupFooter | 5
crGroupHeader | 3
crPageFooter | 7
crPageHeader | 2
crReportFooter | 8
crReportHeader | 1


CRBarSize

Constant (numeric order) | Description
crMinimumBarSize | 0
crSmallBarSize | 1
crAverageBarSize | 2
crLargeBarSize | 3
crMaximumBarSize | 4


CRBindingMatchType

Constant | Value
crBMTName | 0
crBMTNameAndValue | 1


CRBooleanFieldFormatConditionFormulaType

Constant | Value
crOutputFormatConditionFormulaType | 20 (&H14)


CRBooleanOutputType

Constant | Value
crOneOrZero | 4
crTOrF | 1
crTrueOrFalse | 0
crYesOrNo | 2
crYOrN | 3


CRBorderConditionFormulaType

Constant | Value
crBackgroundColorConditionFormulaType | 45 (&H2D)
crBorderColorConditionFormulaType | 46 (&H2E)
crBottomLineStyleConditionFormulaType | 43 (&H2B)
crHasDropShadowConditionFormulaType | 44 (&H2C)
crLeftLineStyleConditionFormulaType | 40 (&H28)
crRightLineStyleConditionFormulaType | 41 (&H29)
crTightHorizontalConditionFormulaType | 47 (&H2F)
crTightVerticalConditionFormulaType | 48 (&H30)
crTopLineStyleConditionFormulaType | 42 (&H2A)


CRCommonFieldFormatConditionFormulaType

Constant | Value
crSuppressIfDuplicatedConditionFormulaType | 80
crUseSystemDefaultConditionFormulaType | 81 (&H51)


CRConvertDateTimeType

Constant | Value
crConvertDateTimeToDate | 1
crConvertDateTimeToString | 0
crKeepDateTimeType | 2


CRCurrencyPositionType

Constant | Value
crLeadingCurrencyInsideNegative | 0
crLeadingCurrencyOutsideNegative | 1
crTrailingCurrencyInsideNegative | 2
crTrailingCurrencyOutsideNegative | 3


CRCurrencySymbolType

Constant | Value
crCSTFixedSymbol | 1
crCSTFloatingSymbol | 2
crCSTNoSymbol | 0


CRDatabaseType

Constant | Value
crSQLDatabase | 2
crStandardDatabase | 1


CRDateCalendarType

Constant | Value
crGregorianCalendar | 1
crGregorianUSCalendar | 2
crGregorianArabicCalendar | 10
crGregorianMEFrenchCalendar | 9
crGregorianXlitEnglishCalendar | 11
crGregorianXlitFrenchCalendar | 12
crHebrewCalendar | 8
crHijriCalendar | 6
crJapaneseCalendar | 3
crKoreanCalendar | 5
crTaiwaneseCalendar | 4
crThaiCalendar | 7


CRDateEraType

Constant | Value
crLongEra | 1
crNoEra | 2
crShortEra | 0


CRDateFieldFormatConditionFormulaType

Constant | Value
crCalendarTypeConditionFormulaType | 131 (&H83)
crDateFirstSeparatorCondidtionFormulaType | 128 (&H80)
crDateOrderConditionFormulaType | 124 (&H7C)
crDatePrefixSeparatorConditionFormulaType | 132 (&H84)
crDateSecondSeparatorConditionFormulaType | 129 (&H81)
crDateSuffixSeparatorConditionFormulaType | 133 (&H85)
crDayFormatConditionFormulaType | 122 (&H7A)
crDayOfWeekEnclosureConditionFormulaType | 134 (&H86)
crDayOfWeekPositionConditionFormulaType | 127 (&H7F)
crDayOfWeekSeparatorConditionFormulaType | 126 (&H7E)
crDayOfWeekTypeConditionFormulaType | 125 (&H7D)
crEraTypeConditionFormulaType | 130 (&H82)
crMonthFormatConditionFormulaType | 121 (&H79)
crWindowsDefaultTypeConditionFormulaType | 123 (&H7B)
crYearFormatConditionFormulaType | 120 (&H78)


CRDateOrder

Constant | Value
crDayMonthYear | 1
crMonthDayYear | 2
crYearMonthDay | 0


CRDateTimeFieldFormatConditionFormulaType

Constant | Value
crDateTimeOrderConditionFormulaType | 140 (&H8C)
crDateTimeSeparatorConditionFormulaType | 141 (&H8D)


CRDateWindowsDefaultType

Constant | Value
crNotUsingWindowsDefaults | 2
crUseWindowsLongDate | 0
crUseWindowsShortDate | 1


CRDayType

Constant | Value
crLeadingZeroNumericDay | 1
crNoDay | 2
crNumericDay | 0


CRDiscreteOrRangeKind

Constant (numeric order) | Value
crDiscreteValue | 0
crRangeValue | 1
crDiscreteAndRangeValue | 2


CRDivisionMethod

Constant | Value
crAutomaticDivision | 0
crManualDivision | 1


CRExchangeDestinationType

Constant | Value
crExchangeFolderType | 0
crExchangePostDocMessage | 1011 (&H3F3)


CRExportDestinationType

Constant | Value
crEDTApplication | 5
crEDTDiskFile | 1
crEDTEMailMAPI | 2
crEDTEMailVIM | 3
crEDTLotusDomino | 6
crEDTMicrosoftExchange | 4
crEDTNoDestination | 0


CRExportFormatType

Constant | Value
crEFTCharSeparatedValues | 7
crEFTCommaSeparatedValues | 5
crEFTCrystalReport | 1
crEFTCrystalReport70 | 33
crEFTDataInterchange | 2
crEFTExactRichText | 35 (&H23)
crEFTExcel50 | 21 (&H15)
crEFTExcel50Tabular | 22 (&H16)
crEFTExcel70 | 27 (&H1B)
crEFTExcel70Tabular | 28 (&H1C)
crEFTExcel80 | 29 (&H1D)
crEFTExcel80Tabular | 30 (&H1E)
crEFTExcel97 | 36 (&H24)
crEFTExplorer32Extend | 25 (&H19)
crEFTHTML32Standard | 24 (&H18)
crEFTHTML40 | 32 (&H20)
crEFTLotus123WK1 | 12
crEFTLotus123WK3 | 13
crEFTLotus123WKS | 11
crEFTNoFormat | 0
crEFTODBC | 23 (&H17)
crEFTPaginatedText | 10
crEFTPortableDocFormat | 31 (&H1F)
crEFTRecordStyle | 3
crEFTReportDefinition | 34 (&H22)
crEFTTabSeparatedText | 9
crEFTTabSeparatedValues | 6
crEFTText | 8
crEFTWordForWindows | 14
crEFTXML | 37 (&H25)


CRFieldKind

Constant | Value
crDatabaseField | 1
crFormulaField | 2
crGroupNameField | 5
crRunningTotalField | 7
crParameterField | 6
crSpecialVarField | 4
crSQLExpressionField | 8
crSummaryField | 3


CRFieldMappingType

Constant | Value
crAutoFieldMapping | 0
crEventFieldMapping | 2
crPromptFieldMapping | 1


CRFieldValueType

Constant | Value
crBitmapField | 17 (&H11)
crBlobField | 15
crBooleanField | 9
crChartField | 21 (&H15)
crCurrencyField | 8
crDateField | 10
crDateTimeField | 16 (&H10)
crIconField | 18 (&H12)
crInt16sField | 3
crInt16uField | 4
crInt32sField | 5
crInt32uField | 6
crInt8sField | 1
crInt8uField | 2
crNumberField | 7
crOleField | 20 (&H14)
crPersistentMemoField | 14
crPictureField | 19 (&H13)
crStringField | 12
crTimeField | 11
crTransientMemoField | 13
crUnknownField | 22 (&H16)


CRFontColorConditionFormulaType

Constant | Value
crColorConditionFormulaType | 180 (&HB4)
crFontConditionFormulaType | 181 (&HB5)
crFontSizeConditionFormulaType | 183 (&HB7)
crFontStrikeOutConditionFormulaType | 184 (&HB8)
crFontStyleConditionFormulaType | 182 (&HB6)
crFontUnderLineConditioneFormulaType | 185 (&HB9)


CRFormulaSyntax

Constant | Value
crBasicSyntaxFormula | 1
crCrystalSyntaxFormula | 0 Default value


CRGraphColor

Constant | Value
crBlackAndWhiteGraph | 1
crColorGraph | 0


CRGraphDataPoint

Constant | Value
crNone | 0
crShowLabel | 1
crShowValue | 2


CRGraphDataType

Constant | Value
crCrossTabGraph | 2
crDetailGraph | 1
crGroupGraph | 0


CRGraphDirection

Constant | Value
crHorizontalGraph | 0
crVerticalGraph | 1


CRGraphType

Constant | Value
crAbsoluteAreaGraph | 20 Obsolete
crDualAxisBubbleGraph | 91 Obsolete
crFaked3DAbsoluteAreaGraph | 23 Obsolete
crFaked3DPercentAreaGraph | 25 (&H19)
crFaked3DPercentBarGraph | 5
crFaked3DRegularPieGraph | 31 (&H1F)
crFaked3DSideBySideBarGraph | 3
crFaked3DStackedAreaGraph | 24 (&H18)
crFaked3DStackedBarGraph | 4
crHighLowDualAxisGraph | 101 Obsolete.
crHighLowGraph | 100 (&H64)
crHighLowOpenCloseDualAxisGraph | 105 Obsolete.
crHighLowOpenCloseGraph | 104 (&H68)
crHighLowOpenDualAxisGraph | 103 Obsolete.
crHighLowOpenGraph | 102 Obsolete.
crLineGraphWithMarkers | 13
crMultipleDoughnutGraph | 41 (&H29)
crMultiplePieGraph | 32 (&H20)
crMultipleProportionalDoughnutGraph | 42 (&H2A)
crMultipleProportionalPieGraph | 33 (&H21)
crPercentageLineGraph | 12
crPercentageLineGraphWithMarkers | 15
crPercentAreaGraph | 22 (&H16)
crPercentBarGraph | 2
crRadarDualAxisGraph | 82 Obsolete
crRegularBubbleGraph | 90 (&H5A)
crRegularDoughnutGraph | 40 (&H28)
crRegularLineGraph | 10
crRegularPieGraph | 30 (&H1E)
crRegularRadarGraph | 80 (&H50)
crSideBySideBarGraph | 0
crStackedAreaGraph | 21 (&H15)
crStackedBarGraph | 1
crStackedLineGraph | 11
crStackedLineGraphWithMarkers | 14
crStackedRadarGraph | 81 (&H51)
crThreeDCutCornersGraph | 53 (&H35)
crThreeDOctagonGraph | 52 (&H34)
crThreeDPyramidGraph | 51 (&H33)
crThreeDRegularGraph | 50 (&H32)
crThreeDSurfaceHoneycombGraph | 62 (&H3E)
crThreeDSurfaceRegularGraph | 60 (&H3C)
crThreeDSurfaceWithSidesGraph | 61 (&H3D)
crUnknownGraph | 1000 (&H3E8)
crXyScatterGraph | 70 (&H46)


CRGridlineType

Constant | Value
crMajorAndMinorGridlines | 3
crMajorGridlines | 2
crMinorGridlines | 1
crNoGridlines | 0


CRGroupCondition

Constant | Value
crGCAnnually | 7
crGCAnyValue | 14
crGCBiweekly | 2
crGCByAMPM | 18 (&H12)
crGCByHour | 17 (&H11)
crGCByMinute | 16 (&H10)
crGCBySecond | 15
crGCDaily | 0
crGCEveryNo | 11
crGCEveryYes | 10
crGCMonthly | 4
crGCNextIsNo | 13
crGCNextIsYes | 12
crGCQuarterly | 5
crGCSemiAnnually | 6
crGCSemimonthly | 3
crGCToNo | 9
crGCToNo | 8
crGCWeekly | 1


CRHierarchicalSummaryType

Constant | Value
crHierarchicalSummaryNone | 0
crSummaryAcrossHierarchy | 1


CRHourType

Constant | Value
crNoHour | 2
crNumericHour | 0
crNumericHourNoLeadingZero | 1


CRHTMLPageStyle

Constant | Value
crFramePageStyle | 2
crPlainPageStyle | 0
crToolbarAtBottomPageStyle | 4
crToolbarAtTopPageStyle | 3
crToolbarPageStyle | 1


CRHTMLToolbarStyle

These bitwise constants can be XOR'd to specify the toolbar style.

Constant | Value
crToolbarRefreshButton | 1
crToolbarSearchBox | 2


CRImageType

Constant | Value
crDIBImageType | 1
crJPEGImageType | 2
crImageUnknown | 0


CRLeadingDayPosition

Constant | Value
crLeadingDayOfWeek | 0
crTrailingDayOfWeek | 1


CRLeadingDayType

Constant | Value
crLongLeadingDay | 1
crNoLeadingDay | 2
crShortLeadingDay | 0


CRLegendPosition

Constant | Value
crPlaceLeft | 5
crPlaceRight | 4
crPlaceBottom | 6
crPlaceCustom | 7


CRLineSpacingType

Constant | Value
crExactSpacing | 1
crMultipleSpacing | 0


CRLineStyle

Constant | Value
crLSDashLine | 3
crLSDotLine | 4
crLSDoubleLine | 2. Not valid for LineObject.LineStyle and BoxObject.LineStyle.
crLSNoLine | 0. Not valid for LineObject.LineStyle and BoxObject.LineStyle.
crLSSingleLine | 1


CRLinkJoinType

Constant | Value
crJTAdvance | 13
crJTEqual | 4
crJTGreaterOrEqual | 10
crJTGreaterThan | 8
crJTLeftOuter | 5
crJTLessOrEqual | 11
crJTLessThan | 9
crJTNotEqual | 12
crJTRightOuter | 6


CRLinkLookUpType

Constant | Value
crLTLookupParallel | 1
crLTLookupProduct | 2
crLTLookupSeries | 3


CRMarkerShape

Constant | Value
crCircleShape | 4
crDiamondShape | 5
crRectangleShape | 1
crTriangleShape | 8


CRMarkerSize

Constant | Value
crLargeMarkers | 4
crMediumLargeMarkers | 3
crMediumMarkers | 2
crMediumSmallMarkers | 1
crSmallMarkers | 0


CRMinuteType

Constant | Value
crNoMinute | 2
crNumericMinute | 0
crNumericMinuteNoLeadingZero | 1


CRMonthType

Constant | Value
crLeadingZeroNumericMonth | 1
crLongMonth | 3
crNoMonth | 4
crNumericMonth | 0
crShortMonth | 2


CRNegativeType

Constant | Value
crBracketed | 3
crLeadingMinus | 1
crNotNegative | 0
crTrailingMinus | 2


CRNumberFormat

Constant | Value
crCurrencyMillions | 12
crCurrencyNoDecimal | 3
crCurrencyThousands | 11
crCurrencyTwoDecimal | 4
crCustomNumberFormat | 8
crMillionsNoDecimal | 10
crNoDecimal | 0
crOneDecimal | 1
crPercentNoDecimal | 5
crPercentOneDecimal | 6
crPercentTwoDecimal | 7
crThousandsNoDecimal | 9
crTwoDecimal | 2


CRNumericFieldFormatConditionFormulaType

Constant | Value
crAllowFieldClippingConditionFormulaType | 114 (&H72)
crCurrencyPositionConditionFormulaType | 111 (&H6F)
crCurrencySymbolConditionFormulaType | 109 (&H6D)
crCurrencySymbolFormatConditionFormulaType | 104 (&H68)
crDecimalSymbolConditionFormulaType | 108 (&H6C)
crDisplayReverseSignConditionFormulaType | 112 (&H70)
crEnableSuppressIfZeroConditionFormulaType | 105 (&H69)
crEnableUseLeadZeroConditionFormulaType | 102 (&H66)
crHasOneSymbolPerPageConditionFormulaType | 110 (&H6E))
crNDecimalPlacesConditionFormulaType | 100 (&H64)
crNegativeFormatConditionFormulaType | 103 (&H67)
crRoundingFormatConditionFormulaType | 101 (&H65)
crThousandsSeparatorFormatConditionFormulaType | 106 (&H6A)
crThousandSymbolFormatConditionFormulaType | 107 (&H6B)
crZeroValueStringConditionFormulaType | 113 (&H71)


CRObjectFormatConditionFormulaType

Constant | Value
crCssClassConditionFormulaType | 66 (&H42)
crEnableCanGrowConditionFormulaType | 64 (&H40)
crEnableCloseAtPageBreakConditionFormulaType | 62 (&H3E)
crEnableKeepTogetherConditionFormulaType | 61 (&H3D)
crEnableSuppressConditinFormulaType | 60 (&H3C)
crHorizontalAlignmentConditionFormulaType | 63 (&H3F)
crHyperLinkConditionFormulaType | 68 (&H44)
crRotationConditionFormulaType | 67 (&H43)
crToolTipTextConditionFormulaType | 65 (&H41)


CRObjectKind

Constant | Value
crBlobFieldObject | 9
crBoxObject | 4
crCrossTabObject | 8
crFieldObject | 1
crGraphObject | 7
crLineObject | 3
crMapObject | 10
crOlapGridObject | 11
crOleObject | 6
crSubreportObject | 5
crTextObject | 2


CROpenReportMethod

Constant | Value
crOpenReportByDefault | 0
crOpenReportByTempCopy | 1


CRPaperOrientation

Constant | Value
crDefaultPaperOrientation | 0
crLandscape | 2
crPortrait | 1


CRPaperSize

Constant | Value
crDefaultPaperSize | 0
crPaper10x14 | 16 (&H10)
crPaper11x17 | 17 (&H11)
crPaperA3 | 8
crPaperA4 | 9
crPaperA4Small | 10
crPaperA5 | 11
crPaperB4 | 12
crPaperB5 | 13
crPaperCsheet | 24 (&H18)
crPaperDsheet | 25 (&H19)
crPaperEnvelope10 | 20 (&H14)
crPaperEnvelope11 | 21 (&H15)
crPaperEnvelope12 | 22 (&H16)
crPaperEnvelope14 | 23 (&H17)
crPaperEnvelope9 | 19 (&H13)
crPaperEnvelopeB4 | 33 (&H21)
crPaperEnvelopeB5 | 34 (&H22)
crPaperEnvelopeB6 | 35 (&H23)
crPaperEnvelopeC3 | 29 (&H1D)
crPaperEnvelopeC4 | 30 (&H1E)
crPaperEnvelopeC5 | 28 (&H1C)
crPaperEnvelopeC6 | 31 (&H1F)
crPaperEnvelopeC65 | 32 (&H20)
crPaperEnvelopeDL | 27 (&H1B)
crPaperEnvelopeItaly | 36 (&H24)
crPaperEnvelopeMonarch | 37 (&H25)
crPaperEnvelopePersonal | 38 (&H26)
crPaperEsheet | 26 (&H1A)
crPaperExecutive | 7
crPaperFanfoldLegalGerman | 41 (&H29)
crPaperFanfoldStdGerman | 40 (&H28)
crPaperFanfoldUS | 39 (&H27)
crPaperFolio | 14
crPaperLedger | 4
crPaperLegal | 5
crPaperLetter | 1
crPaperLetterSmall | 2
crPaperNote | 18 (&H12)
crPaperQuarto | 15
crPaperStatement | 6
crPaperTabloid | 3
crPaperUser | 256 (&H100)


CRPaperSource

Constant | Value
crPRBinAuto | 7
crPRBinCassette | 14
crPRBinEnvelope | 5
crPRBinEnvManual | 6
crPRBinFormSource | 15
crPRBinLargeCapacity | 11
crPRBinLargeFmt | 10
crPRBinLower | 2
crPRBinManual | 4
crPRBinMiddle | 3
crPRBinSmallFmt | 9
crPRBinTractor | 8
crPRBinUpper | 1


CRParameterFieldType

Constant | Value
crQueryParameter | 1
crReportParameter | 0
crStoreProcedureParameter | 2


CRParameterPickListSortMethod

Constant (numeric order) | Value
crNoSort | 0
crAlphanumericAscending | 1
crAlphanumericDescending | 2
crNumericAscending | 3
crNumericDescending | 4


CRPieLegendLayout

Constant | Value
crAmountLayout | 1
crBothLayout | 2
crNoneLayout | 3
crPercentLayout | 0


CRPieSize

Constant (numeric order) | Value
crMaximumPieSize | 0
crLargePieSize | 16 (&H10)
crAveragePieSize | 32 (&H20)
crSmallPieSize | 48 (&H40)
crMinimumPieSize | 64 (&H30)


CRPlaceHolderType

Constant | Value
crAllowPlaceHolders | 2
crDelayTotalPageCountCalc | 1


CRPrinterDuplexType

Constant | Value
crPRDPDefault | 0
crPRDPHorizontal | 3
crPRDPSimplex | 1
crPRDPVertical | 2


CRPrintingProgress

Constant | Value
crPrintingCancelled | 5
crPrintingCompleted | 3
crPrintingFailed | 4
crPrintingHalted | 6
crPrintingInProgress | 2
crPrintingNotStarted | 1


CRRangeInfo

Constant (numeric order) | Value
crRangeNotIncludeUpperLowerBound | 0
crRangeIncludeUpperBound | 1
crRangeIncludeLowerBound | 2
crRangeNoUpperBound | 4
crRangeNoLowerBound | 8


CRRenderResultType

Constant | Value
crBSTRType | 8. This constant is currently not supported.
crUISafeArrayType | 8209


CRReportFileFormat

Constant | Value
cr70FileFormat | 1792
cr80FileFormat | 2048


CRReportFormatStyle

Constant | Value
crRFStandardStyle | 0
crRFLeadingBreakStyle | 1
crRFTrailingBreakStyle | 2
crRFTableStyle | 3
crRFDropTableStyle | 4
crRFExecutiveLeadingBreakStyle | 5
crRFExecutiveTrailingBreakStyle | 6
crRFShadingStyle | 7
crRFRedBlueBorderStyle | 8
crRFMartoonTealBoxStyle | 9


CRReportKind

Constant | Value
crColumnarReport | 1
crLabelReport | 2
crMulColumnReport | 3


CRReportVariableValueType

Constant | Value
crRVBoolean | 2
crRVCurrency | 1
crRVDate | 3
crRVDateTime | 5
crRVNumber | 0
crRVString | 6
crRVTime | 4


CRRotationAngle

Constant (numeric order) | Value
crRotate0 | 0
crRotate90 | 1
crRotate270 | 2


CRRoundingType

Constant (numeric order) | Value
crRoundToMillion | 17
crRoundToHundredThousand | 16
crRoundToTenThousand | 15
crRoundToThousand | 14
crRoundToHundred | 13
crRoundToTen | 12
crRoundToUnit | 11
crRoundToTenth | 10
crRoundToHundredth | 9
crRoundToThousandth | 8
crRoundToTenThousandth | 7
crRoundToHundredThousandth | 6
crRoundToMillionth | 5
crRoundToTenMillionth | 4
crRoundToHundredMillionth | 3
crRoundToBillionth | 2
crRoundToTenBillionth | 1


CRRunningTotalCondition

Constant | Value
crRTEvalNoCondition | 0
crRTEvalOnChangeOfField | 1
crRTEvalOnChangeOfGroup | 2
crRTEvalOnFormula | 3


CRSearchDirection

Constant (numeric order) | Value
crForward | 0
crBackward | 1


CRSecondType

Constant | Value
crNumericNoSecond | 2
crNumericSecond | 0
crNumericSecondNoLeadingZero | 1


CRSectionAreaFormatConditionFormulaType

Constant | Value
crSectionAreaBackgroundColorConditionFormulaType | 9
crSectionAreaCssClassConditionFormulaType | 8
crSectionAreaEnableHideForDrillDownConditionFormulaType | 11
crSectionAreaEnableKeepTogetherConditionFormulaType | 4
crSectionAreaEnableNewPageAfterConditionFormulaType | 2
crSectionAreaEnableNewPageBeforeConditionFormulaType | 3
crSectionAreaEnablePrintAtBottomOfPageConditionFormulaType | 1
crSectionAreaEnableResetPageNumberAfterConditionFormulaType | 6
crSectionAreaEnableSuppressConditionFormulaType | 0
crSectionAreaEnableSuppressIfBlankConditionFormulaType | 5
crSectionAreaEnableUnderlaySectionConditionFormulaType | 7
crSectionAreaShowAreaConditionFormulaType | 10


CRSliceDetachment

Constant (numeric order) | Value
crLargestSlice | 2
crSmallestSlice | 1
crNoDetachment | 0


CRSortDirection

Constant | Value
crAscendingOrder | 0
crDescendingOrder | 1
crOriginalOrder | 2. Not supported for any kind of groups.
crSpecifiedOrder | 3. Not supported for any kind of groups.


CRSpecialVarType

Constant | Value
crSVTDataDate | 4
crSVTDataTime | 5
crSVTFileAuthor | 15
crSVTFileCreationDate | 16 (&H10)
crSVTFilename | 14
crSVTGroupNumber | 8
crSVTGroupSelection | 13
crSVTModificationDate | 2
crSVTModificationTime | 3
crSVTPageNofM | 17 (&H11)
crSVTPageNumber | 7
crSVTPrintDate | 0
crSVTPrintTime | 1
crSVTRecordNumber | 6
crSVTRecordSelection | 12
crSVTReportComments | 11
crSVTReportTitle | 10
crSVTTotalPageCount | 9


CRStringFieldConditionFormulaType

Constant | Value
crTextInterpretationConditionFormulaType | 200 (&HC8)


CRSubreportConditionFormulaType

Constant | Value
crCaptionConditionFormulaType | 220 (&HDC)
crDrillDownTabTextConditionFormulaType | 221 (&HDD)


CRSummaryType

Constant | Value
crSTAverage | 1
crSTCount | 6
crSTDCorrelation | 10
crSTDCovariance | 11
crSTDistinctCount | 9
crSTDMedian | 13
crSTDMode | 17 (&H11)
crSTDNthLargest | 15
crSTDNthMostFrequent | 18 (&H12)
crSTDNthSmallest | 16 (&H10)
crSTDPercentage | 19 (&H13)
crSTDPercentile | 14
crSTDWeightedAvg | 12
crSTMaximum | 4
crSTMinimum | 5
crSTPopStandardDeviation | 8
crSTPopVariance | 7
crSTSampleStandardDeviation | 3
crSTSampleVariance | 2
crSTSum | 0


CRTableDifferences

Constant | Value
crTDOK | 0x00000000
crTDDatabaseNotFound | 0x00000001
crTDServerNotFound | 0x00000002
crTDServerNotOpened | 0x00000004
crTDAliasChanged | 0x00000008
crTDIndexesChanged | 0x00000010
crTDDriverChanged | 0x00000020
crTDDictionaryChanged | 0x00000040
crTDFileTypeChanged | 0x00000080
crTDRecordSizeChanged | 0x00000100
crTDAccessChanged | 0x00000200
crTDParametersChanged | 0x00000400
crTDLocationChanged | 0x00000800
crTDDatabaseOtherChanges | 0x00001000
crTDNumberFieldChanged | 0x00010000
crTDFieldOtherChanges | 0x00020000
crTDFieldNameChanged | 0x00040000
crTDFieldDescChanged | 0x00080000
crTDFieldTypeChanged | 0x00100000
crTDFieldSizeChanged | 0x00200000
crTDNativeFieldTypeChanged | 0x00400000
crTDNativeFieldOffsetChanged | 0x00800000
crTDNativeFieldSizeChanged | 0x01000000
crTDFieldDecimalPlacesChanged | 0x02000000


CRTextFormat

Constant | Value
crHTMLText | 2
crRTFText | 1
crStandardText | 0


CRTimeBase

Constant | Value
cr12Hour | 0
cr24Hour | 1


CRTimeFieldFormatConditionFormulaType

Constant | Value
crAMPMFormatConditionFormulaType | 161 (&HA1)
crAMStringConditionFormulaType | 166 (&HA6)
crHourFormatConditionFormulaType | 162 (&HA2)
crHourMinuteSeparatorConditionFormulaType | 168 (&HA8)
crMinuteFormatConditionFormulaType | 163 (&HA3)
crMinuteSecondSeparatorConditionFormulaType | 167 (&HA7)
crPMStringConditionFormulaType | 165 (&HA5)
crSecondFormatConditionFormulaType | 164 (&HA4)
crTimeBaseConditionFormulaType | 160 (&HA0)


CRTopOrBottomNGroupSortOrder

Constant | Value
crAllGroupsSorted | 1
crAllGroupsUnsorted | 0
crBottomNGroups | 3
crTopNGroups | 2
crUnknownGroupsSortOrder | 10


CRValueFormatType

Constant | Value
crAllowComplexFieldFormatting | 4
crIncludeFieldValues | 1
crIncludeHiddenFields | 2


CRViewingAngle

Constant | Value
crBirdsEyeView | 15
crDistortedStdView | 10
crDistortedView | 4
crFewGroupsView | 9
crFewSeriesView | 8
crGroupEmphasisView | 7
crGroupEyeView | 6
crMaxView | 16 (&H10)
crShorterView | 12
crShortView | 5
crStandardView | 1
crTallView | 2
crThickGroupsView | 11
crThickSeriesView | 13
crThickStdView | 14
crTopView | 3


CRYearType

Constant | Value
crLongYear | 1
crNoYear | 2
crShortYear | 0


Report Viewer Object Model

The Crystal Report Viewer contains an extensive object model allowing you complete control over how the viewer appears and functions. This section provides detailed information on the properties, methods and events of the Crystal Report Viewer object model for both the ActiveX viewer, and the Java Bean viewer.

Click the appropriate link to jump to that section:

  • Report Viewer/ActiveX Object Model technical reference
  • Enumerated Types—Report Viewer
  • The Report Viewer/Java Bean technical reference


Report Viewer/ActiveX Object Model technical reference

The following diagram outlines the Report Viewer hierarchy.


CRField Object (CRVIEWERLib)

The CRField object contains information related to the fields in a report displayed in the Report Viewer.

CRField Object Properties

Property | Description | Read/Write
FieldType | CRFieldType (CRViewerLib). Gets the type of field. | Read-only
IsRawData | Boolean. Gets whether or not the data in the field is raw data. | Read-only
Name | String. Gets the name of the field. | Read-only
Value | Variant. Default property gets the value in the field. | Read-only


CRFields Collection (CRVIEWERLib)

The CRFields Collection contains instances of CRFields objects.

CRFields Collection Properties

Property | Description | Read/Write
Count | Long. Gets the total number of items in the Collection. | Read-only
Item (index As Long) | Long. Default property gets the 1-based index number of the item in the Collection. | Read-only
SelectedFieldIndex | Long. Gets the index of the selected field. | Read-only


CRVEventInfo Object (CRVIEWERLib)

The CRVEventInfo object contains information about events relating to objects within a report.

CRVEventInfo Object Properties

Property | Description | Read/Write
CanDrillDown | Boolean. Gets whether or not the object is drillable. | Read-only
Index | Long. Gets the number identifying a control in a control array. | Read-only
ParentIndex | Long. Gets reference to the object's parent's index. | Read-only
Text | String. Gets the object's text string. | Read-only
Type | CRObjectType (CRViewerLib). Gets the object type. | Read-only


CRVEventInfo Object Methods

GetFields Method (CRVEventInfo Object)

Use the GetFields method to get the Fields Collection.

Syntax

Function GetFields ()


CRViewer Object (CRVIEWERLib)

The CRViewer object is the primary object representing the Crystal Report Viewer Control as it appears on a Form in your Visual Basic application. The current interface is ICrystalReportViewer11.

Click the appropriate link to jump to that section:

  • CRViewer Object Properties
  • CRViewer Object Methods
  • CRViewer Object Events


CRViewer Object Properties

Property | Description | Read/Write
ActiveViewIndex | Integer. Gets the 1-based index of the current view (tab). | Read only
DisplayBackgroundEdge | Boolean. Gets or sets whether the report is offset from the edge of its view window. | Read/Write
DisplayBorder | Boolean. Gets or sets whether the border of the viewer object is displayed. | Read/Write
DisplayGroupTree | Boolean. Gets or sets the visibility of the group tree. | Read/Write
DisplayTabs | Boolean. Gets or sets whether the viewer has tabs for navigation between views. | Read/Write
DisplayToolbar | Boolean. Gets or sets the visibility of the toolbar. | Read/Write
EnableAnimationCtrl | Boolean. Gets or sets whether or not the animation control is visible. | Read/Write
EnableCloseButton | Boolean. Gets or sets the visibility of the close button. | Read/Write
EnableDrillDown | Boolean. Gets or sets whether drill down is allowed. | Read/Write
EnableExportButton | Boolean. Gets or sets the visibility of the Export toolbar button. | Read/Write
EnableGroupTree | Boolean. Gets or sets whether or not the group tree is available. | Read/Write
EnableHelpButton | Boolean. Gets or sets whether or not the help button appears on the toolbar. | Read/Write
EnableNavigationControls | Boolean. Gets or sets whether or not the First Page button, Previous Page button, Next Page button, and Last Page button appear on the toolbar. | Read/Write
EnablePopupMenu | Boolean. Gets or sets whether the popup menu is available. | Read/Write
EnablePrintButton | Boolean. Gets or sets the visibility of the Print button. | Read/Write
EnableProgressControl | Boolean. Gets or sets the visibility of the progress control. | Read/Write
EnableRefreshButton | Boolean. Gets or sets the visibility of the Refresh button. | Read/Write
EnableSearchControl | Boolean. Gets or sets the visibility of the search control. | Read/Write
EnableSearchExpertButton | Boolean. Gets or sets the status of the Search Expert toolbar button. | Read/Write
EnableStopButton | Boolean. Gets or sets whether the viewer displays the stop button. | Read/Write
EnableToolbar | Boolean. Gets or sets the visibility of the toolbar. | Read/Write
EnableZoomControl | Boolean. Gets or sets the visibility of the zoom control. | Read/Write
IsBusy | Boolean. Gets the status of the control, busy or not busy. | Read only
ReportSource | Unknown. Gets or sets the report source. | Read/Write
TrackCursorInfo | CRVTrackCursorInfo Object (CRVIEWERLib). Gets reference to TrackCursor information. | Read only
ViewCount | Integer. Gets the current number of views (tabs). | Read only


CRViewer Object Methods

The following methods are discussed in this section:

  • ActivateView Method (CRViewer Object)
  • AddView Method (CRViewer Object)
  • CloseView Method (CRViewer Object)
  • GetCurrentPageNumber Method (CRViewer Object)
  • GetViewName Method (CRViewer Object)
  • GetViewPath Method (CRViewer Object)
  • PrintReport Method (CRViewer Object)
  • Refresh Method (CRViewer Object)
  • SearchByFormula Method (CRViewer Object)
  • SearchForText Method (CRViewer Object)
  • ShowFirstPage Method (CRViewer Object)
  • ShowGroup Method (CRViewer Object)
  • ShowLastPage Method (CRViewer Object)
  • ShowNextPage Method (CRViewer Object)
  • ShowNthPage Method (CRViewer Object)
  • ShowPreviousPage Method (CRViewer Object)
  • ViewReport Method (CRViewer Object)
  • Zoom Method (CRViewer Object)


ActivateView Method (CRViewer Object)

Use the ActivateView method to activate a particular view.

Syntax

Sub ActivateView ( Index )

Parameter

Parameter | Description
Index | The 1-based index number of the view that you want to activate.


AddView Method (CRViewer Object)

Use the AddView method to add a new view tab to the Viewer.

Syntax

Sub AddView ( GroupPath )

Parameter

Parameter | Description
GroupPath | GroupPath can be a colon-delimited string (Country:State:City) or a safe array of strings. It indicates the group for which you want to add a view (tab) to the Report Viewer window.


CloseView Method (CRViewer Object)

Use the CloseView method to close the specified view.

Syntax

Sub CloseView ( Index )

Parameter

Parameter | Description
Index | The 1- based index number of the view that you want to close.


GetCurrentPageNumber Method (CRViewer Object)

Use the GetCurrentPageNumber method to retrieve the number of the page of the report that is currently being viewed.

Syntax

Function GetCurrentPageNumber () As Long

Returns

Returns the current page number, if the call is successful.


GetViewName Method (CRViewer Object)

Use the GetViewName method to retrieve the current view's tab name and the current report document's name.

Syntax

Function GetViewName ( pTabName As String ) As String

Parameter

Parameter | Description
pTabName | Specifies the name of the current view (tab) As String.

Returns
  • Returns the current report's document name, if the call is successful.
  • Passes back the current view's tab name.


GetViewPath Method (CRViewer Object)

Use the GetViewPath method to retrieve the path to the current view. Path contains a safe array of strings. Views refer to the main Preview Tab and drill down tabs that appear in the Report Viewer as the user interacts with the report.

Syntax

Function GetViewPath ( Index As Integer )

Parameter

Parameter | Description
Index | Specifies the 1-based index number of the view (tab) displayed in the Report Viewer for which you want to retrieve the path.

Returns

Returns a safe array of strings indicating the path to the current view, if the call is successful.

Example

Use the following code as an example of how to use GetViewPath.

Dim vPath As Variant

Dim vString As String

Dim x As Integer

Dim y As Integer

Dim counter As Integer

vPath = CRViewer1.GetViewPath(userEnteredInteger)

x = Lbound(vPath)

y = Ubound(vPath)

For counter = x To y

If vString <> "" Then

vString = vString & ":"

End If

vString = vString & vPath(counter)

Next counter

ViewPathName.Caption = "View path is: " & vString


PrintReport Method (CRViewer Object)

Use the PrintReport method to initiate printing of the report in the current view.

Syntax

Sub PrintReport ()


Refresh Method (CRViewer Object)

Use the Refresh method to reload and display the report displayed in the Report Viewer from its original source.

Syntax

Sub Refresh ()


SearchByFormula Method (CRViewer Object)

Use the SearchByFormula method to search using the specified formula. The Search GUI is displayed if parameter formula is empty.

Syntax

Sub SearchByFormula ( formula As String )

Parameter

Parameter | Description
formula | Specifies the formula that you want to use for the search As String.


SearchForText Method (CRViewer Object)

Use the SearchForText to search for the specified String.

Syntax

Sub SearchForText ( Text As String )

Parameter

Parameter | Description
Text | Specifies the text that you want to search for As String.


ShowFirstPage Method (CRViewer Object)

Use the ShowFirstPage method to display the first page of the report.

Syntax

Sub ShowFirstPage ()


ShowGroup Method (CRViewer Object)

Use the ShowGroup method to display the indicated group in the current view. GroupPath can be a colon-delimited string (Country:State:City) or a safe array of strings.

Syntax

Sub ShowGroup (GroupPath)

Parameter

Parameter | Description
GroupPath | Specifies the path to the group that you want to display. Use a safe array of strings or a colon delimited string (for example, Canada:BC:Vancouver).


ShowLastPage Method (CRViewer Object)

Use the ShowLastPage method to display the last page of the report.

Syntax

Sub ShowLastPage ()


ShowNextPage Method (CRViewer Object)

Use the ShowNextPage method to display the next page of the report.

Syntax

Sub ShowNextPage ()


ShowNthPage Method (CRViewer Object)

Use the ShowNthPage method to display the specified page of the report.

Syntax

Sub ShowNthPage ( PageNumber As Integer )

Parameter

Parameter | Description
PageNumber | The page number that you want to display As Integer.


ShowPreviousPage Method (CRViewer Object)

Use the ShowPreviousPage method to display the previous page of the report.

Syntax

Sub ShowPreviousPage ()


ViewReport Method (CRViewer Object)

Use the ViewReport method to display the report.

Syntax

Sub ViewReport ()


Zoom Method (CRViewer Object)

Use the Zoom method to change the magnification used to display the report.

Syntax

Sub Zoom ( ZoomLevel As Integer )

Parameter

Parameter | Description
ZoomLevel | The zoom level to use to view the report As Integer. Indicate a percentage, or use 1 to fit the entire width of the page in the Report Viewer window (but not the entire page) or 2 to fit the entire page in the window.


CRViewer Object Events

The following events are discussed in this section:

  • Clicked Event (CRViewer Object)
  • CloseButtonClicked Event (CRViewer Object)
  • DblClicked Event (CRViewer Object)
  • DownloadFinished Event (CRViewer Object)
  • DownloadStarted Event (CRViewer Object)
  • DrillOnDetail Event (CRViewer Object)
  • DrillOnGraph Event (CRViewer Object)
  • DrillOnGroup Event (CRViewer Object)
  • DrillOnSubreport Event (CRViewer Object)
  • ExportButtonClicked Event (CRViewer Object)
  • FirstPageButtonClicked Event (CRViewer Object)
  • GoToPageNClicked Event (CRViewer Object)
  • GroupTreeButtonClicked Event (CRViewer Object)
  • HelpButtonClicked Event (CRViewer Object)
  • LastPageButtonClicked Event (CRViewer Object)
  • NextPageButtonClicked Event (CRViewer Object)
  • OnReportSourceError Event (CRViewer Object)
  • PrevPageButtonClicked Event (CRViewer Object)
  • PrintButtonClicked Event (CRViewer Object)
  • RefreshButtonClicked Event (CRViewer Object)
  • SearchButtonClicked Event (CRViewer Object)
  • SearchExpertButtonClicked Event (CRViewer Object)
  • SelectionFormulaBuilt Event (CRViewer Object)
  • SelectionFormulaButtonClicked Event (CRViewer Object)
  • ShowGroup Event (CRViewer Object)
  • StopButtonClicked Event (CRViewer Object)
  • ViewChanged Event (CRViewer Object)
  • ViewChanging Event (CRViewer Object)
  • ZoomLevelChanged Event (CRViewer Object)


Clicked Event (CRViewer Object)

The Clicked event occurs when an object in the viewer is clicked.

Syntax

Event Clicked ( x As Long, y As Long, EventInfo, UseDefault As Boolean )

Parameters

Parameter | Description
X | Long. The X coordinate of the object clicked.
Y | Long. The Y coordinate of the object clicked.
EventInfo | A CRVEventInfo Object (CRVIEWERLib) containing information about the object clicked.
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


CloseButtonClicked Event (CRViewer Object)

The CloseButtonClicked event occurs when the Close Current View button is clicked.

Syntax

Event CloseButtonClicked ( UseDefault As Boolean )

Parameter

Parameter | Description
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


DblClicked Event (CRViewer Object)

The DblClicked event occurs when an object is double clicked.

Syntax

Event DblClicked ( x As Long, y As Long, EventInfo, UseDefault As Boolean )

Parameters

Parameter | Description
X | Long. The X coordinate of the object that was double clicked.
Y | Long. The Y coordinate of the object that was double clicked.
EventInfo | A CRVEventInfo Object (CRVIEWERLib) containing information about the object clicked.
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


DownloadFinished Event (CRViewer Object)

The DownloadFinished event occurs when report data finishes loading into the report. For example, if the user displays a new page, a new set of report data is downloaded.

Syntax

Event DownloadFinished ( loadingType As CRLoadingType )

Parameter

Parameter | Description
LoadingType | CRLoadingType (CRViewerLib). Indicates the type of data being loaded into the Report Viewer.


DownloadStarted Event (CRViewer Object)

The DownloadStarted event occurs when report data starts being downloaded into the Report Viewer. For example, if the user displays a new page, a new set of report data is downloaded.

Syntax

Event DownloadStarted ( loadingType As CRLoadingType )

Parameter

Parameter | Description
LoadingType | CRLoadingType (CRViewerLib). Indicates the type of data being loaded into the Report Viewer.


DrillOnDetail Event (CRViewer Object)

The DrillOnDetail event occurs when you drill down on a field in the Detail section of the report. This event is not available in the current version of the Report Viewer, but will be enabled in a future upgrade.

Syntax

Event DrillOnDetail ( FieldValues, SelectedFieldIndex As Long,

UseDefault As Boolean )

Parameters

Parameter | Description
FieldValues | An array of objects containing details on the field.
SelectedFieldIndex | Long. The array index of the value in the field actually drilled on.
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


DrillOnGraph Event (CRViewer Object)

The DrillOnGraph event occurs when you drill down on a graph.

Syntax

Event DrillOnGraph ( PageNumber As Long, x As Long, y As Long,

UseDefault As Boolean )

Parameters

Parameter | Description
PageNumber | Long. The page number of the report containing the graph where the event occurred.
x | Long. The X coordinate of the graph that was drilled on.
y | Long. The Y coordinate of the graph that was drilled on.
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


DrillOnGroup Event (CRViewer Object)

The DrillOnGroup event occurs when drilling down (double-clicking) on a group field viewer window.

Syntax

Event DrillOnGroup ( GroupNameList, DrillType As CRDrillType,

UseDefault As Boolean )

Parameters

Parameter | Description
GroupNameList | An array containing all group names for the group drilled on.
DrillType | CRLoadingType (CRViewerLib). Specifies what type of object the drill event occurred on (for example, graph, group tree, map).
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


DrillOnSubreport Event (CRViewer Object)

The DrillOnSubreport event occurs when drilling down (double-clicking) on a subreport.

Syntax

Event DrillOnSubreport ( GroupNameList, SubreportName As String,

Title As String, PageNumber As Long,

Index As Long, UseDefault As Boolean )

Parameters

Parameter | Description
GroupNameList | An array containing all group names for the group drilled on.
SubreportName | String. Indicates the name of the subreport that was drilled on.
Title | String. Indicates the title of the subreport that was drilled on.
PageNumber | Long. Indicates the page number that the event occurred on.
Index | Long. Indicates the index of the subreport that was drilled on.
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


ExportButtonClicked Event (CRViewer Object)

The ExportButtonClicked event occurs when the Export button is clicked.

Syntax

Event ExportButtonClicked ( UseDefault As Boolean )

Parameter

Parameter | Description
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


FirstPageButtonClicked Event (CRViewer Object)

The FirstPageButtonClicked event occurs when the button which navigates through the report to the first page is clicked.

Syntax

Event FirstPageButtonClicked ( UseDefault As Boolean )

Parameter

Parameter | Description
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


GoToPageNClicked Event (CRViewer Object)

The GoToPageNClicked event occurs when a user requests and goes to a specific page in the report.

Syntax

Event GoToPageNClicked ( UseDefault As Boolean, PageNumber As Integer )

Parameters

Parameter | Description
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.
PageNumber | Integer. The page number of the page that is to be displayed.


GroupTreeButtonClicked Event (CRViewer Object)

The GroupTreeButtonClicked event occurs when the Group Tree button is clicked to show/hide the Group Tree in the viewer window.

Syntax

Event GroupTreeButtonClicked ( Visible As Boolean )

Parameter

Parameter | Description
Visible | Boolean. Indicates whether or not the Group Tree is now visible.


HelpButtonClicked Event (CRViewer Object)

The HelpButtonClicked event occurs when the Help button is clicked.

Syntax

Event HelpButtonClicked ()


LastPageButtonClicked Event (CRViewer Object)

The LastPageButtonClicked event occurs when the button which navigates through the report to the last page is clicked.

Syntax

Event LastPageButtonClicked ( UseDefault As Boolean )

Parameter

Parameter | Description
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


NextPageButtonClicked Event (CRViewer Object)

The NextPageButtonClicked event occurs when the button which navigates through the report to the next page is clicked.

Syntax

Event NextPageButtonClicked ( UseDefault As Boolean )

Parameter

Parameter | Description
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


OnReportSourceError Event (CRViewer Object)

The OnReportSourceError event occurs when the report source (assigned to the CRViewer.ReportSource property) causes an error or cannot be loaded by the Report Viewer.

Syntax

Event OnReportSourceError ( errorMsg As String,

errorCode As Long, UseDefault As Boolean )

Parameters

Parameter | Description
errorMsg | String. Indicates the error message.
errorCode | Long. Indicates the code or ID for the error.
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


PrevPageButtonClicked Event (CRViewer Object)

The PrevPageButtonClicked event occurs when the button which navigates through the report to the previous page is clicked.

Syntax

Event PrevPageButtonClicked ( UseDefault As Boolean )

Parameter

Parameter | Description
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


PrintButtonClicked Event (CRViewer Object)

The PrintButtonClicked event occurs when the Print button is clicked.

Syntax

Event PrintButtonClicked ( UseDefault As Boolean )

Parameter

Parameter | Description
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


RefreshButtonClicked Event (CRViewer Object)

The RefreshButtonClicked event occurs when the Refresh button is clicked.

Syntax

Event RefreshButtonClicked ( UseDefault As Boolean )

Parameter

Parameter | Description
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


SearchButtonClicked Event (CRViewer Object)

The SearchButtonClicked event occurs when the Search button is clicked.

Syntax

Event SearchButtonClicked ( searchText As String, UseDefault As Boolean )

Parameters

Parameter | Description
searchText | String. Indicates the data being searched for.
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


SearchExpertButtonClicked Event (CRViewer Object)

The SearchExpertButtonClicked event occurs when the Search Expert button is clicked.

Syntax

Event SearchExpertButtonClicked ( UseDefault As Boolean )

Parameter

Parameter | Description
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


SelectionFormulaBuilt Event (CRViewer Object)

The SelectionFormulaBuilt event occurs when a new selection formula is assigned to the report. This event is not valid when the Report Viewer is used in conjunction with the Report Designer Component.

Syntax

Event SelectionFormulaBuilt (

selctionFormula As String, UseDefault As Boolean )

Parameters

Parameter | Description
selectionFormula | String. Indicates the new selection formula assigned to the report.
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


SelectionFormulaButtonClicked Event (CRViewer Object)

The SelectionFormulaButtonClicked event occurs when the Selection Formula button in the Report Viewer is clicked. This is not valid when the Report Viewer is assigned a report source produced by the Report Designer Component.

Syntax

Event SelectionFormulaButtonClicked (

selctionFormula As String, UseDefault As Boolean )

Parameters

Parameter | Description
selectionFormula | String. The current selection formula that will be replaced.
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


ShowGroup Event (CRViewer Object)

The ShowGroup event occurs when you click a group in the Group Tree.

Syntax

Event ShowGroup ( GroupNameList, UseDefault As Boolean )

Parameters

Parameter | Description
GroupNameList | An array containing all group names for the group selected.
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


StopButtonClicked Event (CRViewer Object)

The StopButtonClicked event occurs when the user clicks the Stop button in the Report Viewer, forcing the Viewer to stop loading data from the report source.

Syntax

Event StopButtonClicked (

loadingType As CRLoadingType, UseDefault As Boolean )

Parameters

Parameter | Description
loadingType | CRLoadingType (CRViewerLib). Indicates what was being loaded into the Report Viewer when the Stop button was clicked.
UseDefault | Boolean. Indicates whether or not the default action of the event will be performed.


ViewChanged Event (CRViewer Object)

The ViewChanged event occurs after the view in the Report Viewer has changed. Views refer to the main Preview Tab and drill down tabs that appear in the Report Viewer as the user interacts with the report.

Syntax

Event ViewChanged ( oldViewIndex As Long, newViewIndex As Long )

Parameters

Parameter | Description
oldViewIndex | Long. An index referring to the view the user switched from.
newViewIndex | Long. An index referring to the view the user switched to.


ViewChanging Event (CRViewer Object)

The ViewChanging event occurs when there has been a request for the view in the Report Viewer to change. Views refer to the main Preview Tab and drill down tabs that appear in the Report Viewer as the user interacts with the report.

Syntax

Event ViewChanging ( oldViewIndex As Long, newViewIndex As Long )

Parameters

Parameter | Description
oldViewIndex | Long. An index referring to the view the user is switching from.
newViewIndex | Long. An index referring to the view the user is switching to.


ZoomLevelChanged Event (CRViewer Object)

The ZoomLevelChanging event occurs when the zoom level of the Report Viewer is changed.

Syntax

Event ZoomLevelChanged ( ZoomLevel As Integer )

Parameter

Parameter | Description
ZoomLevel | Integer. A value indicating the new zoom level percentage.


CRVTrackCursorInfo Object (CRVIEWERLib)

The CRVTrackCursorInfo object contains information about the types of mouse cursors displayed while the user interacts with the report in the Report Viewer. This object corresponds to the TrackCursorInfo property in the CRViewer Object (CRVIEWERLib).

CRVTrackCursorInfo Object Properties

Property | Description | Read/Write
DetailAreaCursor | CRTrackCursor (CRViewerLib). Gets or sets the DetailAreaCursor type. | Read/Write
DetailAreaFieldCursor | CRTrackCursor (CRViewerLib). Gets or sets the DetailAreaFieldCursor type. | Read/Write
GraphCursor | CRTrackCursor (CRViewerLib). Gets or sets the GraphCursor type. | Read/Write
GroupAreaCursor | CRTrackCursor (CRViewerLib). Gets or sets the GroupAreaCursor type. | Read/Write
GroupAreaFieldCursor | CRTrackCursor (CRViewerLib). Gets or sets the GroupAreaFieldCursor type. | Read/Write


WebReportBroker Object (CRWEBREPORTBROKERLib)

The WebReportBroker object is used internally by the Report Viewer to access web servers. In most applications, developers will not need to access this object directly.


WebReportSource Object (CRWEBREPORTBROKERLib)

The WebReportSource object contains information and methods related to the display of a report by the Report Viewer.

WebReportSource Object Properties

Property | Description | Read/Write
ImageType | Reserved. Do not use in current development. Gets or sets the image type. | Read/Write
PromptOnRefresh | Boolean. Gets or sets the prompt mode. If TRUE, the user will be prompted for new information each time the Report Viewer displays the report. If FALSE, the user will not get a prompt and the information provided with the previous prompt will be used, unless the server requires new information. | Read/Write
ReportSource | Unknown. Gets or sets the report source for the WebReportBroker. | Read/Write
Title | String. Gets or sets the report title that can be displayed in viewer. | Read/Write
URL | String. Gets or sets the URL source for the report. | Read/Write


WebReportSource Object Methods

The following methods are discussed in this section:

  • AddParameter Method (WebReportSource Object)
  • AddParameterEx Method (WebReportSource Object)


AddParameter Method (WebReportSource Object)

Use the AddParameter method to pass additional information for setting values for prompts in code as an alternative to prompting user to provide it. For example, you can provide user information which the server might request, rather than prompting the user to enter the information at runtime.

Syntax

Sub AddParameter ( tag As String, value As String )

Parameters

Parameter | Description
tag | String. Specifies the prompt for which you want to pass a value.
value | String. Specifies the response string that you want to provide.


AddParameterEx Method (WebReportSource Object)

AddParameterEx method is not implemented for the current release. This method will allow you to pass more information than AddParameter Method, which should be used at this time.


Enumerated Types—Report Viewer

The following enumerated types of the Report Viewer Object Model are discussed in this section:

  • CRLoadingType (CRViewerLib)
  • CRFieldType (CRViewerLib)
  • CRLoadingType (CRViewerLib)
  • CRObjectType (CRViewerLib)
  • CRTrackCursor (CRViewerLib)


CRDrillType (CRViewerLib)

Constant | Value
crDrillOnGraph | 2
crDrillOnGroup | 0
crDrillOnGroupTree | 1
crDrillOnMap | 3
crDrillOnSubreport | 4


CRFieldType (CRViewerLib)

Constant | Value
crBoolean | 5
crCurrency | 4
crDate | 6
crDateTime | 8
crInt16 | 1
crInt32 | 2
crInt8 | 0
crNumber | 3
crString | 9
crTime | 7
crUnknownFieldType | 255


CRLoadingType (CRViewerLib)

Constant | Value
LoadingNothing | 0
LoadingPages | 1
LoadingQueryInfo | 3
LoadingTotaller | 2


CRObjectType (CRViewerLib)

Constant | Value
crBitmap | 103 (&H67)
crBlob | 104 (&H68)
crBox | 106 (&H6A)
crCrossTab | 110 (&H6E)
crCrosstabChart | 108 (&H6C)
crCrosstabMap | 115 (&H73)
crDatabaseFieldType | 1
crDetailChart | 109 (&H6D)
crDetailMap | 116 (&H74)
crDetailSection | 202 (&HCA)
crFormulaFieldType | 5
crGraphic | 111 (&H6F)
crGroupChart | 107 (&H6B)
crGroupFooterSection | 201 (&HC9)
crGroupHeaderSection | 200 (&HC8)
crGroupMap | 114 (&H72)
crGroupNameFieldType | 8
crLine | 105 (&H69)
crOLAPChart | 113 (&H71)
crOLAPCrossTabFieldType | 4
crOLAPDataFieldType | 3
crOLAPDimensionFieldType | 2
crOLAPMap | 117 (&H75)
crOLEObject | 101 (&H65)
crOOPSubreport | 112 (&H70)
crPageFooterSection | 206 (&HCE)
crPageHeaderSection | 205 (&HCD)
crPromptingVarFieldType | 9
crReportFooterSection | 204 (&HCC)
crReportHeaderSection | 203 (&HCB)
crSpecialVarFieldType | 7
crSubreport | 102 (&H66)
crSummaryFieldType | 6
crText | 100 (&H64)
crUnknownFieldDefType | 0


CRTrackCursor (CRViewerLib)

Constant | Value
crAppStartingCursor | 12
crArrowCursor | 1
crCrossCursor | 2
crDefaultCursor | 0
crHelpCursor | 13
crIBeamCursor | 3
crMagnifyCursor | 99
crNoCursor | 10
crWaitCursor | 11


The Report Viewer/Java Bean technical reference

The following Properties, Methods, and Events are discussed in this section:

  • The Report Viewer/Java Bean Properties
  • The Report Viewer/Java Bean Methods
  • The Report Viewer/Java Bean Events


The Report Viewer/Java Bean Properties

The Report Viewer Bean properties may have one or more of the characteristics listed below:

  • read: you can get the current value.
  • write: you can set the value.
  • bound: you can get a notification every time the value changes.
  • constrained: you can veto a request to change the value.

    • Property | Description | Read(r), Write(w), Bound(b), Constrained(c)
busy | Boolean. True if the ReportViewer is currently processing a command initiated by user action, method call, or property change. | r, b
canCloseCurrentView | Boolean. True if the current views tab can be closed. The initial ("Preview") tab cannot be closed. Refer to method closeCurrentView. | r,b
canDrillDown | Boolean. True if drill-down views can be opened. Normally, clicking on a hidden group in the group tree (indicated by a magnifying glass icon next to the group name) or double-clicking on a chart or map or group section in the page will open a drill-down view. | r,w,b,c
currentMessage | String. The message currently displayed in the status area of the toolbar. | r,b
currentPageNumber | Integer. The number of the page currently being viewed. | r,b
currentTip | String. The "tool tip" currently displayed in the status area of the toolbar. Tool tips temporarily override any message in the status area. | r,b
currentViewName | String. The name of the view whose tab is selected. | r,b
exportingPossible | Boolean. False if exporting is not possible because the user has denied the bean permission to write to the local disk. | r
hasExportButton | Boolean. True if the Export button can be made visible in the toolbar. If exporting is not possible (refer to property exportingPossible), requests to set this property to True will be vetoed. | r,w,b,c
hasGroupTree | Boolean. If set to True then the GroupTree toggle button is made visible in the toolbar and the GroupTree can be displayed (refer to property showGroupTree). | r,w,b,c
hasPrintButton | Boolean. If True then the Print button will be visible in the toolbar. If printing is not possible (refer to property printingPossible) then requests to set this property to True will be vetoed. | r,w,b,c
hasRefreshButton | Boolean. If True then the Refresh button is visible in the toolbar. | r,w,b,c
hasToolBar | Boolean. If True then the toolbar is visible. | r,w,b,c
hasTextSearchControls | Boolean. If True then the Text Search field and the Find Next button are visible in the toolbar. | r,w,b,c
language | String. Contains the 2 letter international Standard code for the language to be used for the user interface. Languages currently supported are: English -- en French -- fr German -- de Japanese -- ja Italian -- it Spanish -- es Portuguese -- pt | r,w,b,c
lastPageNumber | Integer. Indicates to the highest numbered page currently available in the report. This may or may not be the final page. (refer to property lastPageNumberKnown). | r,b
lastPageNumberKnown | Boolean. True if the number of the final page in the report is known. If False then there are more pages in the report than the lastPageNumber property indicates. | r,b
printingPossible | Boolean. True if printing is possible. If False then either the Java implementation doesn't support it or the user has denied the bean permission to print. | r
reportName | String. The URL of the report to be viewed. For example: http://server_name/report_dir/report.rpt Setting this property causes the ReportViewer to request page 1 of the report from the server. | r,w,b,c
searchText | String. Contains the text most recently searched for, or the text being typed by the user int to the Text Search field in the toolbar. | r,b
selectionFormula | String. The current selection formula to be used for subsequent commands. The formula is expressed in the Crystal Reports formula language. Setting this property closes all views except the initial one (the "Preview" view), discards all information cached for the report, and re-requests the current page of the report. | r,w,b,c
showGroupTree | Boolean. If True and the hasGroupTree property is True then the GroupTree will be visible. | r,w,b,c


The Report Viewer/Java Bean Methods

Each of the methods in the Report Viewer Bean starts what may be a lengthy operation, and they return to the caller before that operation is complete. If it is important to know when the command begun by one of these methods is finished, the calling code should watch for the associated events or property change notifications.

Generally there will be a time delay between the method call returning and the associated event being fired or the property changing. In fact, there may be a delay in beginning the command if the report viewer is busy processing a previous command. Commands are begun strictly one at a time in the order they are generated although, once begun, they may be processed in parallel in different threads.

The events and property change notifications will be given to the calling code on a different thread from the one that made the method call.

Click the appropriate link to jump to that section:

  • closeCurrentView
  • exportView
  • printView
  • refreshReport
  • searchForText
  • showLastPage
  • showPage
  • stopAllCommands


closeCurrentView

If the canCloseCurrentView property is True, closes the current view. Equivalent to the Close button in the toolbar. A viewClosed and a viewActivated event are fired. The currentViewName property is changed.

Syntax

void closeCurrentView ()


exportView

If the exportingPossible property is True, requests the report from the server in the indicated format and writes it to the local disk. Similar to the Export button in the toolbar.

Syntax

void exportView ( int exportFormat, File destinationFile )

Parameters

exportFormat | Specifies the format in which the requested report should appear.
 | Constant | Value
 | toHTML | 0
 | toCrystalReport | 1
 | toMSWord | 2
 | toMSExcel | 3
destinationFile | Complete pathname of the destination file.


printView

If the printingPossible property is True, prints all pages in the current view, requesting them from the server if necessary. Equivalent to the Print button in the toolbar.

Syntax

void printView ()


refreshReport

Closes all views except the initial one (the "Preview" view), discards all information cached for the report, and re-requests the current page of the report.

Syntax

void refreshReport ()


searchForText

Displays the next occurrence of the indicated text in the report output. Equivalent to the text search field in the toolbar. Currently, the second and third parameters are ignored; the search is always forward and case-insensitive. The searchText property is changed.

Syntax

void searchForText ( String searchString, boolean forwardSearch,

boolean caseSensitive )

Parameters

searchString | The string for which you want to search.
forwardSearch | This parameter is ignored.
caseSensitive | This parameter is ignored.


showLastPage

Shows the last page of the report, requesting it from the server if necessary. Equivalent to the Last Page button in the toolbar. The lastPageNumber and lastPageNumberKnown properties may be changed.

Syntax

void showLastPage ()


showPage

Displays the indicated page, requesting it from the server if necessary. Equivalent to the page number field in the toolbar. The currentPageNumber property is changed.

Syntax

void showPage ( int pageNumber )

Parameter

pageNumber

Number of the page to be displayed.


stopAllCommands

Cancels all unfinished commands. Equivalent to the Stop button in the toolbar.

Syntax

void stopAllCommands ()


The Report Viewer/Java Bean Events

There are 2 event classes defined by the Report Viewer Bean and discussed in this section: class ViewChangeEvent and class ServerRequestEvent.

Click the appropriate link to jump to that section:

  • ServerRequestEvent
  • ViewChangeEvent


ServerRequestEvent

Description | Properties | ListenerInterface Methods
Indicates a request has been sent to the server owning the current report. | string ServerURL string Parameter | requestStarted(event e) requestEnde(event e)


ViewChangeEvent

Description | Properties | ListenerInterface Methods
Indicates that a view has changed. | string viewName | viewOpened(event e) viewActivated(event e) viewClosed(event e)


Embeddable Crystal Reports Designer Control Object Model

The Embeddable Crystal Reports Designer Control (Embeddable Designer) is a new addition to the Report Designer Component as of version 9; it enables you to provide a Crystal Reports designer in your application. In this section, you will find a general overview of the control as well as detailed information on its properties and methods.

Click the appropriate link to jump to that section:

  • Overview of the Embeddable Designer
  • Application development with the Embeddable Designer
  • Distributing the Embeddable Designer
  • Properties and methods of the Embeddable Designer


Overview of the Embeddable Designer

Your users can now design or edit reports at runtime with the Embeddable Designer. This easy-to-use ActiveX control provides the full power of Crystal Reports to your application. The control is placed on a form, or in a container within the form, and displays a new or existing report in design mode. This presents the user with an interactive environment in which to design or edit the report. The Embeddable Designer allows users to:

  • Add data sources.
  • Add database fields.
  • Create and add formulas.
  • Create and add parameters.
  • Group data.
  • Summarize data.
  • Add charts.
  • Add subreports.
  • Add special fields.
  • Format fields and sections.


Application development with the Embeddable Designer

The Embeddable Designer is an ActiveX control that can be added to any development environment that supports ActiveX. Using Microsoft Visual Basic, Microsoft Visual C++, Delphi, and Borland C++, you can now add a Crystal Reports designer to your application with minimal code.

As a standard component, the Embeddable Designer not only exposes several properties at design time, but also provides a complete set of properties, methods, and events that can be programmed at runtime. An application using the Embeddable Designer will consist of three components. These three components allow the user to create, design, preview, print, export, and save their reports.

  • The Embeddable Designer, also known as the Embeddable Crystal Reports Designer Control Library 11.0 (Crdesignerctrl.dll), is a front-end user interface for designing or editing new or existing reports. See Programming the Embeddable Crystal Reports Designer Control for tutorials on creating applications with the Embeddable Designer.
  • The Automation Server, also known as the Crystal Reports ActiveX Designer Design and Runtime Library 11.0 (Craxddrt.dll), is an extensive object model with hundreds of properties and methods that you can use to program a report. See Report Designer Component Object Model for more information.

    • Note: The Craxddrt.dll must only be used in a client-side application. See Unification of the RDC object model for more information.

  • The Report Viewer, also known as the Crystal Reports Viewer Control (Crviewer.dll), is a front-end user interface for viewing reports. See Programming the Crystal Report Viewers for more information.


Distributing the Embeddable Designer

Distribution of an application consists of three main DLLs: Crdesignerctrl.dll, Craxddrt.dll, and Crviewer.dll. In addition to these main DLLs, you will need to distribute the standard runtime files, including database DLLs and export DLLs. The additional DLLs you distribute will vary depending on your application. For more information on standard runtime files, refer to the Crystal Reports Developer Runtime Help (Runtime.hlp).

Note: The Embeddable Designer is not royalty free; it requires licensing. For more information on licensing, refer to the License Manager Help (License.hlp).

Providing online help for the Embeddable Designer

Although online help for designing reports at runtime in the Embeddable Designer is not provided, you can provide your own online help to your users. The Embeddable Designer has access to online help through the Help button on the main toolbar and through the Help command in the shortcut menu. By default, the Embeddable Designer will disable the Help menu. You can enable or disable the Help button and hide the Help menu through the EnableHelp property (Microsoft Visual Basic) or the put_EnableHelp function (Microsoft Visual C++). To set your help file to the Embeddable Designer, create the following registry subkey:

Key Name

HKEY_LOCAL_MACHINE\SOFTWARE\Business Objects\Suite 11.0\Report Designer Component\

Value Name

VBDesignerHelpPath

Value Data

Provide the full path and name of your help file here.

The Embeddable Designer uses the WinHelp function to start Microsoft Windows Help. The following table lists the various help options available and the UCommand used in the WinHelp function based on the help option selected. Keep this in mind when creating your online help.

Option Location | UCommand
Menu: Help > Crystal Reports Help | HELP_INDEX
Menu: Help > Search | HELP_FINDER
Menu: Help > Using Help | HELP_HELPONHELP
Toolbar: Help | HELP_INDEX

For a complete description of the WinHelp function see "WinHelp Shell and Common Controls: Platform SDK" in the Microsoft Developer Network (MSDN).


Properties and methods of the Embeddable Designer

In Microsoft Visual Basic, the properties of the Embeddable Designer are Read/Write. In Microsoft Visual C++, the corresponding functions will have Set and Get prefixed to the property name. Set writes to the property, and Get reads from the property. Methods and events have the same names in both environments.

Note: Only the properties and methods of the CCRDesignerCtrl class (main class for the Embeddable Designer) are included. Information on properties, methods, and events for the base classes can be found in the Microsoft Developer Network (MSDN).

Microsoft Visual Basic example

Dim bShowGrid As Boolean

' Get the value of the DisplayGrid property

bShowGrid = CRDesignerCtrl1.DisplayGrid

' If the Grid is displayed Set the DisplayGrid

' property to False

If bShowGrid Then CRDesignerCtrl1.DisplayGrid = False

Microsoft Visual C++ example

BOOL bShowGrid;

// Get the value for the DispalyGrid property

bShowGrid = m_Designer.GetDisplayGrid();

// If the Grid is displayed Set the DisplayGrid

// property to False

if(bShowGrid) m_Designer.SetDisplayGrid(FALSE);


Embeddable Designer (Properties)

Property | Data type and description | Read/Write
CaseInsensitiveSQLData | Boolean. Specifies whether or not to perform a case insensitive search for SQL data. | Read/Write
ConvertDateTimeType | CRConvertDateTimeType. Gets or sets the report option that specifies the format to be converted for date / time fields. | Read/Write
ConvertNullFieldToDefault | Boolean. Specifies whether or not to convert NULL parameter fields to their default values. | Read/Write
DisplayFieldView | Boolean. Gets or sets whether or not the field view is available. The field view is the list of available fields for the report, including Database, Formula, Parameter, Group Name, Running Total, Special, and Unbound fields. | Read/Write
DisplayGrid | Boolean. Gets or sets whether or not the grid is displayed. | Read/Write
DisplayHiddenSections | Boolean. Gets or sets whether or not a section is available when hidden. | Read/Write
DisplayRulers | Boolean. Gets or sets whether or not the Ruler is available. | Read/Write
DisplayToolbar | Boolean. Gets or sets the visibility of the toolbar. | Read/Write
EnableHelp | Boolean. Gets or sets the availability of the help options. When True, the Help icon on the toolbar is enabled and the Help command is visible in the shortcut menu. When False, the Help Icon on the toolbar is disabled and the Help command is hidden in the shortcut menu. | Read/Write
EnableSnapToGrid | Boolean. Specifies whether or not to automatically align any fields you insert or to resize to the nearest grid coordinate. | Read/Write
GridSize | Single. Gets or sets the size of the grid in inches. Default value is 0.083. | Read/Write
ReportObject | ReportObject. Gets or sets the report object. | Read/Write
TranslateDosMemos | Boolean. Gets or sets the report option that indicates whether or not to translate DOS memos. | Read/Write
TranslateDosStrings | Boolean. Gets or sets the report option that indicates whether or not to translate DOS strings. | Read/Write
UseIndexForSpeed | Boolean. Gets or sets the "Use Indexes or Server for Speed" option during record selection report option. | Read/Write
VerifyOnEveryPrint | Boolean. Gets or sets the report option that indicates whether or not to verify the database every time the report is run. | Read/Write


Embeddable Designer (Methods)

SaveReport Method

Use the SaveReport method to the save the report to Crystal Reports format.

Syntax

Sub SaveReport (ReportName as String)

Parameter

Parameter | Description
ReportName | Specifies the file path and name that you want to save the report to.

Remarks

If you open a report using the OpenReport Method (Application Object) setting the OpenMethod parameter to "1" (open temporary copy), you must save the report using the SaveAs Method (Report Object) rather than this method in order to avoid a runtime error.


Creating User-Defined Functions in C

Crystal Reports allows you to create User-Defined Functions that are recognized by the Crystal Reports Formula Editor. In this section you will find detailed information on programming User-Defined Functions in C.

Note: You can also use Java user defined function libraries. For details, see the Java Reporting Component Developer's Guide. (Note that the Java UFLs can only be used with CRW and the JRC.)

Click the appropriate link to jump to that section:

  • Overview of User-Defined Functions in C
  • Programming User-Defined Functions in C
  • Name of the function
  • Purpose of the function
  • Function data
  • Return types
  • Programming the UFL
  • Setting up a UFL project
  • Function definition
  • Returning user-defined errors
  • Obtaining parameter values from the parameter block
  • Picture function—a sample UFL function
  • Module Definition (.def) file
  • UFJOB modules
  • Implement InitJob and TermJob


Overview of User-Defined Functions in C

The Crystal Reports Formula Editor and formula language are powerful tools, enabling you to perform a wide variety of report-related tasks easily and efficiently. The formula language is expandable as well. That is, while it already includes a large selection of useful functions, it also comes with the ability to accept new functions that you define to meet your needs.

User-Defined Functions that are recognized by the Crystal Reports Formula Editor can be created in a Dynamic Link Library or in an Automation Server. This section demonstrates how to create User-Defined Functions in a Dynamic Link Library, the U25 DLL, using the C programming language.

Note:

  • The U25 DLLs work with Crystal Reports version 5 or later.
  • Existing U2L DLLs (the earlier version of the UFL DLL) can still be used.

For information on how to create User-Defined Functions in an Automation Server using Visual Basic, see Creating User-Defined Functions in Visual Basic.


Programming User-Defined Functions in C

You can add new functions to the Crystal Reports Formula Editor by:

  • Writing the functions using the C programming language.
  • Compiling and linking the functions into a User-Defined Function DLL called a UFL (User Function Library).

Note: If you are not familiar with programming Windows DLLs, refer to the Microsoft Windows Software Development Kit. Do not attempt to create a UFL if you do not understand Windows DLL programming.

When designing a new function for the Crystal Reports Formula Editor, you need to determine the following:

  • Name of the function
  • Purpose of the function
  • Function data

    • (The report data or user supplied data that the function will require.)

  • Return types

    • (The type of data that the function will return to the report.)


Name of the function

The name of the new function should reflect the function's purpose, making it easier to recognize when it appears in the Formula Editor's Functions list. For example, a function named "Picture" could let you specify a template picture of how data should appear in the report. If a field contains phone numbers, you can use the Picture function to specify that the data appear like this:

(xxx) xxx-xxxx

A resulting value from the phone number field would appear as follows:

(415) 555-1234

Function names must start with a letter, while all remaining characters in the name can be letters or numbers. The name can be up to 254 characters long, and it must be unique. That is, you cannot give a function a name that has been used for another Formula Editor function or UFL function, nor can it have a name that matches a standard C keyword (such as if, return, switch, or while).


Purpose of the function

You may find it helpful to start simply by "fleshing out" your function. Determine the purpose of the function and outline it on paper. Use C code or even pseudocode to determine how the function will perform the required operation. This step is important, as it will form the base information for every other step in the designing and programming of your UFL.


Function data

UFL functions are much like any other function you might create in C. They can accept values that are passed as parameters, and they return a value that is printed on the report. Once you have determined how a UFL function will perform a task, you will know exactly what kind of data it will require to complete that operation. The following table shows the data types that a UFL function can accept as a parameter, along with a description of what the parameter will look like in C.

Parameter Type (alphabetical) | C Data Type
Array (Boolean) | Pointer to a Boolean array.
Array (Currency) | Pointer to a number array.
Array (Date) | Pointer to a date array.
Array (DateTime) | Pointer to a date time array.
Array (Number) | Pointer to a number array.
Array(NumberToCurrency) | Pointer to a number array.
Array (String) | Pointer to a string array.
Array (Time) | Pointer to a time array.
Boolean | Short integer.
Currency | Double.
Date | Integer.
DateTime | Structure of two integers.
Number | Double.
NumberToCurrency | Double.
Range (Currency) | Structure containing two doubles.
Range (Date) | Structure containing two long integers.
Range (DateTime) | Structure containing two date time structures.
Range (Number) | Structure containing two doubles.
Range (NumberToCurrency) | Structure containing two doubles.
Range (String) | Structure containing pointers to two elements in a character array.
Range (Time) | Structure containing two integers.
RangeArray (Currency) | Pointer to a number range structure array.
RangeArray (Date) | Pointer to a date range structure array.
RangeArray (DateTime) | Pointer to a date time range structure array.
RangeArray (Number) | Pointer to a number range structure array.
RangeArray (NumberToCurrency) | Pointer to a number range structure array.
RangeArray (String) | Pointer to a string range structure array.
RangeArray (Time) | Pointer to a time range structure array.
String | Pointer to an array of characters.
Time | Integer.


Return types

Finally, you must determine what kind of data your function returns to the current report in Crystal Reports. The following table lists the possible UFL return types along with a description of the C data type used when programming the function.

Return Type (alphabetical) | C Data Type
Array (Boolean) | Pointer to a Boolean array.
Array (Currency) | Pointer to a number array.
Array (Date) | Pointer to a date array.
Array (DateTime) | Pointer to a date time array.
Array (Number) | Pointer to a number array.
Array (String) | Pointer to a string array.
Array (Time) | Pointer to a time array.
Boolean | Short integer.
Currency | Double.
Date | Long integer.
DateTime | Structure of two integers.
Number | Double.
Range (Currency) | Structure containing two doubles.
Range (Date) | Structure containing two long integers.
Range (DateTime) | Structure containing two date time structures.
Range (Number) | Structure containing two doubles.
Range (String) | Structure containing pointers to two elements in a character array.
Range (Time) | Structure containing two integers.
RangeArray (Currency) | Pointer to a number range structure array.
RangeArray (Date) | Pointer to a date range structure array.
RangeArray (DateTime) | Pointer to a date time range structure array.
RangeArray (Number) | Pointer to a number range structure array.
RangeArray (String) | Pointer to a string range structure array.
RangeArray (Time) | Pointer to a time range structure array.
String | Pointer to a character array.
Time | Integer.


Programming the UFL

After sketching out a new function, deciding on its parameters and data types, and determining the type of data the function will return to a report, you can begin programming the UFL.

A UFL is like any other DLL with a few simple differences:

  • Although the file is referred to as a "UFL" it must have a U25 prefix. For example, U25SAMP.DLL.
  • It must export your User-Defined Function (UDF) as a DLL function.
  • It must export a collection of other functions required by Crystal Reports.

You can design your UFL from scratch, but you may find the Helper modules, provided with Crystal Reports useful. If you use the helper modules provided, you will only need to create a single C code module, a Module Definition (.def) file, and an application project file. More experienced programmers may want to use these modules simply as a starting point to design more complex UFL features.

The "Picture" example

Code for the Picture function is provided as an example of a UFL. The purpose of this function is to display string type field data using a format specified by the user. For example, if the phone number is entered in the database table as "4155551234", the user can create the following formula:

Picture({table.PHONENUM}, "(xxx) xxx-xxxx")

The phone number will appear in the report as: (415) 555-1234

The code segments that appear in this section as examples use this Picture function. In addition, the complete code is listed in Picture function—a sample UFL function, later in the chapter.


Helper modules

Note: All information contained in this guide relating to the files listed below are maintained for backward compatibility. A currently supported solution for creating user-defined functions in C is available for download at http://support.businessobjects.com. Once you are at the site, search for "UFL".

You do not need to work with the actual code in any of these files, but they will have to be added to your UFL project. UFJOB.H and UFJOB.C are optional files providing job information for the current print job accessing the Formula Editor. For more information, see UFJOB modules.

File Name | Purpose
crdll.h | Defines primitives required by ufdll.h.
crdates.h | Declarations for functions to convert to and from Crystal Reports' date values.
crdates.c | Implementation of functions to convert to and from Crystal Reports' date values.
ufdll.h | Defines UFL enumerated, union, structure, and other data types.
ufuser.h | Prototypes of tables and functions user must implement.
ufmain.h | Prototypes of internal UFL functions implemented in UFMAIN.C.
uffuncs.h | Prototypes of functions that must be exported by the UFL to be used by Crystal Reports. These functions are implemented in UFMAIN.C.
ufmain.c | Implementation of UFL functions used internally and used by Crystal Reports when connecting to the UFL. This file also contains generic LibMain and WEP functions for Windows 3.x DLLs and a generic DllEntryPoint function for Win32 DLLs. (The LibMain, WEP, and DllEntryPoint functions are defined conditionally according to whether or not you are building a Win32 DLL. You do not need to make any changes to the code here).
ufjob.h | Optional file. Contains a definition of the JobInfo structure (see UFJOB modules, and prototypes of theInitForJob function, TermForJob function,) and FindJobInfo (see Implement InitJob and TermJob, implemented in UFJOB.C. structure and PROTOTYPES.C.)
ufjob.c | Optional file. Contains implementations of the required InitForJob function and TermForJob function. Also implements theFindJobInfo helper function.


Setting up a UFL project

Begin creating your UFL by setting up a new directory on your system to work in. Use File Manager or Windows Explorer to copy all of the files listed in the chart under Helper modules into your new directory. This ensures that you do not inadvertently edit or change the original files in your CRW directory.

Note: If you will not be using the functionality provided by UFJOB.H and UFJOB.C, you do not need to copy these files into your working directory.

Open Microsoft Visual Studio and create a new project file. Name the new project file with a U25 prefix. For example, U25Funcs.dsp. Make sure the project is set to build a DLL (not a Windows EXE) file.

Note: If you are building a User Function Library, make sure you set Struct Member Alignment for the project to 1 byte. Crystal Reports for Win32 will not be able to use your UFL otherwise. To find out how to change the Struct Member Alignment setting for your project, refer to the documentation for your development environment.

Finally, add the UFMain.c file to your project, and save the project in your new working directory. Add the UFJOB.C file as well if you are using this file. You are now ready to begin creating a new UFL for the Crystal Reports Formula Editor.

UFL states

To keep a report section together during an operation (for instance, formatting) Crystal Reports sometimes needs to roll back to the last consistent point—perhaps the end of the last section that fits completely on a page. Crystal Reports accomplishes this by saving and then restoring state information, including UFL states. A UFL state consists of the global information maintained by the UFL and modified by its functions. The UFL generates its state as a binary stream. An example is a UFL that implements a running total. It would have the running total, a function to reset the total to zero, another to increment it, and a third to retrieve its current value. That running total is the UFL's state and the first two functions mutate it. For the Crystal Reports Print Engine to produce consistent results, the UFL must implement the save and restore functions, UF5SaveState and UF5RestoreState. To save the UFL state at particular points in time, Crystal Reports calls UF5SaveState to obtain the current state from the UFL. Later, Crystal Reports calls UF5RestoreState to restore the UFL state to its saved values.

Note: As the developer, it is your responsibility to ensure that the type of state information saved can be restored correctly. For example, pointers representing memory addresses should not be part of the UFL state data. The UFL state is serialized and stored in a report so if that report is opened on another machine, the pointers will be invalid. You should also consider whether the report will be opened on different platforms. In this case, the UFL functions that save and restore its state should be platform-aware. For example, an integer is stored by a Pentium III using little-endian representation, while the same integer is stored by a SPARC using big-endian representation. It is the UFL's responsibility to interpret the meaning of the binary stream and to insure its integrity: the UFL must ensure that little-endian order is always used, regardless of the platform's native byte order.


Function definition

Creating a UFL function requires that you create only one more C code module and a module definition (.def) file in addition to the Helper modules. (Your particular UFL Function needs may require more modules, but the simplest method for creating a UFL requires creating only these two.) For information on creating the module definition file, see Module Definition (.def) file. To begin building your UFL, create a new C module in your Visual Studio, and save it to your working directory with the same name as your project file. For example, if your project file is named U25samp.mak or U25Funcs.dsp, you would name your C module U25Samp.C or U25Funcs.C. This demonstration will refer to UFLSamp.C. This is the "private" C module for your UFL because it is the one section of code that must be unique to your UFL.

The first step to programming your UFL's private C code module is to #include the appropriate header files:

  • #include <windows.h>
  • #include "ufdll.h"
  • #include "ufmain.h"
  • #include "ufuser.h"

You do not need to #include the UFFUNCS.H header file that you also copied into your working directory. This file is already #included by UFMAIN.C, and you will not be directly calling any of the functions defined in these files (though they are necessary for Crystal Reports when the Formula Editor accesses your UFL).

The private C code module of your UFL requires several parts:

  • Function definition table
  • Function definition table example
  • Function templates table
  • Function examples table
  • Error table
  • InitForJob function
  • TermForJob function
  • UFL function implementation

Most of these sections have specific guidelines that must be used and that are the same for every function you add to your UFL. Your UFL function implementation is completely designed and programmed by you. It is the functionality that you are adding to the Crystal Reports Formula Editor.


Function definition table

You must supply a definition for each function that you want to add to Crystal Reports. Each entry in the function definition table consists of a definition string that specifies:

  • The return type.
  • The function name.
  • An argument list (showing the required order in which arguments are to be entered and the data type of each argument).
  • The name of the new UFL C/C++ function that implements the call (that is, the function for which this entry is being written).
  • The name of the C/C++ function that implements the memory calculation call or NULL if this function is not available.
  • A Boolean value. When this value is TRUE, the UFL tells the formula compiler that a formula that uses this UFL function should be marked automatically as a print-time formula.
  • A Boolean value. When this value is TRUE, the UFL tells the formula compiler that this UFL function has side effects. In this case, the UFL must implement the UF5SaveState and UF5RestoreState functions.

    • The definition table entry for a UFL function is in the following format:

    "returnType UDFName (arg1, arg2,...)", CFunctionName, MemCalcFunctionName, BooleanValue, BooleanValue"

    Here is an example:

    "String Picture (String, String)", Picture, NULL, FALSE, FALSE

    In this example:

    • "String" specifies that the function is to return a string.
    • "Picture" is the name that will identify the function on the Function list in the Formula Editor.
    • "(String, String)" specifies that the function is to require two arguments, both are strings.
    • "Picture" (appearing after the comma), is the actual function name, the name you give the function when you code it.
    • "NULL" indicates there is no memory calculation function available.
    • "FALSE" indicates that the function is not called only while printing records.
    • "FALSE" indicates that the function does not has side effects.

Note: The UDFName and the CFunctionName do not have to be the same. You can use something other than the function name to identify a function on the Function list of the Formula Editor if you wish.

All function definitions must be set up in a table with the following heading:

UF5FunctionDefStrings FunctionDefStrings [] =

Note: The entry must be terminated with three NULLs and two FALSEs.

Crystal Reports uses the information you supply in this table to create parameter blocks when you call the functions.

Function definition table example

Here is a sample function definition table entry for the Picture function:

UF5FunctionDefStrings FunctionDefStrings [] =

{

{"String Picture(String,String)",Picture, NULL, FALSE, FALSE},

{NULL,NULL,NULL, FALSE, FALSE}

};

Here, the third argument being NULL indicates that no memory calculation function is used (Crystal Reports will use the maximum allowable). The last two arguments being FALSE indicate the Picture function is not print-time only and has no side effects.

In contrast, if a memory calculation function is used by the Picture function, the definition might be:

{"String Picture (String, String)", Picture, PictureRetSize, FALSE, FALSE},

Here, the PictureRetSize function will calculate the maximum length of the string returned by the Picture function.


Function templates table

You must supply a function template for each function that you define. A function template specifies the string that Crystal Reports is to enter in the Formula Editor's Formula text box when you select the function from the Functions list in the Formula Editor. Each template must contain:

  • The function call.
  • Any syntax guides (parentheses, commas, etc.) you want to include.
  • An exclamation point (!) character to specify where the insertion point is to appear when the function is entered into the formula. Here is an example:

    • "Picture (!, )"

    In this example, the string "Picture ( , )" is to be entered into the formula whenever you select the Picture function from the Functions list in the Formula Editor.

    • The string includes the function call "Picture" and the syntax guides "( , )" to guide the user when entering arguments.
    • The exclamation point specifies that the insertion point is to be placed inside the parentheses, before the comma.

All function templates must be set up in a table with the following heading:

UFFunctionTemplates FunctionTemplates [] =

Note: The table must be terminated with a null.

Continuing with the example, the function templates table for the Picture function should look like this:

UFFunctionTemplates FunctionTemplates [] =

{

{"Picture (!, )"},

{NULL}

};


Function examples table

You must also supply a function example for each function. A function example specifies the string you want to use to identify and select the function in the Functions list in the Formula Editor. Here is a function example for the Picture function:

"\tPicture (string, picture)"

This example specifies that the string "Picture (string, picture)" is the listing that you want to appear in the Functions list. The characters "\t" specify that the string is to be set in from the left one tab stop, thus aligning it with other functions in the list.

All function examples must be set up in a table with the following heading:

UFFunctionExamples FunctionExamples [] =

Note: The table must be terminated with a null.

The complete function examples table for the Picture function should look like this:

UFFunctionExamples FunctionExamples [] =

{

{"\tPicture (string,picture)"},

{NULL}

};


Error table

You must also supply an error string for each error message that you want to make available to your functions. Each error string contains only the text you want to display when an error is detected, and it must be in the format:

"ErrorString"

Note: C compilers view the first string in the table as Error 0, the second as Error 1, an so on. Each string in the error table corresponds to an error code that you define. For each user error code, there must be a message string in the error table at the corresponding index, where the first string is at index 0.

Each UFL C function must return a value of the enumerated type UFError, defined in ufdll.h. Return UFNoError if no error occurred. Return one of the other UFError values if there is an error. Try to choose one of the predefined values if it fits your situation. If the error is specific to your UFL, set the ReturnValue.UFReturnUserError member of the parameter block to an error code value you have defined and return UFUserError from your function code. The Formula Editor will then call back to return the error string that you have defined in the error table.

The Formula Editor passes a parameter block to a UFL function rather than individual parameters. Obtaining parameter values from the parameter block, will examine how to handle parameter blocks.

All error strings must be set up in a table with the following heading:

char *ErrorTable [] =

An error table for the Picture function should, at a minimum, look like this:

char *ErrorTable[] =

{

"no error"

};


InitForJob function

The InitForJob function initializes all user function UFL's with the job ID whenever a job starts. You can handle any job initialization for your functions here, but all that is absolutely necessary is an empty function implementation:

void InitForJob(UFTInt32u jobID)

{

}

Note: See the note following TermForJob function.


TermForJob function

The TermForJob function terminates the job ID for all user function UFL's whenever a job finishes. You can add any job termination code here that you like, but all that is absolutely necessary is an empty function implementation:

void TermForJob(UFTInt32u jobID)

{

}

Note: Every UFL must have an implementation of InitForJob function, and TermForJob. These functions are called when a job starts and ends printing, respectively. You can choose to implement these yourself. At a minimum, you must provide empty functions. Alternatively, if you include the UFJOB helper modules in your project, you do not need to implement InitForJob and TermForJob. Crystal Reports provides helper modules (UFJOB.C and UFJOB.H) which implement these functions and maintain a doubly linked list of JobInfo structures, one for each active job. The JobInfo structure (declared in UFJOB.H) holds the ID# of the job and contains a void pointer where you can store any data that you allocate. The files also implement a FindJobInfo function (see Implement InitJob and TermJob), which you can use to retrieve the job information for any open job. UFJOB modules will examine these files and their implementation of InitForJob and TermForJob.


UFL function implementation

As the final step to creating a UFL function (see Function definition), you must add code for the operation of the function you have designed. Your function must be programmed for the specific needs of your UFL. This section will examine the basics of how to obtain the parameters from the parameter block and use the values of those parameters in the implementation of the UFL function.

You begin by coding your function as follows:

ExternC UFError FAR _export PASCAL FunctionName

(UFParamBlock *ParamBlock)

{

// Your function's code

}

First, notice that the function is exported because a UFL is simply a DLL being accessed by Crystal Reports. Second, the function returns an error code of the enumerated type UFError. In the error trapping sections of your function, you can return a UFError value, such as UFNotEnoughParameters, or you can return UFUserError and define your own errors in the error table. Finally, the function accepts a parameter block of type UFParamBlock from Crystal Reports rather than individual parameters. You will need to retrieve the individual parameters from that parameter block to work with the data values passed by the Formula Editor.

Note: ExternC is defined in UFDLL.H and is equivalent to: extern "C".


Returning user-defined errors

The UFError enumerated type provides several errors that are common to many types of functions. If appropriate, have your UFL function return one of these predefined types. If no error occurs, you can return UFNoError.

If your function can cause an error that is not predefined, you can establish a user-defined error. You do this by:

  • Adding an error string to the error table.
  • Passing the appropriate error index to the ReturnValue.UFReturnUserError member of the parameter block.
  • Returning UFUserError from your UFL function implementation.

A user-defined error string in the error table might look like this:

char *ErrorTable[] =

{

"My User-defined Error"

};

This error string is assigned an error index by Crystal Reports. The first error is 0, the second is 1, etc. If an error occurs in your function, you assign the appropriate index value to the ReturnValue.UFReturnUserError member of the parameter block. For example:

ParamBlock->ReturnValue.UFReturnUserError = 0;

Once you specify a user-defined error, you can return the UFError value UFUserError from your function. When the Formula Editor finds the error in a formula entered in the Formula text box (when the Check or Accept button is clicked), it will use the error index specified to report the appropriate string listed in the error table.


Obtaining parameter values from the parameter block

Since Crystal Reports passes the values for a Formula Editor function's parameters in a parameter block rather than individually, you must separate the values from the parameter block before they can be evaluated. For the Picture function (see Picture function—a sample UFL function), expect the parameter block to contain two parameters, both of type String, as defined in the function definition table.

To obtain the values of the individual parameters, begin by defining pointers to two structures of type UFParamListElement (defined in UFDLL.H):

UFParamListElement *FirstParam,*SecondParam;

Next, call the GetParam function (defined in UFMAIN.C) for each UFParamListElement to obtain a pointer to each parameter from the parameter block:

FirstParam = GetParam (ParamBlock, 1);

SecondParam = GetParam (ParamBlock, 2);

The actual value is stored in the Parameter member of the UFParamListElement according to the type of data it contains. The Parameter member is a UFParamUnion type (a union data type holding a value according to the type of data expected). Since both of the parameters are of type String, you can obtain the actual parameter value for each UFParamListElement by using the following notation:

FirstParam->Parameter.ParamString

SecondParam->Parameter.ParamString

If, on the other hand, the second parameter contained a numeric value, you could use this notation:

SecondParam->Parameter.ParamNumber

Study the UFParamUnion union definition in the UFDLL.H file for a complete list of all possible parameter types and how to obtain a value from them.


Picture function—a sample UFL function

Here is a complete commented private C code module implementing the Picture function. Use this as a guide for how to create your own functions in UFLs:

/********************************

** U25SAMP.C

**

** Private C code module

** implementing the Picture UDF.

********************************/

#include <Windows.h>

#include "UFDll.h"

#include "UFMain.h"

#include "UFUser.h"

#define PicturePlaceholder 'x'

/* UDF PROTOTYPE */

ExternC UFError FAR PASCAL Picture (UFParamBlock * ParamBlock);

/*****

* This array gives the program the types for the

* parameters to the UDF, the return

* type, and the name. It also passes the

* address of the actual function code.

*****/

UF5FunctionDefStrings FunctionDefStrings [] =

{

{"String Picture (String, String)", Picture, NULL, FALSE, FALSE},

{NULL, NULL, NULL, FALSE, FALSE}

};

/*****

* The following is the template the program

* will insert into the Formula Editor

* Formula text box when this function is

* selected.

*****/

UFFunctionTemplates FunctionTemplates [] =

{

{"Picture (!,"},

{NULL}

};

/*****

* The following is an example of the format

* for this function. This text will appear

* in the Functions list box of the Formula

* Editor.

*****/

UFFunctionExamples FunctionExamples [] =

{

{"\tPicture (string, picture)"},

{NULL}

};

/*****

* This array contains ASCII string

* representations of the errors which

* could occur.

*****/

char *ErrorTable [] =

{

"no error"

};

/* Called for on initialization */

void InitForJob (UFTInt32u jobID)

{

}

/* Called on termination */

void TermForJob (UFTInt32u jobID)

{

}

/*****

* This function is used by the Picture UDF to

* copy the contents of a source string and a

* format string into a destination string.

*****/

static void copyUsingPicture (char *dest, const char *source, const char *picture)

{

while (*picture != '\0')

{

if (tolower (*picture) ==

PicturePlaceholder)

if (*source != '\0')

*dest++ = *source++;

else

; // do not insert anything

else

*dest++ = *picture;

picture++;

}

// copy the rest of the source

lstrcpy (dest, source);

}

/*****

* This is the User-Defined Function

*****/

ExternC UFError FAR PASCAL Picture (UFParamBlock * ParamBlock)

{

UFParamListElement *FirstParam,*SecondParam;

FirstParam = GetParam (ParamBlock, 1);

SecondParam = GetParam (ParamBlock, 2);

if (FirstParam == NULL || SecondParam == NULL)

return UFNotEnoughParameters;

copyUsingPicture (ParamBlock->ReturnValue.ReturnString,

FirstParam->Parameter.ParamString,

SecondParam->Parameter.ParamString);

return UFNoError;

}


Module Definition (.def) file

The last element of your UFL is the module definition (.def) file. This is just like any module definition file you would create for a DLL, but you must make sure to explicitly export not only your UFL function, but also the specialized UFL functions defined in UFMAIN.C that Crystal Reports expects to find. The following is an example of a module definition file for the UFL that exports the Picture function (seePicture function—a sample UFL function):

LIBRARY U25SAMP

DESCRIPTION 'Sample User Function Library for Crystal Reports'

EXPORTS

UF5Initialize

UFTerminate

UFGetVersion

UFStartJob

UFEndJob

UFGetFunctionDefStrings

UFGetFunctionExamples

UFGetFunctionTemplates

UFErrorRecovery

Picture

Notice that the only function exported that you actually coded is the Picture UFL. The rest of the exported functions have been defined for you in UFMAIN.C. Every U25 DLL must export these 9 UF* functions. If UF5SaveState and UF5RestoreState are defined, they should also be exported.

When you have finished coding the module definition file, save it to your working directory and add it to the list of files in your project file.

Finally, compile and link the u25*project file. Resolve any errors that occur, and recompile if necessary. Once you have your DLL (u25*.dll), place it in \Program Files\Common Files\Business Objects\3.0\bin directory. From that point on, when you open the Formula Editor, your User-Defined Function(s) will appear in the "Additional Functions" section at the bottom of the Functions list of the Formula Editor. Enter each function in one or more formulas, and test and modify it until it works the way you want.

Note: For additional information, download the sample file from http://support.businessobjects.com/communityCS/FilesAndUpdates/cr_ufl_cpp_general.exe.asp.


UFJOB modules

Two optional modules, UFJOB.C and UFJOB.H have been provided with Crystal Reports. These files provide an implementation of theInitForJob function, and TermForJob function, which allow you to obtain an ID number that is specific to the current print job in Crystal Reports. At the same time, these modules establish a JobInfo structure for the current job where you can store information regarding the job. If your UFL, for example, must evaluate all values in a field before printing a result, it can tally data in the JobInfo structure until it has a result. Data can even be passed between functions using the JobInfo structure.

Use the JobInfo structure whenever you want to create UFL functions that summarize or group report data. For example, statistical functions that evaluate the median, mean, or range of values in a field can store data in the JobInfo structure.

If you decide to use the UFJOB modules in your own UFL, the following are required:

  • UFJOB.C
    • Add UFJOB.C to your UFL project file.

      • Note: See also UFJOB.H.

  • UFJOB.H
    • #include UFJOB.H in your private C code module that implements your UFL functions.
  • Implement InitJob and TermJob
    • Replace your own implementations of the InitForJob and TermForJob functions with implementations of the InitJob and TermJob functions.


UFJOB.C

This module contains implementations of the InitForJob function, and TermForJob function, that provide a JobInfo structure for the current job in Crystal Reports. These replace any versions of these functions that you coded in your private C module containing your UFL definitions. They also call the InitJob and TermJob functions respectively. You will implement these functions in your private C code module.

In addition, this file also defines the FindJobInfo function. Use this function in your own code whenever you need to obtain a pointer to the JobInfo structure for the current job. This function requires only the job ID number, which is stored in the JobId member of the parameter block. The following code demonstrates how to call this function:

struct JobInfo *jobInfo;

jobInfo = FindJobInfo (ParamBlock->JobId);


UFJOB.H

This module prototypes the InitForJob function, TermForJob function, and FindJobInfo functions that appear in UFJOB.C. It also prototypes the InitJob and TermJob functions that you must implement yourself. Most importantly, this file defines the JobInfo structure:

struct JobInfo

{

UFTInt32u jobId;

struct JobInfo FAR *prev;

struct JobInfo FAR *next;

void FAR *data;

};

The data member of this structure allows you to store a pointer to any kind of data you wish. This means you can store information for the current job that allows you to evaluate several field values before printing a result or store data from one function to be used by another function.


Implement InitJob and TermJob

If you previously implemented the InitForJob and TermForJob functions in the private C code module with your UFL function definitions, delete those functions now since they are being replaced by the functions in UFJOB.C. Now, in your private C module, define the InitJob and TermJob functions which InitForJob and TermForJob call. You can use these functions to add job initialization or job termination code to your UFL, but they can also remain blank.

Following are examples of how you might implement these functions for your own UFL:

void InitJob (struct JobInfo *jobInfo)

{

}

void TermJob (struct JobInfo *jobInfo)

{

If (jobInfo->data != 0)

free (jobInfo->data);

}

Once you have done all this, you can make full use of the JobInfo structure with your own UFL function code.


Special functions

You can define several special purpose functions in your Class Module in addition to the User-Defined Functions that you are creating. The Crystal Reports Formula Editor can look for and process code defined in any of the following functions:

Be sure to define the functions in your code exactly as they appear above. If not defined correctly, they will be ignored by Crystal Reports.


UF5Initialize

This function is called just after the DLL is loaded into memory. Use this function to handle one-time initialization of variables. It takes a version number.

UF5Initialize returns a value of 0 (zero) to indicate successful initialization. Any non-zero values indicate initialization failed.


UFTerminate

This function is called just before the DLL is unloaded from memory. Use this function to clean up any allocated memory or other data before unloading the DLL.

UFTerminate returns a value of 0 (zero) when the memory clean-up is finished.


UFStartJob

This procedure is called by Crystal Reports just before User-Defined Functions are evaluated (or reevaluated). The Crystal Reports job number is passed to the function as the only parameter. Use this function to handle any initialization on a per-job basis.


UFEndJob

This procedure is called by Crystal Reports when the current job finishes (that is, when all pages of a report have been generated), before UFStartJob is called again, or before UFTerminate is called. This function also accepts the Crystal Reports job number as its only parameter. Handle any clean-up necessary on a per-job basis using this function.


UF5SaveState

This procedure must be implemented only if your UFL has a function with side effects. It is called by Crystal Reports to obtain the state from the UFL at a given point. The Crystal Reports job number is passed to the function. The function returns the UFL state binary stream in the second parameter, and returns the size of the state in the third parameter.


UF5RestoreState

This procedure must be implemented only if your UFL has a function with side effects. It is called by Crystal Reports to restore the UFL state to its saved value. The Crystal Reports job number and the saved UFL state binary stream are passed to the function.


Creating User-Defined Functions in Delphi 3.0

Crystal Reports allows you to create User-Defined Functions that are recognized by the Crystal Reports Formula Editor. In this section you will find detailed information on programming User-Defined Functions in Delphi.

Note: You can also use Java user defined function libraries. For details, see the Java Reporting Component Developer's Guide. (Note that the Java UFLs can only be used with CRW and the JRC.)

Click the appropriate link to jump to that section:

  • Overview of User-Defined Functions in Delphi
  • Programming User-Defined Functions in Delphi
  • Delphi and Crystal Reports


Overview of User-Defined Functions in Delphi

The Crystal Reports Formula Editor and formula language are powerful tools, enabling you to do a wide variety of report-related tasks easily and efficiently. The formula language is expandable as well. That is, while it already includes a large selection of useful functions, it also comes with the ability to accept new functions that you define to meet your needs.

User-Defined Functions that are recognized by the Crystal Reports Formula Editor can be created in a Dynamic Link Library or, for 32-bit environments, in an Automation Server. This section demonstrates how to create User-Defined functions in an Automation Server using Borland Delphi 3.0 (and later versions). For information on how to create User-Defined Functions in a Dynamic Link Library using the C or C++ programming language, see Creating User-Defined Functions in C. For information on how to create User-Defined Functions in an Automation Server using Visual Basic, see Creating User-Defined Functions in Visual Basic.


Programming User-Defined Functions in Delphi

The Crystal Reports Formula Editor can access User-Defined Functions through a User Function Library (UFL). A User Function Library is a specially designed Dynamic Link Library that exposes one or more functions that you create. UFLs can be designed and programmed in any language that supports the development of Windows DLLs.

The 32-bit version of Crystal Reports Professional Edition includes the User Function Library U2LCOM.DLL. This UFL is installed in your \Program Files\Common Files\business objects\3.0\bin directory when you install Crystal Reports and provides an interface through which you can expose User-Defined Functions in Automation Servers.

An Automation Server is a Dynamic Link Library or executable file that exposes its functionality to other modules and processes through the Component Object Model. For complete information on the Component Object Model (COM), refer to Microsoft documentation or the Microsoft World Wide Web site. U2LCOM.DLL is a UFL that can access any functions exposed by any Automation Servers named with a CRUFL prefix. This means that you can create an Automation Server in any language environment that supports COM, name the server with a CRUFL prefix, register the server on a system, and the Crystal Reports Formula Editor will access and make available any functions exposed by that Automation Server.

You may be more familiar with Automation Servers as OLE Automation. Though the technology behind Automation Servers is the same as OLE Automation, the correct name for these servers is now simply Automation Servers.

Delphi 3.0 allows you to design 32-bit Automation Servers easily. As a Delphi programmer, you can design User-Defined Functions for use in your reports by exposing them in an ActiveX Library and registering the library (Automation Server) on your system.


Using Delphi 3.0

Note: Version 3.0 of Delphi is required to create Automation Servers containing User-Defined Functions.

There are seven primary steps to creating User-Defined Functions in an automation server in Delphi 3.0:

  • Create the project
  • Create the Automation Object
  • Add Methods to the Type Library
  • Register the Type Library
  • Create the User-Defined Functions
  • Build the project
  • Using the User-Defined Functions


Create the project

When Delphi first opens, it creates a default project and form for you.

  1. Choose New from the File menu.
  2. Click the ActiveX Tab in the New Items dialog box, and double-click the ActiveX Library icon.

    3. Delphi creates a default ActiveX Library for you.

    The U2LCOM.DLL UFL will only read functions exposed by Automation Servers named with a CRUFL prefix. For example, CRUFLMyFunctions is a valid project name for your Automation Server.

  3. Choose Save Project As from the File menu, and save your Delphi project.

    4. The project should be named CRUFLxxx.DPR, where xxx is a name of your choice.


Create the Automation Object

  1. Choose New from the File menu.
  2. Click the ActiveX Tab in the New Items dialog box, and double-click the Automation Object icon.

    3. The Automation Object Wizard appears.

  3. Enter a class name appropriate to the functions you will create.
  4. Make sure Instancing is set to Multiple Instance, and click OK.

    5. The Type Library Editor appears.

  5. Make sure the name of the type library for your project matches the project name you created earlier. If not, change the name of the type library to CRUFLxxx, where xxx is the name you chose.


Add Methods to the Type Library

The methods in the class you specified when you created the type library will become User-Defined Functions that appear in the Crystal Reports Formula Editor.

  1. Right-click the interface for your type library.

    2. The interface name is identical to the class name you specified preceded by an I.

  2. Choose New from the menu that appears, and then choose Method.

    3. A new method appears below the interface in the Object list pane.

  3. Name the method according to the function you want to create.
  4. On the Attributes Tab for the method, declare your function.

    5. For example:

    function Square (Number: double): double;

Note: For complete information on how to declare functions in Delphi, refer to your Delphi documentation.

The U2LCOM.DLL UFL supports most standard Delphi data types and arrays. For complete information on how the Crystal Reports Formula Editor interprets Delphi data types and arrays, see Delphi and Crystal Reports.

Continue creating methods for all User-Defined Functions you want to appear in the Crystal Reports Formula Editor.


Register the Type Library

  1. Click Register in the Type Library Editor.

    2. Delphi creates your type library and registers it on your system. A message should appear indicating that the ActiveX automation server was successfully registered.

  2. Click OK in the message box.

Note: If the type library is not registered successfully on your system, create the type library and object methods over again. If you continue to have problems, refer to your Delphi documentation on creating type libraries.


Create the User-Defined Functions

  1. Minimize the Type Library Editor, and locate the declaration of the method you created in the your type library in the Unit1.pas unit.
  2. Enter code for the function as desired.

    3. For example:

    function TConversion.Square(Number: Double): Double;

    begin

    result := Number * Number;

    end;

  3. Continue coding all methods that you declared for the interface.


Build the project

  • Save all files in your project, and choose Build All from the Project menu.

Delphi builds your automation server, and the methods you declared are now available from the Crystal Reports Formula Editor.


Using the User-Defined Functions

  1. In Crystal Reports, create a new report and add tables to it, or open an existing report.
  2. From the Insert menu, choose Formula Field.

    3. The Insert Field dialog box appears.

  3. Click New, and enter a name for the new formula in the Formula Name dialog box.
  4. Click OK and the Formula Editor appears.
  5. Scroll down in the Functions list box to the Additional Functions section. Locate the User-Defined Function you created.

    6. User-Defined Function names for functions created in Automation Servers are prefixed according to the project and class name used when you created the automation server. For instance, if you named your project CRUFLProject, named the class Conversion, and named the function Square, the User-Defined Function would appear in the Formula Editor as ProjectConversionSquare.

  6. Double-click the User-Defined Function, and it appears in the Formula text box.
  7. Enter valid arguments for the function.

    8. For example:

    ProjectConversionSquare(5)

  8. Click Check.

    9. Make sure no errors appear in the function.

  9. Click Accept, and place the formula in your report.
  10. Preview the report and verify that the function worked correctly.

Congratulations, you just created and used a User-Defined Function.


Delphi and Crystal Reports

Note: 32-bit Support Only. U2LCOM.DLL is a 32-bit UFL only and, therefore, supports only 32-bit Automation Server DLLs. To create User-Defined Functions for Crystal Reports, you must have Delphi 3.0 (or another 32-bit development environment that supports the creation of COM-based Automation Servers).

The following topics are discussed in this section:

  • Data types.
  • Using arrays.
  • Reserved names.
  • Function name prefixing.
  • Passing Parameters By Reference and By Value.
  • Error handling.
  • Special purpose functions


Data types

Crystal Reports will support most common Delphi data types provided through a User-Defined Function developed in Delphi 3.0. The following table shows how Crystal Reports converts the most common Delphi data types to data types supported by the Formula Editor:

Delphi Data Types | Formula Editor Data Types
ShortInt Integer LongInt Real Single Double | NumberVar
Currency | CurrencyVar
Date | DateVar
Boolean | BooleanVar
String | StringVar

Note: Ranges—the range data type available in the Crystal Reports Formula Editor is not supported in COM-based User-Defined Functions.


Using arrays

Arrays can be passed to any User-Defined Function as a parameter of the function. This means that when you design your function in Delphi, the function can accept an array of values of any of the supported data types. However, the function cannot return an array to the Crystal Reports Formula Editor. The following Delphi function is an acceptable User-Defined Function for Crystal Reports:

Function GetNthItem (A: MyArray, n: Integer): Integer;

begin

GetNthItem := A[n];

End;


Reserved names

Certain names are reserved and cannot be used as User-Defined Function names. The following names are reserved by the Crystal Reports Formula Editor for special purposes:

  • UFInitialize
  • UFTerminate
  • UFStartJob
  • UFEndJob

For more explanation of these function names, see Special purpose functions.

In addition, User-Defined Functions cannot use the same name as any of the functions exposed by the IDispatch interface used by COM:

  • QueryInterface
  • AddRef
  • Release
  • GetTypeInfoCount
  • GetTypeInfo
  • GetIDsOfNames
  • Invoke


Function name prefixing

To ensure a unique name when User-Defined Functions appear in the Formula Editor, Crystal Reports appends a prefix to each function name that is generated from the project and class names. The first part of the prefix is the project name without the CRUFL prefix. The rest of the function name prefix is the class name.

Once the prefix for the function name is generated, all non-alphanumeric characters are removed, and the prefix is applied to the original function name. The following table illustrates this process:

Project Name | CRUFLTestFunctions
Class Name | Conversion
User-Defined Function Name | Date_To_String()
Formula Editor Function | TestFunctionsConversionDateToString()


Passing Parameters By Reference and By Value

Arguments can be passed to User-Defined Functions written in Delphi 3.0, either by value or by reference. For instance, both of the following functions are valid:

Function Test1 (num1: Integer): Integer;

Function Test1 (var num1: Integer): Integer;


Error handling

If it is possible for your User-Defined Function to produce an error, the Crystal Reports Formula Editor should be notified of the error. Many types of errors are automatically handled by the Formula Editor. Passing the wrong type of data to a function, for instance, will be recognized and trapped by Crystal Reports. However, if you design a function that can produce an error unique to that function, you should provide a means for reporting that error to the Formula Editor.

To send error messages to the Formula Editor, define the UFErrorText string property in your Class Module. This property should be defined Public, using code similar to this:

Property UFErrorText: String;

Any time you trap for an error condition, simply set the UFErrorText property to the error text you want reported in Crystal Reports. Setting the value of this property triggers the error in Crystal Reports, and Crystal Reports displays a dialog box containing the error message that you assigned to UFErrorText.

Note: You should not use the UFErrorText property for anything other than returning errors from User-Defined Functions. The U2LCOM.DLL UFL regularly resets the value of this property, so data can be lost if stored in UFErrorText for any reason other than reporting an error.


Special purpose functions

You can define several special purpose functions in your Class Module in addition to the User-Defined Functions that you are creating. The Crystal Reports Formula Editor can look for and process any of the following class methods:

Function UFInitialize: Integer;

Function UFTerminate: Integer;

Procedure UFStartJob (job: Integer)

Procedure UFEndJob (job: Integer)

Be sure to declare the methods in your code exactly as they appear above. If not declared correctly, they will be ignored by Crystal Reports. These methods are completely optional when creating your Delphi Automation Server. They are provided to assist you with the design of your User-Defined Functions.


UFInitialize

This function is called just after the DLL is loaded into memory. Use this function to handle one-time initialization of variables.

Returns a value of 0 (zero) to indicate successful initialization. Any non-zero value indicates initialization failed.


UF5Initialize

This function is similar to UFInitialize except that it takes a version number.


UFTerminate

This function is called just before the DLL is unloaded from memory. Use this function to clean up any allocated memory or other data before unloading the DLL.

Returns a value of 0 (zero) when finished cleaning up memory.


UFEndJob

This procedure is called by Crystal Reports when the current job finishes, which happens when all pages of a report have been generated, before UFStartJob is called again, or before UFTerminate is called. This function also accepts the Crystal Reports job number as its only parameter. Handle any clean-up necessary on a per-job basis using this function.


Creating User-Defined Functions in Visual Basic

Crystal Reports allows you to create User-Defined Functions that are recognized by the Crystal Reports Formula Editor. In this section you will find detailed information on programming User-Defined Functions in Microsoft Visual Basic.

Note: You can also use Java user defined function libraries. For details, see the Java Reporting Component Developer's Guide. (Note that the Java UFLs can only be used with CRW and the JRC.)

Click the appropriate link to jump to that section:

  • Overview of User-Defined Functions in Visual Basic
  • Programming User-Defined Functions in Visual Basic
  • Visual Basic and Crystal Reports


Overview of User-Defined Functions in Visual Basic

The Crystal Reports Formula Editor and formula language are powerful tools, enabling you to accomplish a wide variety of report-related tasks easily and efficiently. The formula language is expandable as well. That is, while it already includes a large selection of useful functions, it also comes with the ability to accept new functions that you define to meet your needs.

User-Defined Functions that are recognized by the Crystal Reports Formula Editor can be created in a Dynamic Link Library or, for 32-bit environments, in an Automation Server. This section demonstrates how to create User-Defined Functions in an Automation Server using Visual Basic. For information on how to create User-Defined Functions in a Dynamic Link Library using the C or C++ programming language, see Creating User-Defined Functions in C.

Note: For more information on creating and using UFLs, go to http://support.businessobjects.com and search for "UFL".


Programming User-Defined Functions in Visual Basic

The Crystal Reports Formula Editor can access User-Defined Functions through a User Function Library (UFL). A User Function Library is a specially designed Dynamic Link Library that exposes one or more functions that you create. UFLs can be designed and programmed in any language that supports the development of Windows DLLs.

The Crystal Reports Professional Edition includes the User Function Library U2LCOM.DLL. This UFL is installed in your \Program Files\Common Files\business objects\3.0\bin directory when you install Crystal Reports and provides an interface through which you can expose User-Defined Functions in Automation Servers.

An automation server is a Dynamic Link Library or executable file that exposes its functionality to other modules and processes through the Component Object Model. For complete information on the Component Object Model (COM), refer to Microsoft documentation or the Microsoft World Wide Web site. U2LCOM.DLL is a UFL that can access any functions exposed by any Automation Servers named with a CRUFL prefix. This means that you can create an Automation Server in any language environment that supports COM, name the server with a CRUFL prefix, register the server on a system, and the Crystal Reports Formula Editor will access and make available any functions exposed by that Automation Server.

Note: You may be more familiar with Automation Servers as OLE Automation. Though the technology behind Automation Servers is the same as OLE Automation, the correct name for these servers is now simply Automation Servers.

Visual Basic, version 4.0 and later, allows you to design 32-bit Automation Servers easily. As a Visual Basic programmer, you can design user-defined functions for use in your reports by exposing them in ActiveX DLLs and registering the DLL on your system.

Note: Any development environment that allows the creation of COM-based Automation Servers can use the techniques similar to those described in this section. However, the code and examples shown here are based on Visual Basic.

The steps for creating automation servers in Visual Basic are slightly different, depending on the version of Visual Basic you are using. Below is an example of how to create an Automation Server in Visual Basic 6.0. Consult your Visual Basic documentation if you are using another version.


Using Visual Basic 6.0

There are only four major steps to creating an Automation Server in Visual Basic 6.0. When you finish designing your Automation Server, the U2LCOM.DLL User Function Library will be able to access all of the functions that it exposes.

  • Create a New ActiveX DLL project
  • Add User Functions to the Class Module
  • Name the project
  • Build the DLL


Create a New ActiveX DLL project

  1. When you first run Visual Basic 6.0, the New Project dialog box appears. If you already have Visual Basic open, simply choose New Project from the File menu.
  2. Double-click the ActiveX DLL icon in the New Project dialog box.

    3. Visual Basic creates a new project for you with a single Class Module.

Note: For complete information on creating an ActiveX DLL in Visual Basic 6.0, refer to your Visual Basic documentation.


Add User Functions to the Class Module

The next step is to add the actual User-Defined Functions that you want to appear in the Crystal Reports Formula Editor. These functions are standard Visual Basic functions that you might define in any Visual Basic project. The only requirement is that the functions are declared Public.

Type in the following function:

Public Function Square(num As Single) As Single

Square = num * num

End Function

The U2LCOM.DLL UFL supports most standard Visual Basic data types and arrays. For complete information on how the Crystal Reports Formula Editor interprets Visual Basic data types and arrays, see the sections Visual Basic and Crystal Reports, and Using Arrays.


Name the project

The U2LCOM.DLL UFL will only read Public functions exposed by Automation Servers named with a CRUFL prefix. For example, CRUFLMyFunctions is a valid project name for your Automation Server.

To change the name of your project in Visual Basic 6.0, highlight your project in the Project window, then change its (Name) property in the Properties window to CRUFLxxx, where xxx is a name of your choice.


Build the DLL

From the File menu, choose Make CRUFLxxx.dll. Once again, xxx is the name you chose. When this command executes, Visual Basic will compile your project into an ActiveX DLL (an Automation Server) and register it in your local system Registry.


Registration of the Automation Server and Distribution of the Visual Basic Project

An Automation Server must be registered on any system on which it will be used. Automation Servers are registered in the Windows 9x, Windows 2000 or Windows NT System Registry. The file can be physically stored anywhere on your hard drive because the Registry settings tell Windows where the file is located when it is needed.

When you make an ActiveX DLL project in Visual Basic 6.0, Visual Basic automatically registers the Automation Server on your system. Once registered, you can easily test and use the new User-Defined Functions from the Crystal Reports Formula Editor.

The easiest way to distribute any Visual Basic project is to use the Setup Wizard to create an installation program. In addition to making sure all necessary files are installed where appropriate, the Setup Wizard can add code to your installation to register the Automation Server in the user's system Registry.

In addition to installing and registering your Automation Server, you must also provide the U2LCOM.DLL UFL file on any system that will use the functions exposed by your Automation Server. If the system has Crystal Reports installed, then this file will already be located in the \Program Files\Common Files\Business Objects\3.0\bin directory.


Using the User-Defined Functions

  1. In Crystal Reports, create a new report and add tables to it, or open an existing report.
  2. In the Field Explorer dialog box, right-click the Formula Fields branch of the tree, click New.

    3. The Formula Name dialog box appears.

  3. Enter a name for the formula, click Use Editor.

    4. The Formula Editor appears.

  4. Scroll down in the Functions list box to the Additional Functions section. Locate the User-Defined Function you created.

    5. User-Defined Function names for functions created in Automation Servers are prefixed according to the project and class name used when you created the Automation Server. For instance, if you named your project CRUFLProject, named the class Conversion, and named the function Square, the User-Defined Function would appear in the Formula Editor as ProjectConversionSquare.

  5. Double-click the User-Defined Function, and it appears in the Formula text box.
  6. Enter valid arguments for the function.

    7. For example:

    ProjectConversionSquare(5)

  7. Click Check. Make sure no errors appear in the function.
  8. Click Save and close.

    9. The Formula Editor closes and the formula appears in the formula list in the Formula Fields branch of the tree in the Field Explorer dialog box.

  9. Insert the formula into the report by dragging it into the report, or by selecting it and then clicking Insert to Report.
  10. Preview the report and verify that the function worked correctly.

Congratulations, you just created and used a User-Defined Function.


Visual Basic and Crystal Reports

Note: 32-bit Support Only. U2LCOM.DLL is a 32-bit UFL only and, therefore, supports only 32-bit Automation Server DLLs. To create User-Defined Functions for Crystal Reports, you must have the 32-bit edition of Visual Basic 4.0 or Visual Basic 5.0 or higher (or another 32-bit development environment that supports the creation of COM-based Automation Servers).


Variable Types

Crystal Reports will support most common Visual Basic data types provided through a User-Defined Function developed in Visual Basic. The following table shows how Crystal Reports converts the most common Visual Basic data types to data types supported by the Formula Editor:

Visual Basic Data Types | Formula Editor Data Types
Integer Long Single Double | NumberVar
Currency | CurrencyVar
Date | DateVar
Boolean | BooleanVar
String | StringVar

Note: Ranges—the range data type available in the Crystal Reports Formula Editor is not supported in COM-based User-Defined Functions.


Using Arrays

Arrays can be passed to any User-Defined Function as a parameter of the function. This means that when you design your function in Visual Basic, the function can accept an array of values of any of the supported data types. However, the function cannot return an array to the Crystal Reports Formula Editor. The following Visual Basic function is an acceptable User-Defined Function for Crystal Reports:

Public Function GetNthItem (sArray() As String, n As Integer) As String

GetNthItem = sArray(n)

End Function


Reserved Names

Certain names are reserved and cannot be used as User-Defined Function names. The following names are reserved by the Crystal Reports Formula Editor for special purposes:

  • UFInitialize
  • UFTerminate
  • UFStartJob
  • UFEndJob

For more explanation of these function names, see Special purpose functions. In addition, User-Defined Functions cannot use the same name as any of the functions exposed by the IDispatch interface used by COM:

  • QueryInterface
  • AddRef
  • Release
  • GetTypeInfoCount
  • GetTypeInfo
  • GetIDsOfNames
  • Invoke


Function Name Prefixing

To ensure a unique name when User-Defined Functions appear in the Formula Editor, Crystal Reports appends a prefix to each function name that is generated from the project and Class Module names in the original source code. The first part of the prefix is the project name without the CRUFL prefix. The rest of the function name prefix is the Class Module name.

Once the prefix for the function name is generated, all non-alphanumeric characters are removed, and the prefix is applied to the original function name. The following table illustrates this process:

Project Name: | CRUFLTestFunctions
Class Module Name | Conversion
User-Defined Function Name | Date_To_String()
Formula Editor Function | TestFunctionsConversionDateToString()

This function name prefixing can be turned off if you are sure that your function names will not conflict with any other function names recognized by the Formula Editor. To turn off function name prefixing:

  1. Define a Boolean property for the class called UFPrefixFunctions.
  2. Set the value of the property to False in the Initialize subroutine for the class.

    3. For example:

    Public UFPrefixFunctions As Boolean

    Private Sub Class_Initialize()
    UFPrefixFunctions = False

    End Sub

Note: Function name prefixing is designed to eliminate function name conflicts. If you turn off function name prefixing and your function name conflicts with another function, you may get unpredictable results.


Passing Parameters By Reference and By Value

Arguments can be passed to User-Defined Functions written in Visual Basic either ByRef or ByVal. ByRef is the default method for Visual Basic, but both methods will work. For instance, all of the following functions are valid:

Public Function Test1 (num1 As Integer) As Integer

Public Function Test1 (ByRef num1 As Integer) As Integer

Public Function Test1 (ByVal num1 As Integer) As Integer


Error handling

If it is possible for your User-Defined Function to produce an error, the Crystal Reports Formula Editor should be notified of the error. Many types of errors are automatically handled by the Formula Editor. Passing the wrong type of data to a function, for instance, will be recognized and trapped by Crystal Reports. However, if you design a function that can produce an error unique to that function, you should provide a means for reporting that error to the Formula Editor.

To send error messages to the Formula Editor, define the UFErrorText string property in your Class Module. This property should be defined Public, using code similar to this:

Public UFErrorText As String

Any time you trap for an error condition, simply set the UFErrorText property to the error text you want reported in Crystal Reports. Setting the value of this property triggers the error in Crystal Reports, and Crystal Reports displays a dialog box containing the error message that you assigned to UFErrorText.

Note: You should not use the UFErrorText property for anything other than returning errors from User-Defined Functions. The U2LCOM.DLL UFL regularly resets the value of this property, so data can be lost if stored in UFErrorText for any reason other than reporting an error.


Special purpose functions

You can define several special purpose functions in your Class Module in addition to the User-Defined Functions that you are creating. The Crystal Reports Formula Editor can look for and process code defined in any of the following functions:

Public Function UFInitialize () As Long

Public Function UFTerminate () As Long

Public Sub UFStartJob (job As Long)

Public Sub UFEndJob (job As Long)

Be sure to define the functions in your code exactly as they appear above. If not defined correctly, they will be ignored by Crystal Reports. These functions are completely optional when creating your Visual Basic Automation Server. They are provided to assist you with the design of your User-Defined Functions.

UFInitialize

This function is called just after the DLL is loaded into memory. Use this function to handle one-time initialization of variables.

Return a value of 0 (zero) to indicate successful initialization. Any non-zero value indicates initialization failed.

UFTerminate

This function is called just before the DLL is unloaded from memory. Use this function to clean up any allocated memory or other data before unloading the DLL.

Return a value of 0 (zero) when finished cleaning up memory.

UFStartJob

This procedure is called by Crystal Reports just before User-Defined Functions are evaluated (or reevaluated). The Crystal Reports job number is passed to the function as the only parameter. Use this function to handle any initialization on a per-job basis.

UFEndJob

This procedure is called by Crystal Reports when the current job finishes, which happens when all pages of a report have been generated, before UFStartJob is called again, or before UFTerminate is called. This function also accepts the Crystal Reports job number as its only parameter. Handle any clean-up necessary on a per-job basis using this function.


Active Data

This section provides information on using active data in the Crystal Reports Development environment. Three areas are covered: the active data drivers, the Crystal Data Object, and the COM Data Provider. By reading these sections you will learn how to create active data reports, create recordsets, and connect to the data source through the Report Designer Component automation server.

Click the appropriate link to jump to that section:

  • Active Data Drivers
  • Crystal Data Object
  • COM data provider


Active Data Drivers

Modern Visual Basic applications often use advanced ActiveX components to connect to data sources. These data sources may include Data Access Objects (DAO) using the, Remote Data Objects (RDO), OLE DB providers, such as ActiveX Data Objects (ADO), COM data providers, and the Crystal Data Objects (CDO), or the Visual Basic data controls. Using the Active Data Drivers for Crystal Reports, you can design reports for your Visual Basic applications that use these same ActiveX data sources. Active data drivers include:

  • Crystal Reports database driver for Microsoft Data Access Objects (crdb_dao.dll).
  • Crystal Reports database driver for ODBC (crdb_odbc.dll) for RDO.
  • Crystal Reports database driver for Microsoft ActiveX Data Objects (crbd_ado.dll).
  • Crystal Reports database driver for COM data provider (crdb_com.dll).
  • Crystal Data Object COM DLL (cdo32.dll).
  • Crystal Reports database driver for Crystal Data Object (crdb_cdo.dll).

For more information on RDO, DAO, and ADO, refer to Microsoft documentation. For information on the Data Control, refer to your Visual Basic documentation. For information on CDO, see Crystal Data Object.

Occasionally, you may also need to create a report when the data source is not actually available at design time. Highly dynamic data may only be available at runtime. In such cases, the Field Definitions Driver (crdb_fielddef.dll) supports the use of Data definition files, which are tab-separated text files that define the fields in a data source but not the actual data.

Normally, developing applications using the Report Designer Component requires designing and saving one or more report files in advance to be accessed by the application at runtime. This process requires that the programmer has access to the data during design time, and that the application, upon installation, also installs whatever database drivers and files are required to make sure the reports can connect to the required data.

An alternative to runtime connectivity is to save data with the report files. The data is neatly packaged and available whenever the report is requested from your custom application. However, saving data with a report increases the file size of the report, wasting disk space. Furthermore, this technique produces a static report file in which the data cannot be updated without connectivity to the database.

The Field Definitions Driver allows you to create report files at design time without specifying an actual data source. Instead, the report is based on a data definition file, an ASCII text file with place holders to represent database fields. At runtime, you add code to your application to specify the actual source of data for the report.

The following topics are discussed in this section:

  • Using the Active Data Drivers
  • Creating data definition files
  • Using ActiveX data sources at design time


Using the Active Data Drivers

Designing and generating reports using the Crystal Active Data Drivers is a straightforward process, but requires several specific steps:

  • Select the design-time data source
  • Design the report
  • Obtain a Recordset from the runtime data source
  • Open the report
  • Pass the Recordset to the Active Data Driver
  • Print the report

The following sections demonstrate this process using the Crystal Active Data Driver with the Report Designer Component Automation Server in Visual Basic 6.0.


Select the design-time data source

When designing a report for your Visual Basic application, you can specify any ActiveX data source using the Active Data Drivers, or you can specify a data definition file so that the actual data is specified at runtime only. The following example uses OLEDB (ADO) to connect to xtreme.mdb through the Microsoft Jet OLE DB provider:

  1. Select Using the Report Wizard in the Crystal Reports Welcome dialog box, or click the new report icon on the Crystal Reports toolbar and select Using the Report Wizard in the Crystal Report Gallery dialog box.

    2. In this example, you can click Standard from the Choose a Wizard box. Then Click OK.

  2. In the Standard Report Creation Wizard box, under Available Data Sources:
    • Expand Create New Connections.
    • Expand OLE DB (ADO).
  3. In the OLE DB (ADO) dialog box, select Microsoft Jet 4.0 OLE DB Provider from the Provider box and click Next.
  4. In the Connection Information page:
    • Click the ellipse (...) button next to the Database Name box, browse to and select xtreme.mdb from \Program Files\Business Objects\Crystal Reports 11\Samples\En\Databases.
    • Click Finish.

      • In the Standard Report Creation Wizard box, under Available Data Sources and OLE DB (ADO), the selected data source is now visible.

  5. Expand the Tables node and double-click Customer to add the table to the Selected Tables box.

Note: For information on specifying an OLE DB provider or other ActiveX data source at design time, see Using ActiveX data sources at design time.


Design the report

Once you have selected an ActiveX data source, you can design your report just as you would design any other report.

  1. Click Next to move to the Fields page.
  2. Add fields to your report just as you would normally add fields to a report using the Standard Report Creation Wizard.
  3. When you are finished designing the report, click Finish.
  4. Apply any formatting or other changes that you feel are necessary to fine-tune the look of your report.
  5. Save the report when finished.

Note: Before saving your report, be sure to turn off the Save Data with Report option on the File menu. The sample data stored with the data definition file is unnecessary at runtime and will only increase the size of your report file.


Obtain a Recordset from the runtime data source

Once you have selected a data source or data definition file and designed a report based on that data source or file, you can begin programming your Visual Basic application to obtain a recordset from an ActiveX data source, open the report file, set the report file to use the recordset object from the ActiveX data source, then print or export the report file. This process requires using the functionality of the Report Designer Component.

The following tutorials use the Report Designer Component Automation Server in Visual Basic 6.0. This section assumes a familiarity with the Report Designer Component Automation Server. If you need more information on how to use the automation server, see the Report Designer Component Object Model.

To begin, you must obtain a Recordset object from a runtime ActiveX data source. This data source can be opened through DAO, RDO, ADO, the Visual Basic Data Control, or Crystal Data Objects (CDO). For information on DAO, RDO, and ADO, refer to Microsoft documentation. For information on the Visual Basic Data Control, refer to your Visual Basic documentation. For information on CDO, see Crystal Data Object.

This tutorial creates a Recordset object from the Customer table of the Xtreme.mdb sample database using ADO. The Recordset concept is used by DAO, and ADO. If you are using RDO, you will need to obtain a rdoResultSet object. If you are using CDO, you will need to obtain a Rowset object (see Crystal Data Object).

Note: You must add the ActiveX Data Object component to your Visual Basic project before performing the following steps. For instructions on using ADO with Visual Basic, refer to your Visual Basic documentation.

  • Declare variables for the Database and Recordset objects in your Visual Basic application. This can be handled in the declarations section of a form or module. Use code similar to this:

    • Dim Connection As New ADODB.Connection

    Dim RS As New ADODB.Recordset

  • Create a connection to the Xtreme database.

    • Connection.ConnectionString = _

    "Provider=Microsoft.Jet.OLEDB.4.0;" _

    + "Persist Security Info=False;Data Source=" _

    + "C:\Program Files\Business Objects\Crystal Reports 11" _

    + "\Samples\En\Databases\xtreme.mdb;Mode=Read"

    Connection.Open

  • Obtain a Recordset object from the Customers table of the Xtreme database.

    • RS.Open "Select * From Customer", _

    Connection, adOpenDynamic, adLockPessimistic, adCmdText


Open the report

Once you have obtained a Recordset object, you can begin working with the report file you created earlier. This example uses the Report Designer Component Automation Server to open a report file.

Note: You must add the Report Designer Component Automation Server component to your Visual Basic project before performing the following steps.

  • Declare variables for the Application and Report objects that you will obtain from the Report Designer Component Object Library in the automation server. This can be handled in the declarations section of a form or module.

    • Dim CRXApplication As New Craxdrt.Application

    Dim CRXReport As Craxdrt.Report

  • Obtain a Report object by opening the report file you created earlier. This example uses the file Customer.RPT.

    • Set CRXReport = CRXApplication.OpenReport("c:\reports\Customer.rpt", 1)


Pass the Recordset to the Active Data Driver

The Recordset object gets passed to the Active Data Driver through the SetDataSource method of the Database object in the Report Designer Component Object Library. You must first obtain a Database object from the Report object, then you must use the SetDataSource method to set the report to point at the recordset object for your Active data source.

The following code demonstrates how to obtain a Database object from the Report object:

Dim CRXDatabase As Craxdrt.Database

Set CRXDatabase = CRXReport.Database

Once you have a Database object for the Report object, you can pass the Active data source to the Report object using the SetDataSource method. This method requires three parameters. The first is the data source itself. The second parameter is a value indicating that the data source you are passing to the report is an ActiveX data source. This value must be 3. The third parameter is the table you are passing the data source to. Since you should only have one table defining the structure of the recordset, this should always be 1. For example:

CRXDatabase.SetDataSource RS, 3, 1


Print the report

Now that the data source for the report has been set to the ADO Recordset, you can print, preview, or export the report normally. For instance, the following code prints the report to the default printer:

CRXReport.PrintOut

Once the data source has been set in the report object, runtime reporting can proceed normally. All features of the Report Designer Component are available to you. See Report Designer Component Object Model for more information.


Data definition files

A report file designed using a data definition file, instead of a specific database or ODBC data source, contains information about the kind of data to place in the report instead of information about an actual data source. It looks for field types, rather than actual fields.

At design time, you create your report based on the data definition file. Previewing or printing the report at design time has little value except to format field placement and style. Since there is no real data in the text file, you cannot preview or print any data at design time.

Note: You can add sample data to the data definition file so that values will appear for each field in the Preview Tab at design time, but the values will be identical for all records, and grouping will not be available.

At runtime, your application opens the report file, just as it would any other report file. Instead of simply formatting and printing the file at runtime, though, you change the data source pointed at by the Field Definitions Driver, which is the data definition file, to a Recordset or Rowset object for an ActiveX data source such as ADO, RDO, DAO, or the Crystal Data Source (see Crystal Data Object).

Once the Recordset from the runtime data source is passed to the report the Crystal Query engine will call the correct database driver based on the type of recordset. The Report Designer Component can then generate the actual report using the existing data. The entire process saves you time designing reports and produces reports that are much more flexible and portable at runtime. For more information on data definition files, see Creating data definition files.


Creating data definition files

A data definition file is a tab-separated text file that contains information about field names, field types, and sample field data. Field names used in the data definition file must match the field names that will appear in the ActiveX data source that is specified at runtime. Field type information indicates the type of data in each field (string, numeric, date, and so on.) and, if it is a string field, the maximum length of the string. Finally, sample field data is simply sample data that Crystal Reports can display in the preview window while you design the report.

The following is an example of how fields are defined in a data definition file:

Order ID Long 1

Customer Name String 50 Sample string value

Order Date Date Jan 5, 2000

Order Amount Currency $1.00

The Field Definitions Driver supports the following data types in a data definition file:

Data Type Description

BLOB

Fields that contain bitmap images.

Boolean

True/False Boolean value.

Byte

8-bit integer value.

Currency

64-bit floating-point value that can include a currency or percent sign.

Date

Any date/time value. Examples include:

  • Jan 5, 1999
  • 07/11/97 5:06:07
  • 07/11/97
  • 23:30:01

Long, int32

32-bit integer value.

Memo

Any string value over 254 characters long. You must indicate the maximum number of characters for the string.

Number

64-bit floating-point value.

Short, int16

16-bit integer value.

String

Any string value under 254 characters long, such as a name, description, or identification number that is not meant to be interpreted numerically. You must indicate the maximum number of characters for the string.

Note: The data type BLOB is supported when connecting to RDO, ADO, DAO, and the data control at runtime but not when connecting to CDO.

Although data definition files can be created manually using a text editor such as Notepad, Crystal Reports provides a tool for simplifying the process. For more information, see Database Definition Tool.


Database Definition Tool

The Database Definition Tool is available from the Field Definitions Only dialog box when you begin designing a report based on the Field Definitions Driver. This tool allows you to design a data definition file as the first step of designing your report.

  1. In the Standard Report Creation Wizard, expand Create New Connection, and then expand Field Definitions Only.
  2. In the Field Definitions Only dialog box, click Create File to open the Database Definition Tool.
  3. Use the Database Definition Tool to create fields for your data definition file.

    4. Use the controls to enter field names, field types, and sample data that will appear in the Crystal Reports Preview Tab. If you select String as the field type, you will also be asked to specify a maximum string length.

  4. Click Add to add each new field to your data definition file.

    5. Each field appears in the list box at the bottom of the Database Definition Tool.

  5. Continue adding as many fields as necessary for your data definition file by entering the information in the controls of the Database Definition Tool, and clicking Add each time.

    6. You can delete a field that you have created by selecting the field in the list box and clicking Delete.

  6. Click File and then click Save when you are finished designing your data definition file.

    7. The Save File As dialog box appears.

  7. Save the data definition file where it can be accessed by your report file.

    8. Click Finish and the new data definition file will appear in the Available Data Sources box under the Field Definitions Only node.

  8. Double-click the table to add it to the Selected Tables box and continue creating your report.


Using ActiveX data sources at design time

The Active Data Drivers are intended to allow reports to be based on ActiveX data sources such as ADO and DAO. Data definition files allow you to avoid specifying an actual data source until runtime. However, you may often need to specify an ADO data source at design time for the report.

Each data source provides a unique dialog box to help you connect to the ActiveX data source. The dialog boxes provide options for selecting a data source to use in your report: specify an ODBC data source for RDO, specify an OLE DB provider and connection string for ADO, specify a database for DAO, specify a Prog ID for a Crystal Data Object, specify a Prog ID for a COM Data Object, or specify a data definition file. The Data Definition option has been thoroughly discussed earlier in this section. The remainder of this section will discuss selecting an ADO, RDO, DAO, CDO or COM data source.

The following topics are discussed in this section:

  • ODBC (RDO)
  • OLE DB (ADO)
  • Access/Excel (DAO)
  • COM connectivity
  • Crystal Data Object


ODBC (RDO)

  1. In the Available Data Sources box expand the Create New Connection node and then expand the ODBC (RDO) node.

    2. The ODBC (RDO) dialog box allows you to connect to an ODBC data source. You can select from a list of available data sources, browse for a File DSN, or enter a connection string.

    • Click Select Data Source to select from a list of available data sources.
      • Click Next if the ODBC data source requires log on information; specify a user name and password to log on.

    - or -

    • Click Find File DSN to browse to a DSN file.
      • Click Next if the ODBC data source requires log on information; specify a user name and password to log on.

    - or -

    • Click Connection String to add a connection string.
      • Click Next if the ODBC data source requires log on information; specify a user name and password to log on.
  2. After you select your data source, click Finish to return to the Standard Report Creation Wizard.
  3. Click Next in the Select Data Source dialog box.

    4. The Select Recordset dialog box appears.

  4. Under ODBC (RDO) you can now select from the Tables, Views, or Stored Procedures node.

    5. Note: The data source will determine which of these are available.

  5. Continue creating your report normally.


OLE DB (ADO)

  1. In the Standard Report Creation Wizard, expand Create New Connection, and then expand OLE DB (ADO).

    2. The OLE DB (ADO) dialog box allows you to select an OLE DB provider or search for a Microsoft Data Link File.

    • Click the desired OLE DB provider in the Provider box.

    - or -

    • Click Use Data Link File and then browse to a Microsoft Data Link File and select it.
  2. Click Next.

    3. This will bring you to the Connection Information page where you can enter the connection information for your data source.

  3. Click Finish to return to the Standard Report Creation Wizard dialog box.
  4. Under OLE DB (ADO), you can now select from the Tables, Views, or Stored Procedures node.

    5. Note: The data source will determine which of these are available.

  5. Continue creating your report normally.


Access/Excel (DAO)

  1. In the Standard Report Creation Wizard, expand Create New Connection, and then expand Access/Excel (DAO).

    2. The Access/Excel (DAO) dialog box allows you to select from a list of database types including Access, dBASE, Excel, HTML, Lotus, Paradox, and Text.

  2. Select the database type from the Database Type list.
  3. Click the Ellipse button (...) for the Database Name box to browse and select the desired data source.
  4. Click Secure Logon and enter any connection info in the boxes below if your data source requires security.
  5. Click Finish to return to the Standard Report Creation Wizard dialog box.
  6. Under Access/Excel (DAO) you can now select from the Tables, Views, or Stored Procedures node.

    7. Note: The data source will determine which of these are available.

  7. Continue creating your report normally.


COM connectivity

  1. In the Standard Report Creation Wizard, expand Create New Connection, and then expand COM Connectivity.

    2. The COM Connectivity dialog box allows you to connect to a registered COM data provider on your machine. The COM data provider enumerates a list of methods on the COM object that return ADO recordsets and presents them as Stored Procedures to the Crystal Reports Designer.

  2. Type the Prog ID in the Program ID box.

    3. For example: COMDemo.SalesData

  3. Click Finish to return to the Standard Report Creation Wizard dialog box.
  4. Under COM Connectivity, you can now select from the list of methods provided by the COM data provider.
  5. Continue creating your report normally.


Crystal Data Object

Crystal Data Object (CDO) connectivity is provided mainly for backward compatibility. For information on programmatic access to the Crystal Data Object, see Using the Crystal Data Object.


Crystal Data Object

The Crystal Data Object (CDO) is an ActiveX data source that allows you to define fields and records at runtime based on data that exists only at runtime. Through CDO, any data can become a virtual database and can be reported on using the power of the Report Designer Component. The Crystal Data Object does not support Memo or Blob fields.

Note: Crystal Data Object (CDO) connectivity is provided mainly for backward compatibility. This feature allows application developers to pass non-persistent data sources to Crystal reports at runtime. Using COM connectivity or Field Definitions connectivity is recommended instead of Crystal Data Object connectivity.

CDO, like DAO and ADO, is based on the Component Object Model (COM). Any development environment that supports COM interfaces can dynamically generate a set of data for a report without relying on a database that exists at design time.

Applications that produce data that does not exist outside of the running application have been unable, until now, to take advantage of the most powerful reporting features in the industry. CDO, however, solves that problem. For instance, applications that monitor system or network resources, or any constantly operating environment, can produce a current report on such information at any time. No longer does data need to be dumped to a separate database before analysis. Through CDO, the Active Data Driver, and the Report Designer Component, analysis is instant and up-to-date.

The following topics are discussed in this section:

  • Using the Crystal Data Object
  • Crystal Data Object Model


Using the Crystal Data Object

The Crystal Data Object is an ActiveX DLL that can be accessed from any Windows development environment that supports ActiveX. By creating a Rowset object, similar to a Recordset, and filling it with fields and data, you design a virtual database table that can be passed as an ActiveX data source to the Crystal Data Object driver.

Once the CDO Rowset has been created, it can be used just like any other active data source such as DAO or ADO. Use a procedure, much like the procedure described in Using the Active Data Drivers, to print, preview, or export a report at runtime that is based on the CDO data source. Simply replace the steps that explain how to pass a ADO Recordset to the Active Data Driver with appropriate steps for passing your CDO Rowset.

Note: Following are known limitations of the CDO:

  • The CDO does not support Memo or Blob fields.
  • If character string fields are used as data, the number of columns in the CDO is limited based on the number of characters in the string fields. For example, the more characters in the string, the fewer number of columns allowed in the rowset.

The rest of this section explains how to create a CDO Rowset in Visual Basic. However, as an ActiveX DLL, CDO can be used by any application development environment that supports ActiveX.

To create a CDO Rowset:

  • Obtain a CDO Rowset object
  • Add Fields to the Rowset object
  • Obtain data as rows
  • Add rows to the Rowset object

Use these steps as a guideline for creating your own CDO Rowsets for use with the Active Data Driver.


Obtain a CDO Rowset object

As stated earlier, CDO is a standard automation server. A Rowset object can be obtained from CDO using the Visual Basic CreateObject function:

Public CDOSet As Object

Set CDOSet = CreateObject("CrystalDataObject.CrystalComObject")

This Rowset object is, essentially, equivalent to a Recordset object you might obtain from DAO or another active data source. It is the Rowset object that you eventually pass to the Active Data Driver.


Add Fields to the Rowset object

Once you have a Rowset object, you need to define fields for the Rowset. These fields act as the virtual database fields. The field names you specify must match the field names specified in the data definition file. For more information on data definition files, see Creating data definition files.

Fields are added to a CDO Rowset using the AddField method:

CDOSet.AddField "Order ID", vbString

CDOSet.AddField "Company Name", vbString

CDOSet.AddField "Order Date", vbDate

CDOSet.AddField "Order Amount", vbCurrency

This code adds four fields to the Rowset with the specified field names and field types. The field types are based on constant values for the Variant data type. The constant names used here are from Visual Basic. For information on valid constant values, see the AddField method in the Crystal Data Source Object Models.


Obtain data as rows

Data to be added as rows in the Rowset can be collected in a two-dimensional array. The first dimension indicates rows, while the second dimension specifies fields for each row. The number of possible fields indicated by the second dimension must not exceed the number of fields you added to the Rowset using the AddField method. For example, you might define an array such as this:

Dim Rows(11, 3) As Variant

This specifies an array named Rows that contains 12 rows (0 to 11) and 4 columns (0 to 3). Notice that the four fields are defined with the AddField method, so the 4 columns in the Rows array are also defined. In addition, room has been made for 12 rows or records. Finally, since each field holds a different type of data, the array is defined as a Variant type.

Note: If your Rowset contains only a single field, you can use a one-dimensional array instead of two dimensional. The single dimension indicates the number of columns or fields in your Rowset.

Now that you have defined an array to hold data, you can begin adding values to the array. These array values will become the actual field values for the virtual database. Most likely, you will want to design a routine in your application that adds runtime data generated by your application into each cell of the array. The following code, however, demonstrates how you can explicitly add values to the array:

Rows(0, 0) = "1002" 'The first Order ID

Rows(0, 1) = "Cyclist's Trail Co." 'The first Company Name

Rows(0, 2) = #12/2/94# 'The first Order Date

Rows(0, 3) = 5060.2725 'The first Order Amount

From here, you could continue by adding a value to the first field of the second record, Rows (1, 0). You continue filling in data record by record and field by field. This technique, of course, requires a lot of code and is not very practical. Most real applications would contain a looping procedure that progressively filled in values for the array.


Add rows to the Rowset object

At this point, you have created a CDO Rowset object, added fields to the Rowset, and collected data in an array that will become part of a virtual runtime database. All that is left is to pass the data from the array to the Rowset object. This step is handled with a single method:

CDOSet.AddRows Rows

The AddRows method accepts a two-dimensional array containing the values you want added to the Rowset and, ultimately, added to a report file that is printed or exported. A one-dimensional array is used to add a single row with multiple fields.

Rows can be added to a CDO Rowset with multiple calls to the AddRows method. However, once you begin adding rows of data to a Rowset, you cannot add any new fields to the Rowset. Any call to AddFields after a successful call to AddRows will fail.

Once you finish populating your virtual database in the CDO Rowset object, you can pass this object as an active data source to the Active Data Driver using the SetDataSource method in the Report Designer Component Automation Server.For complete instructions on doing this, see Pass the Recordset to the Active Data Driver.


Crystal Data Object Model

Crystal Data Objects support several methods and properties that can be used to work with the Rowset object. The object model for CDO is completely defined and described in the section Crystal Data Source Object Models.


COM data provider

The Crystal Reports database driver for COM data provider (crdb_com.dll) allows Crystal Reports to report off COM data. Based on a given ProgID, this driver will enumerate the list of methods on the COM object that return ADO recordsets and will present them as Stored Procedures to the Crystal Reports Designer. The methods on the object can require parameters that will also propagate back to the Crystal Reports Designer, which will treat them as a standard Crystal Reports Parameter Type. This driver also supports accessing Chaptered or Hierarchical ADO recordsets.

Creating a COM Data provider is a straightforward process. This tutorial demonstrates how to create a COM Data provider that returns a recordset from the Xtreme Sample Database 11 ODBC data source, and how to connect to that data source.

Tip: The Xtreme Sample Database 11 ODBC data source is installed by default. If you do not have this data source installed, create the data source and point it to \Program Files\Crystal Decisions\Crystal Reports 11\Samples\En\Databases\xtreme.mdb

The following topics are discussed in this section:

  • Advantages of the COM data provider
  • Creating a new project and class
  • Creating a Report off the COM Data driver


Advantages of the COM data provider

The COM data provider provides significant enhancements to developers including:

  • The ability to report off of and manage multiple data sources.

    • Traditionally, reports created in Crystal Reports have been created from physical databases with the option of connecting to a database using either a native driver or an ODBC driver. With the COM driver, Crystal Reports is available to other types of data sources. You can create a report so that it can report from Active Data in the report designer.

  • The ability to easily separate report design from application creation when working with Active Data record sets.

    • With the COM Driver, the act of connecting to the data source and generating the recordset from which the report can be designed are now separate. You no longer need to write code to push data into the report. This means report designers can simply point to the DLL, and create their report without any concerns about having adequate sample data, access to the actual data, and so on. It is much simpler than designing reports via TTX information and one line of sample data. Unlike Data Definition (TTX) files, this method is for use only during design time. You should be able to use these reports at runtime; however, you cannot pass a recordset to the report at runtime (as can be done with TTX files). Another advantage of using this method is the ability to put your own interface into the report designer.


Creating a new project and class

The Crystal Data Source interface can be implemented inside almost any type of application. You might want to create and internal data source, for instance, inside the same standard executable application that you are implementing the Report Designer Component. On the other hand, you could create an ActiveX DLL that did nothing except implement Crystal Data Source. Your ActiveX DLL then could work as a separate data source to be accessed from other applications, much like ADO, RDO, and, DAO are used.

The following topics are discussed in this section:

  • Creating a new project
  • Adding a class module to a project
  • Adding a Sub Main() procedure
  • Adding a reference to the Microsoft ADO Library
  • Creating the functions
  • Compiling the ActiveX DLL


Creating a new project

For this tutorial, you will create an ActiveX DLL that can be referenced by other applications. One such application may be a standard executable that uses the COM Data driver with the Report Designer Component to produce reports based on this new ActiveX data source. The code will create functions that allow the user to select all the tables records, the records from a specific region, or the records with sales over a spcific amount.

  1. With Visual Basic running, select New Project from the File menu.

    2. The New Project dialog box appears.

  2. Select ActiveX DLL from the New Project dialog box, and click OK.

    3. Your new ActiveX DLL project is created.

  3. Select Class1 in the Project window, and make sure the Properties window is displayed.

    4. To display the Properties window, press the F4 key or select Properties Window from the View menu.

    Note: If you are not creating an ActiveX DLL, you may not have a class module in your project. See the next section, Adding a class module to a project.

  4. Change the value of the (Name) property for Class1 to DemoXtreme.
  5. Select Project1 in the Project window, and change the value of the (Name) property for Project1 to DemoCom.
  6. Save the project.

Use DemoXtreme as the name of the class file and DemoCom as the name of the project file.


Adding a class module to a project

Since you are creating an ActiveX DLL, your project already contains a class module. However, if you are creating a project that does not automatically include a class module, such as a Standard EXE project, you will need to complete the following steps.

  1. From the Project menu, select Add Class Module.

    2. The Add Class Module dialog box appears.

  2. Make sure Class Module is selected, and click Open.

    3. The new class module is added to your project, and the code window for the module appears.


Adding a Sub Main() procedure

Although a Sub Main() procedure is not required by ActiveX DLLs created in Visual Basic 5.0 or later, you may want to create a Sub Main() procedure to handle initialization processes. Developers working in Visual Basic 4.0 are required to add the Main subroutine to an Automation Server DLL project and specify that the project use Sub Main() as the entry point. If you are creating an ActiveX EXE in Visual Basic 4.0 or later, you should add the Sub Main() procedure to allow your code to determine if it is being started as a stand-alone application or as an out-of-process automation server.

The following steps demonstrate how to add a Sub Main() procedure in Visual Basic versions 5.0 and 6.0. If you add this procedure to the MyDataSource project, you can leave the procedure empty.

  1. From the Project menu in Visual Basic, select Add Module.

    2. The New Module dialog box appears.

  2. Leave the default Module type selected, and click Open.

    3. A new module, Module1, is added to your project.

  3. In the code window for the new module, add the following code:

    4. Sub Main()

    End Sub


Adding a reference to the Microsoft ADO Library

You need to reference the ADO library in order to create and pass the recordset to the report. To add the reference:

  1. From the Project menu, choose References.

    2. The References dialog box appears.

  2. Scroll through the Available References list to locate the Microsoft ActiveX Data Object 2.x library.
  3. Select the check box next to Microsoft ActiveX Data Object 2.x library.
  4. Click OK to save.


Creating the functions

Once you have added the ADO reference to your project, you can add the code to create and pass the recordset.

Dim Connection As New ADODB.Connection

Dim adoRs As New ADODB.Recordset

Private Sub Class_Initialize()

Set adoRs = New ADODB.Recordset

adoRs.Open "Customer", "Xtreme Sample Database 11", _

adOpenKeyset, adLockOptimistic, adCmdTable

End Sub

Public Function demoSelectRegion(ByVal Region As String) As ADODB.Recordset

Dim sqlStm As String

sqlStm = "SELECT * FROM Customer WHERE Region = '" _

& sRegion & "'"

Set demoSelectRegion = Connection.Execute(sqlStm)

End Function

Public Function demoSelectSales(ByVal Sales As Double) As ADODB.Recordset

Dim sqlStm As String

sqlStm = "SELECT * FROM Customer WHERE `Last Year's Sales` > " _

& Sales

Set demoSelectSales = Connection.Execute(sqlStm)

End Function

Public Function demoRecordset() As ADODB.Recordset

Dim sqlStm As String

sqlStm = "SELECT * FROM Customer "

Set demoNoParam = Connection.Execute(sqlStm)

End Function

Private Sub Class_Terminate()

cnn.Close

End Sub

Note: It is the responsibility of the Provider to close any recordsets that may be open.


Compiling the ActiveX DLL

Once you have finished adding the functions, you can compile the ActiveX DLL. When compiling ActiveX components, Visual Basic registers the component in the Windows Registry database. The name of the project, DemoCom in this case, is used as the name of the component. The name of the class module, DemoXtreme for this example, becomes the name of a creatable object. Once compiled, the component can be referenced by the COM Data driver.

  1. Make sure you save the entire project so that all source code is preserved.
  2. From the File menu, choose Make DemoCom.dll.

    3. Note: The name of the DLL that will be created is based on the name of your Visual Basic project file (.VBP), not on the project name as specified by the (Name) property.

  3. When the Make Project dialog box appears, select the location where the new DLL should reside.
  4. Click OK.

    5. The new DLL is created and registered.


Creating a Report off the COM Data driver

Once you have created the COM Data provider, you can create a report off the new data source.

  1. Select Using the Report Wizard in the Crystal Reports Welcome dialog box, or click the new report icon on the Crystal Reports toolbar and select Using the Report Wizard in the Crystal Report Gallery dialog box.

    2. In this example, you can click Standard from the Choose a Wizardbox. Then Click OK.

  2. In the Standard Report Creation Wizard box, under Available Data Sources:
    • Expand Create New Connections.
    • Expand COM Connectivity.
  3. In the COM Connectivity page:
    • Type DemoCom.DemoXtreme in the Program ID box.
    • Click Finish.

      • In the Standard Report Creation Wizard box, under the COM Connectivity node, in the Available Data Sources box, the selected data source is now visible.

  4. Double-click demoRecordset to add the Stored Procedure from the Com Data provider to the Selected Table box.
  5. Click Next to move to the Fields page.
  6. Add fields to your report just as you would normally add fields to a report using the Standard Report Creation Wizard.
  7. When you are finished designing the report, click Finish.
  8. Apply any formatting or other changes that you feel are necessary to fine-tune the look of your report.
  9. Save the report when finished.


Crystal Data Source Object Models

Crystal Reports provides support for reporting off data when no true data source exists. In this section you will find detailed information, including properties and methods, on Crystal Data Objects.

Click the appropriate link to jump to that section:

  • Crystal Data Source Object Models
  • Crystal Data Objects
  • CrystalComObject


Crystal Data Source Object Models

Crystal Reports includes two ActiveX based data source models to allow on-the-fly reporting when a true data source does not exist at design time, and the data at runtime does not exist in a relational or OLAP database. The Crystal Data Sources allow you to dynamically produce data at runtime inside your code, then pass the data to an existing report file. Both data source models are designed primarily for Visual Basic programmers, but they can be used within other development environments that support ActiveX components and interfaces.


Crystal Data Objects

Crystal Data Objects allow you to quickly design a set of relational data at runtime using standard Visual Basic arrays. For more information on using Crystal Data Objects in Visual Basic, see Crystal Data Object. To add a reference to the Crystal Data Objects component to your Visual Basic application, select the Crystal Data Object item in the Available References list box of the References dialog box. Crystal Data Objects do not support Memo or Blob fields.


CrystalComObject

The CDO component provides a single object named CrystalComObject. This object works much like a Recordset or Rowset that you might use in ADO, DAO, or RDO. Rather than connecting to an existing database, though, CDO allows you to fill it with data stored in a standard Visual Basic array. Once filled with data, the entire object can be passed to the "Grid Controls and the Crystal Report Engine" at runtime, producing a dynamic report filled with data only available at runtime.

To create an instance of the CrystalComObject in Visual Basic, use the following code as an example:

Dim cdoRowset As Object

Set cdoRowset = CreateObject("CrystalComObject.CrystalDataObject")

The following topics are discussed in this section:

  • CrystalComObject Properties
  • CrystalComObject Methods


CrystalComObject Properties

The CrystalComObject provides a single property:

RowCount

Use this property to obtain the number of rows in the rowset once data has been assigned. This is especially useful if data is added to the Rowset in several steps, each step adding more to the size of the Rowset. This value can be used to find out how many rows have been added.

Example

Dim numRows As Long

numRows = cdoRowset.RowCount


CrystalComObject Methods

The CrystalComObject uses the following methods. These methods each have a section describing their parameters and returns, followed by an example.

  • AddField
  • AddRows
  • DeleteField
  • GetColCount
  • getEOF
  • GetFieldData
  • GetFieldName
  • GetFieldType
  • MoveFirst
  • MoveNext
  • MoveTo
  • Reset


AddField

Function AddField(FieldName As String, [FieldType]) As Boolean

Use this method to add fields to a rowset before adding data. The rowset must have fields defined before data can be added using the AddRows method.

Parameters

FieldName

A string value specifying the name of the field.

FieldType

An optional value specifying the data type that will be contained in this field. Use Visual Basic VarType constants to specify the data type. If this value is omitted, the vbVariant type will be used.

Returns

A Boolean value indicating whether or not the field was successfully added to the Rowset.

Example

cdoRowset.AddField "Order ID", vbString

cdoRowset.AddField "Company Name", vbString

cdoRowset.AddField "Order Amount", vbCurrency


AddRows

Sub AddRows(RowData)

Use this method to assign an array of data to the CDO Rowset.

Parameters

RowData

A standard Visual Basic two-dimensional array. The first dimension specifies the number of rows in the Rowset, while the second dimension specifies the number of fields for each row. A one-dimensional array is used to add a single row with multiple fields. When this array is dimensioned, it must be defined As Variant. For example:

Dim Rows(11, 3) As Variant

This example creates an array that will hold 12 rows with 4 fields. You must assign data to all cells in the array before assigning the array to the Rowset using AddRows.

Example

cdoRowset.AddRows Rows


DeleteField

Function DeleteField(FieldName As String) As Boolean

This method removes an existing field from the Rowset. If the field contains any data, that data is lost.

Parameters

FieldName

The name of the field you want to delete from the Rowset.

Returns

A Boolean value indicating whether or not the field was successfully deleted. If the field does not exist, this function will return False.

Example

cdoRowset.DeleteField "Company Name"


GetColCount

Function GetColCount() As Integer

This function returns the number of columns or fields currently in the Rowset.

Returns

An integer value indicating the number of fields in the Rowset.

Example

Dim numFields As Integer

numFields = cdoRowset.GetColCount


getEOF

Function getEOF() As Boolean

Use this function to determine if the current row in the Rowset is the last row.

Returns

True if the current row is the last row in the Rowset. False if the current row is anywhere else in the Rowset.

Example

If cdoRowset.getEOF Then

cdoRowset.MoveFirst

End If


GetFieldData

Function GetFieldData(column As Integer)

This method obtains the current value of a specific column in the Rowset for the currently selected row.

Parameters

column

A number indicating which field (column) of the row you want the current value of. Rowset columns, like array dimensions, are 0 based. The first column is 0, the second is 1, and so on.

Returns

A variant value that contains the data for the specified field of the current row.

Example

Dim fieldData As Variant

fieldData = cdoRowset.GetFieldData 0


GetFieldName

Function GetFieldName(column As Integer) As String

Returns the name of the specified field (column). Field names are assigned using AddField.

Parameters

column

A number indicating which field (column) of the Rowset you want the name of. Rowset columns, like array dimensions, are 0 based. The first column is 0, the second is 1, and so on.

Returns

A string containing the name of the specified field.

Example

Dim secondField As String

secondField = cdoRowset.GetFieldName 1


GetFieldType

Function GetFieldType(Field) As Integer

Use this method to obtain the type of data contained by a field in the Rowset. Data types are assigned to fields using AddField.

Parameter

Field

This parameter indicates which field you are querying for the type of data contained. This field can accept either a numeric value or a string value. If you use a numeric value, it must be a number representing the field (column) of the Rowset you want to find out the data type of. Rowset columns, like array dimensions, are 0 based. The first column is 0, the second is 1, and so on. If a string is used, the string must contain the name of the field.

Returns

A Visual Basic VarType constant indicating the type of data contained in the field.

Example

Dim dataType As Integer

dataType = cdoRowset.GetFieldType "Customer Id"

If dataType = vbString Then

' Do something with the string

End If


MoveFirst

Function MoveFirst() As Boolean

This method moves to the first row (record) in the Rowset.

Returns

A Boolean value indicating whether or not the current row was successfully set to the first row. If the Rowset contains no data, this method will return False.

Example

cdoRowset.MoveFirst


MoveNext

Function MoveNext() As Boolean

Moves to the next row (record) in the Rowset. The current record is set to the new row.

Returns

A Boolean value indicating whether or not the current record was successfully set to the next row in the Rowset. This function will return False if the current record before calling the method is the last row of the Rowset.

Example

cdoRowset.MoveNext


MoveTo

Function MoveTo(recordNum As Long) As Boolean

Moves the current record to the specified record number in the Rowset.

Parameter

recordNum

A 1-based value indicating to which record in the Rowset you want to move. The first record is 1, the second is 2, and so on.

Returns

A Boolean value indicating whether or not the current record was successfully set to the specified record number. This method returns False is the specified record does not exist.

Example

cdoRowset.MoveTo 9


Reset

Sub Reset()

Resets the Rowset, clearing all fields and data.

Example

cdoRowset.Reset


Deprecated and Retired API Reference

The following developer APIs, interfaces, methods, and properties are retired or deprecated. Retired features are no longer available or supported. Deprecated features, while they may be supported for backwards compatibility, are not recommended for use in the current version of Crystal Reports. Deprecated features may become obsolete in future versions of the product.

Click the link to jump to that section:

  • Retired Developer APIs
  • Retired P2smon.dll functions
  • Deprecated RDC Interfaces
  • Deprecated RDC Properties
  • Deprecated RDC Methods
  • Deprecated RDC Export Format Types

Note: For more information on retired features, see the Release Notes in the \Doc directory on your CD.


Retired Developer APIs

Crystal Reports provides many new options to meet your development needs in COM, .NET, and Java environments. Report Application Server (RAS) is a reporting SDK and server intended for use in a web application to preview, modify and create Crystal reports. RAS works equally well in a .NET, Java, or COM architecture; it provides similar functionality and performance regardless of the platform you choose. RAS uses well-known Crystal Reports technology as its foundation, so the reports you create and modify through RAS are fully compatible with other version 11 Crystal Reports products. RAS is a component of the BusinessObjects Enterprise Infrastructure, which is suitable for large-scale deployments and is available to meet your organization's enterprise reporting needs. For more information, see http://www.businessobjects.com/ and follow the links to reporting products.

Note: Some of the older Developer APIs have been retired as shown in the following list.

Crystal Data Source Type Library (crsource.tlb)

The Crystal Data Source Type Library is no longer supported and no longer available as of Crystal Reports version 9.

Crystal Reports ActiveX Control (crystl32.ocx)

The Crystal Reports ActiveX control is no longer supported and no longer available as of Crystal Reports version 9.

For information on migrating from the Crystal Reports ActiveX control to the RDC, go to http://support.businessobjects.com/library/ and enter the file name scr8-ocxtordc.pdf.

Crystal Reports Automation Server (cpeaut32.dll)

The Crystal Reports Automation Server is no longer supported and no longer available as of Crystal Reports version 9.

For information on migrating from the Crystal Reports Automation Server to the RDC, go to http://support.businessobjects.com/library/ and enter the file name scr8-cpeauttordc.pdf.

Crystal Reports Print Engine (crpe32.dll)

The Crystal Reports Print Engine is no longer a supported method of access (API) for Crystal Reports. OEM partners may contact OEM support for additional information.

RDC Runtime C Headers

The RDC runtime C headers are no longer supported as of Crystal Reports version 9.

Design Time Control for Microsoft Visual Interdev (DTC)

The DTC is no longer supported as of Crystal Reports version 9.


Retired P2smon.dll functions

The Active Data driver (p2smon.dll) is no longer supported as of Crystal Reports version 9. Active data is now handled through individual database drivers. For more information see "Active Data" in the Crystal Reports Developer Runtime Help (Runtime.hlp).

In order to retain backwards compatibility of it's runtime functions, the p2smon.dll is available in the \tools directory on the Crystal Reports installation CD. Include the p2smon.dll if you have any the following functions in your application:

Click the link to jump to that section:

  • CreateFieldDefFile
  • CreateReportOnRuntimeDS
  • SetActiveDataSource


CreateFieldDefFile

This is a retired function. It creates a tab-separated text file, known as a field definition file, which represents the structure of the data in a specified Recordset or Rowset object. This field definition file can then be used to design a report file using the Runtime DB option in the Create Report Expert of Crystal Reports. When designing an application that prints, previews, or exports the report, the field definition file can be replaced, at runtime, by the Recordset or Rowset object.

C Syntax

BOOL FAR PASCAL CreateFieldDefFile(LPUNKNOWN FAR *lpUnk,

LPCSTR fileName,

BOOL bOverWriteExistingFile);

Visual Basic Syntax

Declare Function CreateFieldDefFile Lib "p2smon.dll"(lpUnk As Object, _

ByVal fileName As String, ByVal bOverWriteExistingFile As Long) _

As Long

Parameters

Parameter | Description
lpUnk | The active data source used to create the field definition file. In C or C++, this is a pointer to an unknown derived COM interface relating to a DAO or ADO Recordset. In Visual Basic, this is a Recordset or Rowset object.
fileName | The path and file name of the field definition file to be created.
bOverWriteExistingFile | If a field definition file already exists with the specified path and file name, this flag indicates whether or not to overwrite that file.

Return Value

Returns 0 (False) if the call failed. Returns 1 (True) if the call succeeded and the field definition file was created.

Remarks

This function creates a field definition file only, and does not create a report file. You must create a report file using Crystal Reports.


CreateReportOnRuntimeDS

This is a retired function. It creates a tab-separated text file, known as a field definition file, which represents the structure of the data in a specified Recordset or Rowset object. Then, the function creates a blank report file based on this field definition file. When designing an application that prints, previews, or exports the report, the field definition file can be replaced by the Recordset or Rowset in the active data source.

C Syntax

BOOL FAR PASCAL CreateReportOnRuntimeDS(LPUNKNOWN FAR *lpUnk,

LPCSTR reportFile,

LPCSTR fieldDefFile,

BOOL bOverWriteFile,

BOOL bLaunchDesigner);

Visual Basic Syntax

Declare Function CreateReportOnRuntimeDS Lib "p2smon.dll" ( _

lpUnk As Object, ByVal reportFile As String, ByVal fieldDefFile _

As String, ByVal bOverWriteFile As Long, ByVal bLaunchDesigner _

As Long) As Long

Parameters

Parameter | Description
lpUnk | The active data source used to create the field definition file. In C or C++, this is a pointer to an Unknown derived COM interface relating to a DAO or ADO Recordset. In Visual Basic, this is a Recordset or Rowset object.
reportFile | The path and file name of the report file to be created.
fieldDefFile | The path and file name of the field definition file to be created.
bOverWriteFile | If a field definition file already exists with the specified path and file name, this flag indicates whether or not to overwrite that file.
bLaunchDesigner | If True (1), Crystal Reports is launched with the newly created report file opened. Crystal Reports must be installed on the system.

Return Value

Returns 0 (False) if the call failed. Returns 1 (True) if the call succeeded and the field definition file was created.

Remarks

This function creates a field definition file, then creates a report file based on that field definition file. The function CreateFieldDefFile is unnecessary when this function is used.


SetActiveDataSource

This is a retired function. It is used to provide information about a data source to the Crystal Active Data database driver. For instance, if a report has been designed using the Crystal Active Data Driver, this method can be used to provide an active data source for the report, such as a DAO, ADO, or RDO recordset or a CDO rowset. In this case, the object passed to the third parameter of this function replaces, at runtime, the field definition file used to create the report.

Visual Basic syntax

Declare Function SetActiveDataSource Lib "p2smon.dll" _

(ByVal printJob as Integer, ByVal tableNum as Integer, x as Object) _

As Long

Parameters

Parameter | Description
printJob | Specifies the print job to which you want to add the active data source.
tableNum | The 0 based number of a table for which you want to pass the active data recordset or rowset.
x | Variant data passed to the database driver such as a DAO, ADO or RDO recordset or a CDO rowset.

Return Value

Returns 0 (False) if the call failed. Returns 1 (True) if the call succeeded the data source was passed.

Remarks

The SetActiveDataSource function is used in conjunction with the Crystal Report Print Engine (Crpe32.dll) in a Visual Basic application.OEM partners may contact OEM support for additional information.


Deprecated RDC Interfaces

Deprecated interfaces | Explanation
IFieldDefinition Interface | This interface was originally defined to provide generic properties for the various types of field definition objects. It is still the base for all field definition objects. In lieu of this object, use the FieldDefinitions Collection. After using the Item property to get a field definition object from the Collection, you can use the Kind property to determine what type of field definition object the item is. All field definition objects have the Kind property.
IReportObject | This interface was originally defined to provide generic properties for the various types of report objects. It is still the base for all report objects. In lieu of this object, use the ReportObjects Collection. After using the Item property to get a report object from the Collection, you can use the Kind property to determine what type of report object the item is. All report objects have the Kind property.


IFieldDefinition Interface

This is a deprecated interface. It was originally defined to provide generic properties for the various types of field definition objects. It is still the base for all field definition objects. In lieu of this object, use the FieldDefinitions Collection. After using the Item property to get a field definition object from the Collection, you can use the Kind property to determine what type of field definition object the item is. All field definition objects have the Kind property.

IFieldDefinition Object Properties

Property | Description | Read/Write | Restriction in event handler
Kind | CRFieldKind. Gets field definition kind. | Read only | None
Name | String. Gets field definition unique formula name. | Read only | None
NextValue | Variant. Gets the field next value. | Read only | None
NumberOfBytes | Integer. Gets field number of bytes. | Read only | None
Parent | Report Object. Gets reference to the parent object. | Read only | None
PreviousValue | Variant. Gets the field previous value. | Read only | None
UseCount | Long. Gets the field use count. | Read only | None
Value | Variant. Gets the field current value. | Read only | None
ValueType | CRFieldValueType. Gets the field value type. | Read only | None


IReportObject

This is a deprecated interface. It was originally defined to provide generic properties for the various types of report objects. It is still the base for all report objects. In lieu of this object, use the ReportObjects Collection. After using the Item property to get a report object from the Collection, you can use the Kind property to determine what type of report object the item is. All report objects have the Kind property

IReportObject Properties

Property | Description | Read/Write | Restriction in event handler
BackColor | OLE_COLOR. Gets or sets the object background color. | Read/Write | Can be written only when formatting idle or active.
BorderColor | OLE_COLOR. Gets or sets the object border color. | Read/Write | Can be written only when formatting idle or active.
BottomLineStyle | CRLineStyle. Gets or sets bottom line style. | Read/Write | Can be written only when formatting idle or active.
CloseAtPageBreak | Boolean. Gets or sets the close border on page break option. | Read/Write | Can be written only when formatting idle or active.
EnableTightHorizontal | Boolean. Gets or sets the enable tight horizontal option. | Read/Write | Can be written only when formatting idle or active.
HasDropShadow | Boolean. Gets or sets the border drop shadow option. | Read/Write | Can be written only when formatting idle or active.
Height | Long. Gets or sets object height, in twips. | Read/Write | Can be written only when formatting idle or active.
KeepTogether | Boolean. Gets or sets the keep object together option. | Read/Write | Can be written only when formatting idle or active.
Kind | CRObjectKind. Gets which kind of object (for example, box, cross-tab, field). | Read only | None
Left | Long. Gets or sets the object upper left position, in twips. | Read/Write | Can be written only when formatting idle or active.
LeftLineStyle | CRLineStyle. Gets or sets the left line style. | Read/Write | Can be written only when formatting idle or active.
Name | String. Gets or sets the object name. | Read/Write | Can be written only when formatting idle or active.
NeedUpdatedPages | Gets whether the user needs to update pages for display due to changes in the report. | Read only | None
Parent | Section Object. Reference to the parent object. | Read only | Can be written only when formatting idle or active.
RightLineStyle | CRLineStyle. Gets or sets the right line style. | Read/Write | Can be written only when formatting idle or active.
Suppress | Boolean. Gets or sets the object visibility. | Read/Write | Can be written only when formatting idle or active.
Top | Long. Gets or sets the object upper top position, in twips. | Read/Write | Can be written only when formatting idle or active.
TopLineStyle | CRLineStyle. Gets or sets the top line style. | Read/Write | Can be written only when formatting idle or active.
Width | Long. Gets or sets the object width, in twips. | Read/Write | Can be written only when formatting idle or active.


Deprecated RDC Properties

Deprecated properties | Explanation
IndexUsed | Deprecated as of Crystal Reports 9, with no replacement. Integer. This property was originally defined in the TableLink Object to get the table link index used.
LogonDatabaseName | This property was originally defined in the DatabaseTable Object to get the logon database name. In lieu of this method, use the name value pair in the ConnectionProperty Object. For example: Name is "Database Name" and the value is the file path and name of the data source. Note: The name value pair will depend on the data source accessed.
LogonServerName | This property was originally defined in the DatabaseTable Object to get the logon server name. In lieu of this method, use the name value pair in the ConnectionProperty Object. For example: Name is "Server" and the value is the server name of the data source. Note: The name value pair will depend on the data source accessed.
LogonUserID | This property was originally defined in the DatabaseTable Object to get the logon user ID. In lieu of this method, use the name value pair in the ConnectionProperty Object. For example: Name is "User ID" and the value is the user name required to connect to the data source. Note: The name value pair will depend on the data source accessed.
MorePrintEngineErrorMessages | Deprecated as of Crystal Reports 9, with no replacement. Boolean. This property was originally defined in the Report Object to get or set the report option that indicates whether to pop up database error dialogs during printing when a Report Engine error occurs.
PartialMatchEnabled | Deprecated as of Crystal Reports 9, with no replacement. Boolean. This property was originally defined in the TableLink Object to get the table link partial-match enabled option.
SessionUserID | This property was originally defined in the DatabaseTable Object to get the session user ID. In lieu of this method, use the name value pair in the ConnectionProperty Object where name is "Session UserID" and the value is the user name required to connect to the data source.
SubLocation | This property was originally defined in the DatabaseTable Object to get the table sublocation. In lieu of this method, use the name value pair in the ConnectionProperty Object where name is "Table Name" and value is the name of the database table.
TranslateDosMemos | Deprecated as of Crystal Reports 9, with no replacement. Boolean. This property was originally defined in the Report Object to gets or set the report option that indicates whether to translate DOS memos.
TranslateDosStrings | Deprecated as of Crystal Reports 9, with no replacement. Boolean. This property was originally defined in the Report Object to get or set the report option that indicates whether to translate DOS strings.


Deprecated RDC Methods

Deprecated methods | Explanation
ConvertDatabaseDriver Method (Database Object) | This method was originally defined to convert the database driver DLL used by the report. In lieu of this method, use the DLLName property of the DatabaseTable Object and the Add method, Delete method and DeleteAll method of the ConnectionProperties Collection to reset the connection properties.
SetLogOnInfo Method (DatabaseTable Object) | This method was originally defined to log on to the data source so table data can be accessed. In lieu of this method, use the name value pairs in the ConnectionProperty Object to provide the connection information needed to log on to the data source. Note: The name and value pairs will depend on the data source accessed.
SetMorePrintEngineErrorMessages Method (Application Object) | Deprecated as of Crystal Reports 9, with no replacement. This method was originally defined to set the global more print engine error messages option.
SetSessionInfo Method (DatabaseTable Object) | This method was originally defined to allow the user to log on to a secured Access session. In lieu of this method, use the name value pairs in the ConnectionProperty Object. These would be "Session UserID" where the value is the session's user name and "Session Password" where the value is the session's password.


ConvertDatabaseDriver Method (Database Object)

This is a deprecated method. This method was originally defined to convert the database driver DLL used by the report. In lieu of this method, use the DLLName property of the DatabaseTable Object and the Add method, Delete method and DeleteAll method of the ConnectionProperties Collection to reset the connection properties.

Syntax

Sub ConvertDatabaseDriver (pDLLName As String, blDoImmediateConvert as Boolean)

Parameters

Parameter | Description
pDllName | Specifies the new DLL for the database driver.
blDoImmediateConvert | Specifies when the database driver will be converted. If True, the database driver is converted when the report is previewed, or the when the database is verified. If False, the database driver is converted when the report is refreshed in the preview window.

Remarks
  • Set blDoImmediate to False when you want the user to be prompted for the data source information. This applies to reports that are previewed and refreshed in the Crystal Report Viewer, and to reports that are exported or saved to a Crystal Report format (.rpt), and previewed and refreshed in the Crystal Reports Designer. When the report is previewed, a dialog box for the new data source appears. For example, converting to ODBC (P2sodbc.dll) opens the Set Data Source dialog box, while converting to OLEDB (P2soledb.dll) opens the Data Link Properties dialog box.
  • Set blDoImmediateConvert to True when you want to set the data source at runtime. Additional code must be added to set the logon information for the data source, and to verify the database. One exception is converting to OLEDB (P2soledb.dll). Since there is no method to set the provider at runtime the Data Links dialog box will always prompt for the data source. In this case only the code to convert the database driver is required.
  • Once the database is converted, and the data source is set, either through code, or through a dialog box, three additional prompts may appear:
    • Logon to the data source

      • This dialog box allows you to log on to the correct data source. If the data source is not secured, you can click OK without entering any logon information.

    • Verify the database

      • This is a message warning the user that the database file has changed and the report is being updated.

    • Map the fields

      • This dialog box allows you to map the fields that have changed with the new data source. For more information on mapping fields see "Remapping processes" in the Crystal Reports Online Help (crw.chm).

Sample

The following code demonstrates how to convert the database driver to ODBC (P2sodbc.dll) using the ConverDataBaseDriver method. The ODBC data source is pointing to a Microsoft Access database.

'Instantiate the report object.

Set m_Report = New CrystalReport1

' Convert the database driver to ODBC.

m_Report.Database.ConvertDatabaseDriver "p2sodbc.dll", True

' Set the logon information for the ODBC data source.

' If the logon information is not set, an error will be produced when the

' report is previewed or exported.

m_Report.Database.Tables(1).SetLogOnInfo "Xtreme Sample Database 10", "", "", ""

' Verify the database.

' If the database is not verified before exporting, an error will be produced.

' If the database is not verified before previewing the report, the user may be

' prompted when the report is refreshed in the Crystal Report Viewer.

m_Report.Database.Verify


SetLogOnInfo Method (DatabaseTable Object)

This is a deprecated method. This method was originally defined to log on to the data source so table data can be accessed. In lieu of this method, use the name value pairs in the ConnectionProperty Object to provide the connection information needed to log on to the data source.

Note: The name and value pairs will depend on the data source accessed.

Syntax

Sub SetLogOnInfo (pServerName As String,

[pDatabaseName], [pUserID], [pPassword])

Parameters

Parameter | Description
pServerName | Specifies the name of the server or ODBC data source where the database is located (that is, CRSS).
[pDatabaseName] | Specifies the name of the database.
[pUserID] | Specifies a valid user name for logging on to the data source.
[pPassword] | Specifies a valid password for logging on to the data source.


SetMorePrintEngineErrorMessages Method (Application Object)

This is a deprecated method as of Crystal Reports 9, with no replacement. This method was originally defined to set the global more print engine error messages option.

Syntax

Sub SetMorePrintEngineErrorMessages (bl As Boolean)

Parameter

Parameter | Description
bl | Specifies whether the option is selected (TRUE)


SetSessionInfo Method (DatabaseTable Object)

This is a deprecated method. This method was originally defined to allow the user to log on to a secured Access session. In lieu of this method, use the name value pairs in the ConnectionProperty Object. These would be "Session UserID" where the value is the session's user name and "Session Password" where the value is the session's password.

Syntax

Sub SetSessionInfo (pSessionUserID As String, pSessionPassword As String)

Parameters

Parameter | Description
pSessionUserID | Specifies the Access userID used to log on to an Access session.
pSessionPassword | Specifies the session password for Access secured session.

Remarks

In Microsoft Access 95 and later, an Access database can have session security (also known as user-level security), database-level security, or both. If the Access database contains only session security, simply pass the session password to the SessionPassword parameter. If the Access database contains database-level security, use a linefeed character, Chr(10), followed by the database-level password. For example:

object.SetSessionInfo "userID", Chr(10) & "dbpassword"

If the Access database contains both session security and database-level security, use the session password followed by the linefeed character and the database password.

object.SetSessionInfo "userID", _

"sesspswd" & Chr(10) & "dbpassword"

Alternately, database-level security can also be handled by assigning the database-level password to the Password parameter of the SetLogOnInfo Method (DatabaseTable Object).


Deprecated RDC Export Format Types

Deprecated format type | Explanation
Data Interchange Format | Deprecated as of Crystal Reports 9, with no replacement. This export format type is now obsolete and was set through the FormatType property of the ExportOptions Object using the crEFTDataInterchange constant. The export format DLL u2fdif.dll is no longer shipped with Crystal Reports.
Lotus Works format | Deprecated as of Crystal Reports 9, with no replacement. This export format type is now obsolete and was set through the FormatType property of the ExportOptions Object using the crEFTLotus123WK1, crEFTLotus123WK3, and crEFTLotus123WKS constants. The export format DLL u2works.dll is no longer shipped with Crystal Reports.


Business Objects Information Resources

Business Objects offers a full documentation set covering its products and their deployment. Additional support and services are also available to help maximize the return on your business intelligence investment. The following sections detail where to get Business Objects documentation and how to use the resources at Business Objects to meet your needs for technical support, education, and consulting.


Documentation

You can find answers to your questions on how to install, configure, deploy, and use Business Objects products from the documentation.

What's in the documentation set?

View or download the Business Objects Documentation Roadmap, available with the product documentation at http://www.businessobjects.com/support/.

The Documentation Roadmap references all Business Objects guides and lets you see at a glance what information is available, from where, and in what format.

Where is the documentation?

You can access electronic documentation at any time from the product interface, the web, or from your product CD.

Documentation from the products

Online help and guides in Adobe PDF format are available from the product Help menus. Where only online help is provided, the online help file contains the entire contents of the PDF version of the guide.

Documentation on the web

The full electronic documentation set is available to customers on the web from support web site at: http://www.businessobjects.com/support/.

Documentation on the product CD

Look in the docs directory of your product CD for versions of guides in Adobe PDF format.

Send us your feedback

Do you have a suggestion on how we can improve our documentation? Is there something you particularly like or have found useful? Drop us a line, and we will do our best to ensure that your suggestion is included in the next release of our documentation: documentation@businessobjects.com.

Note: If your issue concerns a Business Objects product and not the documentation, please contact our Customer Support experts. For information about Customer Support visit: http://www.businessobjects.com/support/.


Customer support, consulting and training

A global network of Business Objects technology experts provides customer support, education, and consulting to ensure maximum business intelligence benefit to your business.

How can we support you?

Business Objects offers customer support plans to best suit the size and requirements of your deployment. We operate customer support centers in the following countries:

  • USA
  • Australia
  • Canada
  • United Kingdom
  • Japan

Online Customer Support

The Business Objects Customer Support web site contains information about Customer Support programs and services. It also has links to a wide range of technical information including knowledgebase articles, downloads, and support forums.

http://www.businessobjects.com/support/

Looking for the best deployment solution for your company?

Business Objects consultants can accompany you from the initial analysis stage to the delivery of your deployment project. Expertise is available in relational and multidimensional databases, in connectivities, database design tools, customized embedding technology, and more.

For more information, contact your local sales office, or contact us at:

http://www.businessobjects.com/services/consulting/

Looking for training options?

From traditional classroom learning to targeted e-learning seminars, we can offer a training package to suit your learning needs and preferred learning style. Find more information on the Business Objects Education web site:

http://www.businessobjects.com/services/training


Useful addresses at a glance

Address | Content
Business Objects product information http://www.businessobjects.com | Information about the full range of Business Objects products.
Product documentation http://www.businessobjects.com/support | Business Objects product documentation, including the Business Objects Documentation Roadmap.
Business Objects Documentation mailbox documentation@businessobjects.com | Send us feedback or questions about documentation.
Online Customer Support http://www.businessobjects.com/support/ | Information on Customer Support programs, as well as links to technical articles, downloads, and online forums.
Business Objects Consulting Services http://www.businessobjects.com/services/consulting/ | Information on how Business Objects can help maximize your business intelligence investment.
Business Objects Education Services http://www.businessobjects.com/services/training | Information on Business Objects training options and modules.