Business objects CRYSTAL REPORTS 10 User Manual

Crystal Reports™ 10 Technical Reference Guide

Business Objects, SA.

North American Corporate Headquarters

3030 Orchard Parkway

San Jose, CA 95134

Issue 1.

No part of this documentation may be stored in a retrieval system, transmitted or reproduced in any way, except in accordance with the terms of the applicable software license agreement. This documentation contains proprietary information of Business Objects SA., and/or its suppliers.

Trademark Acknowledgements

The Business Objects logo, BusinessObjects, Crystal Reports, and Crystal Enterprise are trademarks or registered trademarks of Business Objects SA in the United States and/or other countries. All other trademarks or registered trademarks referenced are the property of their respective owners.

Contents

Chapter 1: Welcome to Crystal Reports Development

About Crystal Reports ....................................................................... 4

About the online help ....................................................................... 4

Product registration .......................................................................... 6

Customer Handbook ......................................................................... 7

Crystal Care technical support .......................................................... 7

Crystal Training ................................................................................. 8

Crystal Consulting ............................................................................ 8

Document conventions ..................................................................... 8

Chapter 2: Report Designer Component Object Model

Overview of the Report Designer Object Model ............................. 14

Unification of the RDC object model .............................................. 15

Runtime licensing ............................................................................ 15

Object naming conflicts .................................................................. 15

Objects and Collections .................................................................. 16

Creatable Objects ........................................................................... 16

Application Object .......................................................................... 17

Area Object ....................................................................................24

Areas Collection .............................................................................. 28

BlobFieldObject Object .................................................................. 28

BoxObject Object ........................................................................... 32

ConnectionProperty Object ............................................................ 34

ConnectionProperties Collection .................................................... 41

Crystal Reports Technical Reference Guide i

CrossTabGroup Object ................................................................... 44

CrossTabGroups Collection ............................................................ 46

CrossTabObject Object ................................................................... 47

Database Object ............................................................................. 50

DatabaseFieldDefinition Object ...................................................... 58

DatabaseFieldDefinitions Collection ............................................... 59

DatabaseTable Object ..................................................................... 60

DatabaseTables Collection .............................................................. 64

ExportOptions Object ..................................................................... 68

FieldDefinitions Collection ............................................................. 75

FieldElement Object ........................................................................ 76

FieldElements Collection ................................................................. 87

FieldMappingData Object ............................................................... 89

FieldObject Object ......................................................................... 89

FormattingInfo Object .................................................................... 98

FormulaFieldDefinition Object ....................................................... 99

FormulaFieldDefinitions Collection .............................................. 101

GraphObject Object ..................................................................... 103

GroupNameFieldDefinition Object ............................................... 112

GroupNameFieldDefinitions Collection ........................................ 114

LineObject Object ........................................................................ 115

MapObject Object ........................................................................ 116

ObjectSummaryFieldDefinitions Collection .................................. 118

OlapGridObject Object ................................................................ 120

OleObject Object ......................................................................... 122

ii Crystal Reports Technical Reference Guide

Page Object .................................................................................. 125

PageEngine Object ........................................................................ 128

PageGenerator Object .................................................................. 132

Pages Collection ............................................................................ 140

ParameterFieldDefinition Object .................................................. 141

ParameterFieldDefinitions Collection ........................................... 150

ParameterValue Object ................................................................. 151

ParameterValues Collection .......................................................... 152

ParameterValueInfo Object .......................................................... 153

ParameterValueInfos Collection ................................................... 154

PrintingStatus Object .................................................................... 155

Report Object ............................................................................... 156

ReportAlert Object ....................................................................... 174

ReportAlerts Collection ................................................................. 175

ReportAlertInstance Object .......................................................... 177

ReportAlertInstances Collection ................................................... 178

ReportObjects Collection .............................................................. 179

RunningTotalFieldDefinition Object ............................................. 180

RunningTotalFieldDefinitions Collection ...................................... 185

Section Object .............................................................................. 187

Sections Collection ....................................................................... 202

SortField Object ............................................................................ 204

SortFields Collection ..................................................................... 204

SpecialVarFieldDefinition Object ................................................. 206

SQLExpressionFieldDefinition Object ........................................... 207

Crystal Reports Technical Reference Guide iii

SQLExpressionFieldDefinitions Collection .................................... 209

SubreportLink Object .................................................................... 211

SubreportLinks Collection ............................................................. 212

SubreportObject Object ............................................................... 214

SummaryFieldDefinition Object ................................................... 217

SummaryFieldDefinitions Collection ............................................. 220

TableLink Object ........................................................................... 222

TableLinks Collection .................................................................... 223

TextObject Object ........................................................................ 226

Examples ....................................................................................... 231

Enumerated Types ......................................................................... 262

Chapter 3: Programming the Crystal Report Viewers

Application Development with Crystal Report Viewers ................ 309

Crystal Report Viewer for ActiveX ................................................ 310

The Crystal Report Viewer Java Bean ............................................ 317

Chapter 4: Report Viewer Object Model

Report Viewer/ActiveX Object Model technical reference ........... 320

Enumerated Types—Report Viewer .............................................. 348

The Report Viewer/Java Bean technical reference ........................ 353

Chapter 5: Programming the Embeddable Crystal Reports Designer Control

Overview ...................................................................................... 362

Creating a Microsoft Visual Basic sample application with the Em-

beddable Designer ........................................................................ 362

iv Crystal Reports Technical Reference Guide

Creating a Microsoft Visual C++ sample application with the Em-

beddable Designer ........................................................................ 368

Designing reports in the Embeddable Designer ............................. 377

Chapter 6: Embeddable Crystal Reports Designer Control Object Model

Overview of the Embeddable Designer ......................................... 382

Application development with the Embeddable Designer ............. 382

Distributing the Embeddable Designer .......................................... 383

Properties and methods of the Embeddable Designer ................... 384

Chapter 7: Active Data

Active Data Drivers ..................................................................... 390

Crystal Data Object ...................................................................... 400

COM data provider ....................................................................... 403

Chapter 8: Crystal Data Source Object Models

Crystal Data Source Object Models .............................................. 410

Crystal Data Objects ..................................................................... 410

CrystalComObject ........................................................................ 410

Chapter 9: Creating User-Defined Functions in C

Overview of User-Defined Functions in C .................................... 418

Programming User-Defined Functions in C ................................... 418

Programming the UFL ................................................................... 422

Setting up a UFL project ............................................................... 424

Function definition ........................................................................ 425

Crystal Reports Technical Reference Guide v

Returning user-defined errors ....................................................... 431

Obtaining parameter values from the parameter block ................ 431

Picture function—a sample UFL function ..................................... 432

Module Definition (.def) file ......................................................... 434

UFJOB modules ............................................................................ 435

Implement InitJob and TermJob ................................................... 437

Special functions ........................................................................... 437

Chapter 10: Creating User-Defined Functions in Visual Basic

Overview of User-Defined Functions in Visual Basic .................... 440

Programming User-Defined Functions in Visual Basic .................. 440

Visual Basic and Crystal Reports ................................................... 443

Chapter 11: Creating User-Defined Functions in Delphi 3.0

Overview of User-Defined Functions in Delphi ............................ 450

Programming User-Defined Functions in Delphi .......................... 450

Delphi and Crystal Reports ........................................................... 454

Chapter 12: Deprecated and Retired API Reference

Retired Developer APIs ................................................................. 460

Retired P2smon.dll functions ........................................................ 461

Deprecated RDC Interfaces .......................................................... 464

Deprecated RDC Properties .......................................................... 468

Deprecated RDC Methods ............................................................ 469

Deprecated RDC Export Format Types ......................................... 474

vi Crystal Reports Technical Reference Guide

Crystal Reports Technical Reference Guide 1

2 Crystal Reports Technical Reference Guide

1 Welcome to Crystal Reports Development

Welcome to Crystal Reports

Development 1

Welcome! This section introduces you to developing with Crystal Reports, the world standard for desktop and web reporting, and provides you with an overview of the contents of this online help.

Click the appropriate link to jump to that section:

• About Crystal Reports

• About the online help

• Product registration

• Customer Handbook

• Crystal Care technical support

• Crystal Training

• Crystal Consulting

• Document conventions

Additional Resources

The Crystal Reports User’s Guide is available in PDF format on the install CD in the Documentation folder (UserGde.pdf). The contents of the Crystal Reports Online Help (crw.chm) includes everything from the printed manual, plus more.

Crystal Decisions Support web site

The Crystal Decisions Support web site, which serves as an extension of all Crystal Decisions products, is the place to go for product support, samples, educational documents, tutorials, tools, forums, and more:

http://support.crystaldecisions.com

Crystal Decisions Developers Zone

The Crystal Decisions Developers zone is the key place for the latest development news. Updated weekly, you will find this an invaluable resource on the latest features, issues, and tips and tricks.

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

Crystal Reports Technical Reference Guide 3

About Crystal Reports

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.

About the online help

The 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.

Click the appropriate link to jump to that section:

• Section contents

4 Crystal Reports Technical Reference Guide

Section contents

The following is a short description of each section in the online help.

Chapter 1: Welcome to Crystal Reports Development

Welcome! This section introduces you to developing with Crystal Reports, the world standard for desktop and web reporting, and provides you with an overview of the contents of this online help.

Chapter 2: 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.

Chapter 3: 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.

Chapter 4: 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.

1 Welcome to Crystal Reports Development

Chapter 5: 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.

Chapter 6: Embeddable Crystal Reports Designer Control Object Model

The Embeddable Crystal Reports Designer Control (Embeddable Designer) is a new addition to the Report Designer Component; 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.

Crystal Reports Technical Reference Guide 5

Product registration

Chapter 7: 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.

Chapter 8: 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.

Chapter 9: 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.

Chapter 10: 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.

Chapter 11: 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.

Chapter 12: 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.

Product registration

There are several ways you can register your product:

• Fill out the Product Registration form on the Crystal Decisions web site at:

http://www.crystaldecisions.com/register/

6 Crystal Reports Technical Reference Guide

• Print the Product Registration form and fax it to the registration fax number

closest to you. Crystal Decisions will then fax you a registration number that can be entered into the product the next time you use it.

Registration fax numbers

USA/Canada +1 (604) 681-5147 United Kingdom +44 (0) 20 8231 0601 Australia +6 2 9955 7682 Germany +49 (0) 69 9509 6182 Hong Kong +852 2893 2727 Singapore +65 777 8786

Registering the product ensures that you are kept up-to-date with product advancements.

Customer Handbook

For the latest details about product registration, maintenance, support, and services, visit our web site and download the Customer Handbook that corresponds to your region:

• North America:

http://www.crystaldecisions.com/about/loyalty/handbook.asp (English)

• Europe:

http://www.crystaldecisions.com/about/loyalty/handbook.asp (English) http://germany.crystaldecisions.com/about/loyalty/handbook.asp http://france.crystaldecisions.com/about/loyalty/handbook.asp (French)

If a Crystal Decisions Customer Handbook is not available for your region, please refer to the rest of this Welcome chapter, or contact your sales or support representative for complete details.

1 Welcome to Crystal Reports Development

(German)

Crystal Care technical support

To access Crystal technical support specialists, you must: register your software online at:

http://www.crystaldecisions.com/register/

To find out about the technical support programs available for Crystal Reports:

• Go to our support web site at:

http://support.crystaldecisions.com/crystalcare/

• Contact your regional office. For details, go to:

http://www.crystaldecisions.com/contact/offices.asp

Crystal Reports Technical Reference Guide 7

Crystal Training

Whether you’re a developer, information technology professional, or business user, we offer a wide range of Crystal Reports training courses designed to build or enhance your existing skills. Courses are available online, at certified training centers, or at your own site:

• For a complete list of training courses and special offers, visit:

http://www.crystaldecisions.com/training/

• Or contact your regional office. For details, go to:

http://www.crystaldecisions.com/offices/

Crystal Consulting

Our global team of certified consultants and consulting partners can guide you through a corporate-wide solution—including strategy, design, integration and deployment—for the fastest results, maximum performance, and increased productivity.

• To learn more, visit:

http://www.crystaldecisions.com/consulting/

• Or contact your regional office. For details, go to:

http://www.crystaldecisions.com/offices/

Document conventions

This online help uses the following conventions:

• Commands and buttons

For easy recognition within procedures, User Interface (UI) features appear in bold type. For example: On the File menu, click New.

• Keyboard shortcuts

Delete means the Delete key, or the Del key on your numeric keypad. Enter means the Enter, Return, or CR key, depending on which of these keys appears on your keyboard.

• Key combinations

CTRL+KEY, SHIFT+KEY, and ALT+KEY are examples of key combinations. Hold down the first key in the combination and, at the same time, press the second key in the combination (designated above as KEY). For example: CTRL+C means hold the Control key down and press the letter C on your keyboard (CTRL+C is the Windows Copy command).

• Key terms are italicized when first defined.

• Monospaced font indicates file paths and names, lines of code, and data that

you enter using your keyboard (for example: In the Formula Editor, type

Sales > 1000 Then crRed

8 Crystal Reports Technical Reference Guide

).

If

1 Welcome to Crystal Reports Development

• Monospaced, italicized font indicates variable data that you must replace with

data appropriate to your current settings, environment, or task. For example, in the following URL, you would replace

http://

webserver

/crystal/enterprise/

webserver:

Crystal Reports Technical Reference Guide 9

Document conventions

10 Crystal Reports Technical Reference Guide

Report Designer Component Object

Model 2

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

Crystal Reports Technical Reference Guide 11

• 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

12 Crystal Reports Technical Reference Guide

• SummaryFieldDefinitions Collection

• TableLink Object

• TableLinks Collection

• TextObject Object

• Examples

• Enumerated Types

2 Report Designer Component Object Model

Crystal Reports Technical Reference Guide 13

Overview of the Report Designer Object Model

14 Crystal Reports Technical Reference Guide

2 Report Designer Component 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” on page 381 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

Crystal Reports Technical Reference Guide 15

Objects and Collections

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.10). If the version number is not specified, CreateObject will create the object using the most recently installed version of

craxdrt.dll

16 Crystal Reports Technical Reference Guide

.

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.10. 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,

2 Report Designer Component Object Model

' 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)” on page 18

• “GetLicenseStatus Method (Application Object)” on page 18

• “GetVersion Method (Application Object)” on page 18

• “LogOffServer Method (Application Object)” on page 19

• “LogOnServer Method (Application Object)” on page 20

• “LogOnServerEx Method (Application Object)” on page 21

• “NewReport Method (Application Object)” on page 22

• “OpenReport Method (Application Object)” on page 22

• “SetMatchLogOnInfo Method (Application Object)” on page 23

Crystal Reports Technical Reference Guide 17

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

18 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

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

Table 1:

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

[pDatabaseName] Specifies the name for the database used to create the report. See Remarks

[pUserID] Specifies the User ID number necessary to log on to the server. See Remarks

[pPassword] Specifies the password necessary to log on to the server.

Crystal Reports Technical Reference Guide 19

ODBC, use the data source name.) This value is case-sensitive. See Remarks below.

below.

Application Object

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

Table 2:

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

[pDatabaseName] Specifies the name for the database used to create the report. See Remarks

20 Crystal Reports Technical Reference Guide

ODBC, use the data source name.) This value is case-sensitive. See Remarks below.

below.

2 Report Designer Component Object Model

Table 2:

Parameter Description

[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

Table 3:

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.

Crystal Reports Technical Reference Guide 21

Application Object

Table 3:

Parameter Description

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

[pPassword] Specifies the password necessary to log on to the server.

[pServerType] Specifies the database Server Type.

[pConnectionString] Specifies the connection string.

Remarks below.

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

22 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

Parameters

Table 4:

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

Table 5:

Parameter Description

bl Specifies whether the option is selected (TRUE).

Crystal Reports Technical Reference Guide 23

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

Ta b le 6:

Property Description

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 printtime formulas. Condition formulas cannot have shared variables.

CopiesToPrint Integer. Gets or sets the number of copies

DetailHeight Long. Gets the mailing label report detail

DetailWidth Long. Gets multiple column report detail

DiscardOtherGroupsBoolean. Gets or sets the discard other

EnableHierarchica lGroupSorting

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.

area height, in twips.

area width, in twips.

groups option.

Boolean. Gets or sets group hierarchically flag.

Read/ Write

Read / Wri te

Read only

Read / Wri te

Restriction in event handler

Can be written only when formatting idle.

None

Formatting idle.

GroupCondition “CRGroupCondition”. Gets or sets the

group condition.

24 Crystal Reports Technical Reference Guide

Read / Wri te

Can be written only when formatting idle.

Table 6:

2 Report Designer Component Object Model

Property Description

GroupConditionFi eld

GroupIndent Long. Gets or sets group indent, in twips. Read

GroupNumber Integer. If the area is a group area, this

HideForDrillDownBoolean. Gets or sets hide for drill down

HorizontalGap Long. Gets the horizontal gaps going

InstanceIDField A field definition object. Gets the instance

KeepGroupTogetherBoolean. Gets or sets the keep group

KeepTogether Boolean. Gets or sets the keep area

Object. Gets or sets the group condition field.

returns the group number. Otherwise, exception is thrown.

option.

across page in a multiple column report.

ID field. See Remarks.

together option.

Read/ Write

Read / Wri te

/ Wri te

Read only

Read / Wri te

Read only

Read / Wri te

Restriction in event handler

Can be written only when formatting idle.

Formatting idle.

None

Can be written only when formatting idle.

None

Formatting idle.

Can be written only when formatting idle.

Kind “CRAreaKind”. Gets which kind of area

(for example, Details, Report Header, Page Footer, etc.).

Name String. Gets or sets the area name. Read

NewPageAfter Boolean. Gets or sets the new page after

options.

NewPageBefore Boolean. Gets or sets the new page before

option.

Crystal Reports Technical Reference Guide 25

Read only

/ Wri te

Read / Wri te

None

Can be written only when formatting idle.

Area Object

Ta b le 6:

Property Description

NumberOfTopOr BottomNGroups

Parent “Report Object”. Gets reference to the

ParentIDField A field definition object. Gets the parent

PrintAtBottomOfP age

RepeatGroupHea der

ResetPageNumber After

Sections “Sections Collection”. Gets a Collection

SortDirection “CRSortDirection”. Gets or sets the group

Integer. Gets or sets the number of top or bottom groups.

parent object.

ID field. See Remarks.

Boolean. Gets or sets the print at bottom of page option.

Boolean. Gets or sets the repeating group header option.

Boolean. Gets or sets the reset page number after option.

of all the sections in the area.

sort direction.

Read/ Write

Read / Wri te

Read Only

Read only

Read / Wri te

Read Only

Read / Wri te

Restriction in event handler

Formatting idle.

None

Formatting idle.

Can be written only when formatting idle.

None

Can be written only when formatting idle.

SpecifiedGroups Gets or sets the specified groups. Read

/ Wri te

Suppress Boolean. Gets or sets the area visibility. Read

/ Wri te

TopOrBottomNGr oupSortOrder

TopOrBottomNSo rtField

26 Crystal Reports Technical Reference Guide

“CRTopOrBottomNGroupSortOrder”.

Gets or sets the top or bottom N group sort order.

“SummaryFieldDefinition Object”. Gets

or sets the top or bottom n sort field.

Read / Wri te

Can be written only when formatting idle.

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)” on page 27

• “SetParentIDField (Area Object)” on page 27

SetInstanceIDField Method (Area Object)

Use the SetInstanceIDField method to set an instance ID field.

Syntax

Sub SetInstanceIDField (InstanceIDField)

Parameter

2 Report Designer Component Object Model

Table 7:

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

Table 8:

Parameter Description

ParentIDField Specifies the parent ID field that you want to set.

Crystal Reports Technical Reference Guide 27

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

Table 9:

Property Description

Count Long. Gets the number of areas in the collection. Read only None

Item (index)

Parent “Report Object”. Gets reference to the parent object. Read only None

“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/ Write

Read only None

Restriction in event handler

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.

28 Crystal Reports Technical Reference Guide

BlobFieldObject Object Properties

Examples

How to format a blob field object

Table 10:

2 Report Designer Component Object Model

Property Description

BackColor OLE_COLOR. Gets or sets the object

background color.

BorderColor OLE_COLOR. Gets or sets the object

border color.

BottomCroppingLong. Gets or sets bottom cropping size,

in twips.

BottomLineStyle“CRLineStyle”. Gets or sets the bottom

line style.

CloseAtPageBr eak

ConditionForm ula

Boolean. Gets or sets the close border on page break.

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

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

CssClass String. Gets or sets the cascading style

sheet Class.

Field “DatabaseFieldDefinition Object”. Gets

the database field definition object containing information about the BLOB field.

Crystal Reports Technical Reference Guide 29

Read / Wri te

Read only

Can be written only when formatting idle.

None

BlobFieldObject Object

Table 10:

Property Description

HasDropShadowBoolean. Gets or sets the border drop

shadow option.

Height Long. Gets or sets the object height, in

twips.

KeepTogether Boolean. Gets or sets the keep object

together option.

Kind “CRObjectKind”. Gets CRObjectKind

which specifies the kind of object (for example, box, cross-tab, field, etc.).

Left Long. Gets or sets the object upper left

position, in twips.

LeftCropping Long. Gets or sets the left cropping size,

in twips.

LeftLineStyle “CRLineStyle”. Gets or sets the left line

style.

Read/ Write

Read / Wri te

Read only

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

None

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Name String. Gets or sets the object name. Read

/ Wri te

Parent “Section Object”. Gets reference to the

parent object.

RightCropping Long. Gets or sets the right cropping

size, in twips.

RightLineStyle “CRLineStyle”. Gets or sets the right line

style.

30 Crystal Reports Technical Reference Guide

Read only

Read / Wri te

Can be written only when formatting idle.

None

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Table 10:

2 Report Designer Component Object Model

Property Description

Suppress Boolean. Gets or sets the object visibility. Read

Top Long. Gets or sets the object upper top

position, in twips.

TopCropping Long. Gets or sets the top cropping size,

in twips.

TopLineStyle “CRLineStyle”. Gets or sets the top line

style.

Width Long. Gets or sets the object width, in

twips.

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.

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

/ Wri te

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

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.

Crystal Reports Technical Reference Guide 31

BoxObject Object

BoxObject Object Properties

Examples

How to format a box object

Ta b le 11 :

Property Description

Bottom Long. Gets or sets the object

lower bottom position, in twips.

BottomRightSection “Section Object”. Gets the

bottom right section.

CloseAtPageBreak Boolean. Gets or sets the close

border on page break option.

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 printtime formulas. Condition formulas cannot have shared variables.

CornerEllipseHeight Long. Gets or sets the corner

elipse height, in twips.

CornerEllipseWidth Long. Gets or sets the corner

elipse width, in twips.

Read/ Write

Read/ Wri te

Read only

Read/ Wri te

Restriction in event handler

Can be written only when formatting idle.

CssClass String. Gets or sets the

cascading style sheet Class.

ExtendToBottomOfS ection

Boolean. Gets or sets the extend to bottom of section

Read/ Wri te

Can be written only when formatting idle.

option.

FillColor OLE_COLOR. Gets or sets the

fill color.

32 Crystal Reports Technical Reference Guide

Read/ Wri te

Can be written only when formatting idle.

Ta b le 11 :

2 Report Designer Component Object Model

Property Description

HasDropShadow Boolean. Gets or sets the

border drop shadow option..

Kind “CRObjectKind”. Gets which

kind of object (for example, box, cross-tab, field, etc.).

Left Long. Gets or sets the upper

left position, in twips.

LineColor OLE_COLOR. Gets or sets the

line color.

LineStyle “CRLineStyle”. Gets or sets the

line style.

LineThickness Long. Gets or sets the line

thickness, in twips.

Name String. Gets or sets the object

name.

Parent “Section Object”. Gets

reference to the parent object.

Right Long. Gets or sets the object

lower right position, in twips.

Read/ Write

Read/ Wri te

Read only

Read/ Wri te

Read only

Read/ Wri te

Restriction in event handler

Can be written only when formatting idle.

None

Can be written only when formatting idle or active.

Can be written only when formatting idle.

None

Can be written only when formatting idle.

Suppress Boolean. Gets or sets the object

visibility.

Top Long. Gets or sets the object

upper top position, in twips.

Read/ Wri te

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 Crystal Decisions 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

Crystal Reports Technical Reference Guide 33

ConnectionProperty Object

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” on page 36.

ConnectionProperty Object Properties

Examples

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

Table 12:

Property Description

ChildProperties “ConnectionProperties Collection”. Gets the

child properties of this connection property in a hierarchal property structure.

Description String. Gets or sets the description of the

connection property.

LocalizedName String. Gets or sets the localized name of the

connection property.

Name String. Gets or sets the name of the connection

property.

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

Read only

Read/ Wri te

Restriction in event handler

None

34 Crystal Reports Technical Reference Guide

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.

Table 13:

2 Report Designer Component Object Model

Data source

ODBC (RDO) crdb_odbc.dll

Connection property name

Connection String

Database String. The name of the

Database Typ e

DSN String. The ODBC data sourec

FILEDSN String. Path to the File DSN. DSN, FILEDSN and

Connection property value description

String. The complete connection string containting the driver information. This can be obtained from content of a File DSN.

database.

String. The type of file. For example: ODBC (RDO)

- or OLE DB (ADO)

name.

Remarks

DSN, FILEDSN and Connection String are mutually exclusive

This property can be used together with the DSN, FILEDSN, and Connection String.

This is an optional property.

DSN, FILEDSN and Connection String are mutually exclusive.

Connection String are mutually exclusive

Password String. The password used to

connect to the data source.

Trus te d_ Co nn ection

Crystal Reports Technical Reference Guide 35

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.

ConnectionProperty Object

Table 13:

Data source

OLE DB (ADO) crdb_ado.dll

Connection property name

User ID String. The user name

Data Source String. The data source that

Database String. The name of the

Database Typ e

Integrated Security

Connection property value description

required to connect to the data source.

the OLE DB provider is connected to such as a file path and database name or a server name.

database.

String. The type of file. For example: ODBC (RDO)

- or OLE DB (ADO)

Boolean. Set to True if you want the connection to use NT Authentication.

Remarks

This property can be used together with the DSN, FILEDSN, and Connection String.

This property can be used together with the Provider and Microsoft Data Link File.

This is an optional property.

This property can be used together with the Provider and Microsoft Data Link File.

Microsoft Data Link File

Password String. The password used to

Provider The name of the OLEDB

36 Crystal Reports Technical Reference Guide

String. The file path to the Data Link.

connect to the data source.

provider. For example: Microsoft.Jet.OLEDB.4.0

-orSQLOLEDB

Provider and Microsoft Data Link File are mutually exclusive.

This property can be used together with the Provider and Microsoft Data Link File.

Provider and Microsoft Data Link File are mutually exclusive.

Table 13:

2 Report Designer Component Object Model

Data source

Access/Excel (DAO) crdb_dao.dll

Connection property name

User ID String. The user name

Database Name

Database Password

Database Typ e

Session Password

Connection property value description

required to connect to the data source.

String. The full file path to the databse.

String. The password used to connect to the data source.

String. The type of file. For example: ODBC (RDO)

- or OLE DB (ADO)

String. The password for a system DSN.

Remarks

This property can be used together with the Provider and Microsoft Data Link File.

This property is required for changing the location and name of the database.

This property is only required if the daabse has database level security.

This is an optional property.

You must provide System Database Path if Session UserID and Session Password are provided.

Session UserID

System Database Path

Crystal Reports Technical Reference Guide 37

String. The user name for a system DSN.

String. You must provide

You must provide System Database Path if Session UserID and Session Password are provided.

System Database Path if Session UserID and Session Password are provided.

ConnectionProperty Object

Table 13:

Data source

Oracle crdb_oracle.dll

Native connections to local databases. crdb_p2b*.dll

Connection property name

Database Typ e

Server String. The Service name.

Password String. The password used to

User ID String. The user name

Database Path String. The full file path to the

Connection property value description

String. The type of file. For example: ODBC (RDO)

- or OLE DB (ADO)

connect to the data source.

required to connect to the data source.

database.

Remarks

This is an optional property.

These include Act!, Btrieve, DB2, Dbase, FoxPro, Paradox and so on.

This property is required for changing the location and name of the database.

Database Typ e

Password String. The password used to

User ID String. The user name

38 Crystal Reports Technical Reference Guide

String. The type of file. For example: ODBC (RDO)

- or OLE DB (ADO)

connect to the data source.

required to connect to the data source.

This is an optional property.

Table 13:

2 Report Designer Component Object Model

Data source

Native connections to server data sources. crdb_p2s*.dll

Field Definitions Only crdb_fielddef.dll

Connection property name

Database String. The database name.

Database Typ e

Server String. The server name.

Password String. The password used to

User ID String. The user name

Connection property value description

String. The type of file. For example: ODBC (RDO)

- or OLE DB (ADO)

connect to the data source.

required to connect to the data source.

Remarks

These include Informix, DB2 Server, Lotus Domino, and so on.

This is an optional property.

Database Typ e

Field Definition File

File Systam Data crdb_FileSystem.d ll

Crystal Reports Technical Reference Guide 39

String. The type of file. For example: ODBC (RDO)

- or OLE DB (ADO)

String. The full file and path to the Field defintion file (*.ttx).

This is an optional property.

ConnectionProperties Collection

Table 13:

Data source

Connection property name

Database Typ e

File Mask String. A mask to filter the

Include Empty Directories

Max Number of Subdirectory Levels

Starting Directory

Connection property value description

String. The type of file. For example: ODBC (RDO)

- or OLE DB (ADO)

types of files returned. For example: *.exe

Boolean. Set to True to include empty directories.

Integer. The number of subdirectory levels to include.

String. The path to the starting directory.

Remarks

This is an optional property.

Set this value to -1 to include all subdirectories.

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” on page 36.

40 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

ConnectionProperties Collection Properties

Examples

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

Table 14:

Property Definition

Count Long. Gets the number of objects in the collection. Read

Item (indexAs Long)

NameIds Variant. Returns an array containing the name of each

“ConnectionProperty Object”. Gets an item from the

Collection specified by name.

connection property in the collection.

Read/ Write

only

Read only

ConnectionProperties Collection Methods

The following methods are discussed in this section:

• “Add Method (ConnectionProperties Collection)” on page 42

• “Delete Method (ConnectionProperties Collection)” on page 43

• “DeleteAll Method (ConnectionProperties Collection)” on page 44

Add Method (ConnectionProperties Collection)

Use the Add method to add a ConnectionProperty Object to the Collection as a name value pair.

Restriction in event handler

None

Crystal Reports Technical Reference Guide 41

ConnectionProperties Collection

Examples

How to change the data source

Syntax

Function Add (Name As String, Value)

Parameter Description

Name Specifies the name of the connection property that you want to

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.

Table 15:

add to the Collection.

Delete Method (ConnectionProperties Collection)

Use the Delete method to remove a ConnectionProperty Object from the Collection.

Examples

How to change the data source

Syntax

Sub Delete (index)

42 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

Parameter

Table 16:

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

How to change the data source

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.

Crystal Reports Technical Reference Guide 43

CrossTabGroup Object

CrossTabGroup Properties

Examples

How to add, delete and format groups in a crosstab

Table 17:

Property Description Read/Write Restriction in event handler

BackColor OLE_COLOR. Gets or sets the

Condition “CRGroupCondition”. Gets or

EnableSuppress Label

EnableSuppress Subtotal

Field A field definition object. Gets

Parent “CrossTabObject Object”. Gets

SortDirection “CRSortDirection”. Gets or

crosstab group background color.

sets the crosstab group condition.

Boolean. Gets or sets the crosstab group enable suppress label option.

Boolean. Gets or sets the crosstab group enable suppress subtotal option.

or sets the crosstab group’s field. See Remarks.

reference to the crosstab group parent object.

sets the crosstab group sort direction.

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.

Read/Write Idle

Read only None

Read/Write Idle

44 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

CrossTabGroups Collection

The CrossTabGroups Collection contains CrossTabGroup Objects associated with a report.

CrossTabGroups Collection Properties

Table 18:

Property Description Read/Write Restriction in event handler

Count Long. Gets the CrossTabGroup

count.

Item (index As Long)

Parent “CrossTabObject Object”. Gets

“CrossTabGroup Object”. Gets

an item from the Collection.

reference to the parent object.

Read only None

CrossTabGroups Collection Methods

The following methods are discussed in this section:

• “Add Method (CrossTabGroups Collection)” on page 46

• “Delete Method (CrossTabGroups Collection)” on page 47

Add Method (CrossTabGroups Collection)

Examples

How to add, delete and format groups in a crosstab

Use the Add method to add a field as a CrossTabGroup to the CrossTabGroups Collection.

Syntax

Function Add (Field) As CrossTabGroup

Crystal Reports Technical Reference Guide 45

CrossTabObject Object

Parameter

Returns

Returns a CrossTabGroup Object member of the Collection.

Delete Method (CrossTabGroups Collection)

Examples

How to add, delete and format groups in a crosstab

Use the Delete method to remove a CrossTabGroup Object from the Collection.

Syntax

Sub Delete (index As Long)

Table 19:

Parameter Description

Field Specifies the field that you want to add as a CrossTabGroup to

the Collection.

Parameter

Table 20:

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.

46 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

CrossTabObject Object Properties

Table 21:

Property Description Read/Write Restriction in event handler

BackColor OLE_COLOR. Gets or sets

the object background color.

BorderColor OLE_COLOR. Gets or sets

the object border color.

BottomLineStyle “CRLineStyle”. Gets or sets

the bottom line style.

CloseAtPageBreak Boolean. Gets or sets the

close border on page break option.

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 printtime fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables.

ColumnGrandTota lColor

OLE_COLOR. Gets or sets the column grand total color.

ColumnGroups “Remarks”. Gets the column

groups Collection.

Read/ Wri te

Read/

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Idle

Wri te

Read only None

CssClass String. Gets or sets the

cascading style sheet Class.

EnableKeepColum nsTogether

Boolean. Gets or sets the enable keep columns

Read/ Wri te

Can be written only when formatting idle.

Idle

together option.

EnableRepeatRow Labels

Boolean. Gets or sets the enable repeat row labels

Read/ Wri te

Idle

option.

Crystal Reports Technical Reference Guide 47

CrossTabObject Object

Table 21:

Property Description Read/Write Restriction in event handler

EnableShowCellM argins

EnableShowGrid Boolean. Gets or sets the

EnableSuppressCo lumnGrandTotals

EnableSuppressE mptyColumns

EnableSuppressE mptyRows

EnableSuppressRo wGrandTotals

HasDropShadow Boolean. Gets or sets the

Height Long. Gets the object height,

KeepTogether Boolean. Gets or sets the

Boolean. Gets or sets the enable show cell margins option.

enable show grid option.

Boolean. Gets or sets the enable suppress column grand totals option.

Boolean. Gets or sets the enable suppress empty columns option.

Boolean. Gets or sets the enable suppress empty rows option.

Boolean. Gets or sets the enable suppress row grand totals option.

border drop shadow option.

in twips.

keep object together option.

Read/ Wri te

Read only Can be written only when

Read/ Wri te

Idle

Can be written only when formatting idle or active.

formatting idle or active.

Can be written only when formatting idle or active.

Kind “CRObjectKind”. Gets which

kind of object (for example, box, cross-tab, field, etc.).

Left Long. Gets or sets the upper

left position, in twips.

LeftLineStyle “CRLineStyle”. Gets or sets

the left line style.

Name String. Gets or sets the object

name.

48 Crystal Reports Technical Reference Guide

Read only None

Read/ Wri te

Can be written only when formatting idle or active.

Can be written only when formatting idle.

2 Report Designer Component Object Model

Table 21:

Property Description Read/Write Restriction in event handler

Parent “Section Object”. Gets

reference to the parent object.

RightLineStyle “CRLineStyle”. Gets or sets

RowGrandTotalCo lor

RowGroups “Remarks”. Gets the row

SummaryFields “ObjectSummaryFieldDefini

SpecifiedGroups Gets or sets the specified

Suppress Boolean. Gets or sets the

Top Long. Gets or sets the object

TopLineStyle “CRLineStyle”. Gets or sets

Width Long. Gets the object width,

the right line style.

OLE_COLOR. Gets or sets the row grand total color.

groups Collection.

tions Collection”. Gets the

summary fields.

groups from a row or column in the crosstab.

object visibility option.

upper top position, in twips.

top line style.

in twips.

Read only None

Read/ Wri te

Read Only None

Read/ Wri te

Read Only Can be written only when

Can be written only when formatting idle or active.

Idle

Can be written only when formatting idle

Can be written only when formatting idle or active.

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” on

page 14.

Crystal Reports Technical Reference Guide 49

Database Object

Database Object Properties

Table 22:

Property Description

Links “TableLinks Collection”. Gets database

link collection.

Parent “Report Object”. Gets reference to the

parent object.

Ta bl es “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).

Database Object Methods

The following methods are discussed in this section:

• “AddADOCommand Method (Database Object)” on page 51

• “AddOLEDBSource Method (Database Object)” on page 52

• “LogOffServer Method (Database Object)” on page 53

• “LogOnServer Method (Database Object)” on page 54

• “LogOnServerEx Method (Application Object)” on page 21

• “SetDataSource Method (Database Object)” on page 56

• “Verify Method (Database Object)” on page 57

Read/ Write

Read only None

Restriction in event handler

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)

50 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

Parameters

Table 23:

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

Table 24:

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.

Crystal Reports Technical Reference Guide 51

Database Object

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

Table 25:

Parameter Description

pDllName Specifies the name of the DLL for the server or password protected non-

pServerName Specifies the log on name for the server used to create the report. For ODBC,

[pDatabaseName] Specifies the name for the database used to create the report. See Remarks

[pUserID] Specifies the User ID number necessary to log on to the server. See Remarks

[pPassword] Specifies the password necessary to log on to the server.

52 Crystal Reports Technical Reference Guide

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.

use the data source name. This value is case-sensitive. See Remarks below.

below.

2 Report Designer Component Object Model

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

Table 26:

Parameter Description

pDllName Specifies the name of the DLL for the server or password protected non-

pServerName Specifies the log on name for the server used to create the report. For

Crystal Reports Technical Reference Guide 53

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.

ODBC, use the data source name. This value is case-sensitive. See Remarks below.

Database Object

Table 26:

Parameter Description

[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

[pPassword] Specifies the password necessary to log on to the server.

below.

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

Table 27:

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.

54 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

Table 27:

Parameter Description

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

[pPassword] Specifies the password necessary to log on to the server.

[pServerType] Specifies the database Server Type.

[pConnectionString] Specifies the connection string.

Remarks below.

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])

Crystal Reports Technical Reference Guide 55

Database Object

Parameters

Table 28:

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

56 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

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

Table 29:

Property Definition

DatabaseFieldDispl ayName

DatabaseFieldName String. Gets the name of the field in

Kind “CRFieldKind”. Gets which kind of

Name String. Gets the unique Crystal

NextValue Variant. Gets the field next value. Read

NumberOfBytes Integer. Gets the number of bytes

Parent “Report Object”. Gets reference to the

String. Gets the display name for the field in the database.

the database (for example, Product ID).

field (for example, database, summary, formula, etc.).

formula form name of the field within the report as {table.FIELD} (for example, {product.PRODUCT ID}).

required to store the field data in memory.

parent object.

Read/ Write

Read Only

Read only

only

Read only

Restriction in event handler

None

Ca n be read onl y wh en top-level Report object is formatting active.

None

Crystal Reports Technical Reference Guide 57

DatabaseFieldDefinitions Collection

Table 29:

Property Definition

PreviousValue Variant. Gets the field previous value. Read

TableAliasName String. Gets the alias for the table

containing the field.

Value Variant. Gets the field current value. Read

Va lu eTy pe “CRFieldValueType”. Gets which

type of value is found in the field.

Read/ Write

only

Read only

only

Read only

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

Restriction in event handler

Ca n be read onl y wh en top-level Report object is formatting active.

None

Ca n be read onl y wh en top-level Report object is formatting active.

None

Table 30:

Property Description

Count Long. Gets the number of “DatabaseFieldDefinition

Item (index As Long)

Parent “DatabaseTable Object”. Reference to the parent

58 Crystal Reports Technical Reference Guide

Object”, in the collection.

“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.

object.

Read/ Write

Read only

Restriction in event handler

None

2 Report Designer Component Object Model

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)” on page 60

GetItemByName Method (DatabaseFieldDefinitions Collection)

Use the GetItemByName method to retrieve a DatabaseFieldDefinition object by name.

Syntax

Sub GetItemByName(name As String, databaseFieldDefinition)

Parameters

Table 31:

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.

Crystal Reports Technical Reference Guide 59

DatabaseTable Object

DatabaseTable Object Properties

Examples

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

Table 32:

Property Description

ConnectBufferSt ring

ConnectionProp erties

DatabaseType “CRDatabaseType”. Gets the database

DescriptiveNameString. Gets the table descriptive name. Read

DllName String. Gets the table driver DLL name. Read

Fields “DatabaseFieldDefinitions Collection

Location String. Gets or sets the location of the

Name String. Gets or sets the alias name for the

Parent “Database Object”. Reference to the

String. Gets the table connect buffer string.

“ConnectionProperties Collection”. Gets

the collection of connection properties from the table.

table type

Properties”. Gets the collection of

database fields in the table.

database table.

database table used in the report.

parent object.

Read/ Write

Read only

only

Read only

Read/ Wri te

Read only

Restriction in event handler

None

None.

None

Can be written only when formatting idle.

None

DatabaseTable Object Methods

The following methods are discussed in this section:

• “CheckDifferences Method (DatabaseTable Object)” on page 62

60 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

• “SetDataSource Method (DatabaseTable Object)” on page 62

• “SetTableLocation Method (DatabaseTable Object)” on page 63

• “TestConnectivity Method (DatabaseTable Object)” on page 64

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

Table 33:

Parameter Description

pDifferences “CRTableDifferences”. Bitwise constants specify the table

[reserved] Reserved. Do not use.

difference(s) (XOR’d), if any.

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])

Crystal Reports Technical Reference Guide 61

DatabaseTable Object

Parameters

Table 34:

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

How to connect to a Microsoft Access database How to connect to a secured Microsoft Access database

Syntax

Sub SetTableLocation (pLocation As String, pSubLocation As String,

pConnectBufferSting As String)

62 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

Parameters

Table 35:

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.

Crystal Reports Technical Reference Guide 63

DatabaseTables Collection

DatabaseTables Collection Properties

Table 36:

Property Description

Count Long. Gets the number of database objects in the

Item (indexAs Long)

Parent “Database Object”. Reference to the parent object. Read

collection.

“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/ Write

Read only

only

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)” on page 65

• “AddStoredProcedure Method (DatabaseTables Collection)” on page 66

• “Delete Method (DatabaseTables Collection)” on page 68

Restriction in event handler

None

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])

64 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

Parameters

Table 37:

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

[pServerName] Specifies the database Server Name.

[pServerType] Specifies the database Server Type.

[pDatabaseName] Specifies the database (file path and name.ext) containing

[pUserID] Specifies the User’s ID.

[pPassword] Specifies the User’s Password.

table that you want to add.

the table that you want to add.

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

Crystal Reports Technical Reference Guide 65

DatabaseTables Collection

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

Table 38:

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

[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

[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

[pUserID] Specifies the User’s ID.

[pPassword] Specifies the User’s Password.

[ParamValuesInfos]ParameterValueInfos Collection. Specifies the initial values for the stored

report.

to add.

you want to add.

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

66 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

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

Table 39:

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

Ta b le 40 :

Property Description

ApplicationFileNameString. Gets or sets the destination

application file name.

CharFieldDelimiterString. Gets or sets the character used to

separate fields in character separated text formats. This character delimits every field in the file.

Read/ Write

Read / Wri te

Restriction in event handler

Set before exporting report to an application destination.

None

Crystal Reports Technical Reference Guide 67

ExportOptions Object

Ta b le 40 :

Property Description

CharStringDelimiterString. Gets or sets the character used to

separate strings in character separated text formats. This character delimits only string fields (numeric, date fields, etc., have no delimiter).

DestinationDLLNameString. 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.

DestinationType “CRExportDestinationType”. Gets or sets

the export destination type.

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.

ExcelAreaGroupN umber

ExcelAreaType “CRAreaKind”. Gets or sets the base area

Integer. Gets or sets the base area group number if the area type is group area when exporting to Excel.

type if not using constant column width when exporting to Excel.

Read/ Write

Read / Wri te

Read only

Read / Wri te

Restriction in event handler

None

ExcelConstantColu mnWidth

ExcelConvertDate To St ri ng

ExcelExportAllPagesBoolean. Gets or sets export to Excel with

ExcelFirstPageNu mber

68 Crystal Reports Technical Reference Guide

Double. Gets or sets the column width when exporting to Excel.

Boolean. Gets or sets export to Excel has converting date values to strings option.

all pages.

Long. Gets or sets export to Excel for first page number.

Read / Wri te

None

Ta b le 40 :

2 Report Designer Component Object Model

Property Description

ExcelLastPageNu mber

ExcelPageBreaks Boolean. Gets or sets export to Excel has

ExcelTabHasColu mnHeadings

ExcelUseConstant ColumnWidth

ExcelUseTabularFo rmat

ExcelUseWorkshee tFunctions

ExchangeDestinati onType

Long. Gets or sets export to Excel for last page number.

page break option.

Boolean. Gets or sets exporting to Excel has column headings option.

Boolean. Gets or sets export to Excel to use constant column width.

Boolean. Gets or sets exporting to Excel to use tabular format.

Boolean. Gets or sets export to Excel to use worksheet functions to represent subtotal fields in the report.

“CRExchangeDestinationType”. Gets or

sets the Exchange destination type for reports exported to Exchange folders.

Read/ Write

Read / Wri te

Restriction in event handler

None

ExchangeFolderPathString. Gets or sets the path of the

Exchange folder for reports exported to Exchange (for example, “MyFolders@Inbox”).

ExchangePassword String. Sets Exchange password. Write

ExchangeProfile String. Gets or sets a user profile for

accessing an Exchange folder for reports exported to Exchange.

ExchangePathHas ColumnHeadings

Crystal Reports Technical Reference Guide 69

Boolean. Gets or sets the column heading option when exporting to Exchange.

Read / Wri te

only

Read / Wri te

None

ExportOptions Object

Ta b le 40 :

Property Description

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.

FormatType “CRExportFormatType”. Gets or sets the

HTMLEnableSeper atedPages

HTMLFileName String. Gets or sets the HTML file name

HTMLHasPageNa vigator

LotusDominoCom ments

LotusDominoData baseName

format type for the exported report (for example, text, Excel, etc.).

Boolean. Gets or sets the option to create seperated pages when exporting to HTML format.

for reports exported to HTML format.

Boolean. Gets or sets the option to display a page navigator on each page of a report exported to HTML format.

String. Gets or sets the destination Lotus Domino comments.

String. Gets or sets the destination Lotus Domino database name.

Read/ Write

Read only

Read / Wri te

Restriction in event handler

None

LotusNotesFormN ame

MailBccList String. Gets or sets a Blind Carbon Copy

MailCcList String. Gets or sets a Carbon Copy (CC)

MailMessage String. Gets or sets the e-mail message

70 Crystal Reports Technical Reference Guide

String. Gets or sets the destination Lotus Domino form name.

(BCC) list for reports e-mailed to a VIM email account.

list for reports e-mailed.

included with e-mailed reports.

Read / Wri te

None

Ta b le 40 :

2 Report Designer Component Object Model

Property Description

MailSubject String. Gets or sets the e-mail subject

heading for reports being e-mailed.

MailToList String. Gets or sets the To list for reports

being e-mailed.

MailUserName String. Gets or sets mail user name. Read

NumberOfLinesPe rPage

ODBCDataSource Name

ODBCDataSourceP assword

ODBCDataSource UserID

Integer. Gets or sets the number of lines to appear per page option for reports exported to a paginated text format.

String. Gets or sets the ODBC data source for reports exported to ODBC.

String. Sets the ODBC data source password.

String. Gets or sets the user name used to access an ODBC data source for reports exported to ODBC.

Read/ Write

Read / Wri te

/ Wri te

Read / Wri te

Wri te only

Read / Wri te

Restriction in event handler

None

ODBCExportTable Name

Parent “Report Object”. Reference to the parent

PDFExportAllPagesBoolean. Gets or sets whether or not to

Crystal Reports Technical Reference Guide 71

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.

object.

export all pages of the report to Portable Document Format(PDF). PDFExportAllPages must be set to false when setting PDFFirstPageNumber and PDFLastPageNumber.

Read / Wri te

Read only

Read / Wri te

None

ExportOptions Object

Ta b le 40 :

Property Description

PDFFirstPageNum ber

PDFLastPageNum ber

RTFExportAllPagesBoolean. Gets or sets whether or not to

RTFFirstPageNum ber

RTFFLastPageNu mber

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.

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.

export all pages of the report to Rich Text Format(RTF). RTFExportAllPages must be set to false when setting RTFFirstPageNumber and RTFLastPageNumber.

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.

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

Read / Wri te

Restriction in event handler

None

UseDefaultCharact ersPerInch

UserDefinedChara ctersPerInch

UseReportDateFor mat

72 Crystal Reports Technical Reference Guide

Boolean. Gets or sets use default characters per inch option.

Long. Gets or sets user defined characters per inch.

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 / Wri te

None

Ta b le 40 :

2 Report Designer Component Object Model

Property Description

UseReportNumber Format

XMLAllowMultipl eFiles

XMLFileName String. Gets or sets the file name if the

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.

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

report is exported to a disk.

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).

Read/ Write

Read / Wri te

Restriction in event handler

None

ExportOptions Object Methods

The following methods are discussed in this section:

• “PromptForExportOptions Method (ExportOptions Object)” on page 74

• “Reset Method (ExportOptions Object)” on page 75

PromptForExportOptions Method (ExportOptions Object)

The PromptForExportOptions method prompts the user for export information using default Crystal Report Engine dialog boxes.

Crystal Reports Technical Reference Guide 73

FieldDefinitions Collection

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

Table 41:

Property Description

Count Long. Gets the collection count. Read

Item (index As Long)

Parent “Report Object”. Reference to the parent object. Read

A field definition object. Gets the collection item. See Remarks.

Read/ Write

only

Read only

only

Restriction in event handler

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:

74 Crystal Reports Technical Reference Guide

2 Report Designer Component Object Model

• “Add Method (FieldDefinitions Collection)” on page 76

• “Delete Method (FieldDefinitions Collection)” on page 76

Add Method (FieldDefinitions Collection)

Use the Add method to add the specified Field to the FieldDefinitions Collection.

Syntax

Sub Add (Field)

Parameter

Table 42:

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

Table 43:

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

Crystal Reports Technical Reference Guide 75

FieldElement Object

FieldElement Object is obtained from the Item property of the “FieldElements

Collection” on page 87.

FieldElement Object Properties

Table 44:

Read

Property Description

AmPmType “CRAMPMType”. Gets or sets the

AM/PM type option.

AmString String. Gets or sets the AM string. Read

BooleanOutputType“CRBooleanOutputType”. Gets or sets

the Boolean output type.

CharacterSpacing Long. Gets or sets the character

spacing. OLE_COLOR. Gets or sets the object background color.

Color OLE_COLOR. Gets or sets the font

color.

ConditionFormulaString. 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.

/ Write

Read / Wri te

/ Wri te

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

CurrencyPosition Ty pe

CurrencySymbol String. Gets or sets the currency

76 Crystal Reports Technical Reference Guide

“CRCurrencyPositionType”. Gets or

sets the currency position type.

symbol.

Read / Wri te

Can be written only when formatting idle or active.

Table 44:

2 Report Designer Component Object Model

Property Description

CurrencySymbol Ty pe

DateCalendarType“CRDateCalendarType”. Gets or sets

DateEraType “CRDateEraType”. Gets or sets the

DateFirstSeparatorString. Gets or sets the date first

DateOrder “CRDateOrder”. Gets or sets the date

DatePrefixSepara tor

DateSecondSepar ator

“CRCurrencySymbolType”. Gets or

sets the currency symbol type.

the date calendar type.

date era type.

separator.

order.

String. Gets or sets the date prefix separator.

String. Gets or sets the date second separator.

Read / Write

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

DateSuffixSepara tor

DateWindowsDef aultType

DayType “CRDayType”. Gets or sets the day

DecimalPlaces Integer. Gets or sets the number

Crystal Reports Technical Reference Guide 77

String. Gets or sets the date suffix separator

“CRDateTimeFieldFormatConditionFo rmulaType”. Gets or sets the date

windows default type.

type.

decimal places.

Read / Wri te

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

FieldElement Object

Table 44:

Read

Property Description

DecimalSymbol String. Gets or sets the decimal symbol. Read

DisplayReverseSignBoolean. Gets or sets the reverse sign

FieldDefinition A field definition object. Gets the field

FirstLineIndent Long. Gets or sets the first line indent. Read

Font IFontDisp. Gets or sets the standard

HourMinuteSepa rator

HourType “CRHourType”. Gets or sets the hour

option.

definition. See Remarks.

OLE font.

String. Gets or sets the hour minute separator.

type.

/ Write

/ Wri te

Read / Wri te

Read Only

/ Wri te

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

None

Can be written only when formatting idle.

Can be written only when formatting idle or active.

LeadingDayPosition“CRLeadingDayPosition”. Gets or sets

the leading day position option.

LeadingDaySepa rator

LeadingDayType “CRLeadingDayType”. Gets or sets the

LeftIndent Long. Gets or sets the left indent, in

78 Crystal Reports Technical Reference Guide

String. Gets or sets the leading day separator.

leading day type.

twips.

Read / Wri te

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Table 44:

2 Report Designer Component Object Model

Read

Property Description

LineSpacing Double. Gets the line spacing. Read

LineSpacingType “CRLineSpacingType”. Gets the line

spacing type.

MaxNumberOfLi nes

MinuteSecondSe parator

MinuteType “CRMinuteType”. Gets or sets the

MonthType “CRMonthType”. Gets or sets month

NegativeType “CRNegativeType”. Gets or sets

Integer. Gets or sets the maximum number of line for a string memo field.

String. Gets or sets minute second separator.

minute type.

type.

number negative type.

/ Write

Only

Read Only

Read / Wri te

Restriction in event handler

None

Can be written only when formatting idle or active.

Parent “TextObject Object”. Reference to the

parent object.

PmString String. Gets or sets the PM string. Read

RightIndent Long. Gets or sets the right indent, in

twips.

RoundingType “CRRoundingType”. Gets or sets the

number rounding type.

Crystal Reports Technical Reference Guide 79

Read only

/ Wri te

Read / Wri te

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

FieldElement Object

Table 44:

Property Description

SecondType “CRSecondType”. Gets or sets the

Suppress Boolean. Gets or sets the object

SuppressIfDuplic ated

SuppressIfZero Boolean. Gets or sets the suppress if

TextFormat “CRTextFormat”. Gets or sets the text

ThousandsSepara tors

ThousandSymbol String. Gets or sets the thousand

seconds type.

visibility.

Boolean. Gets or sets the suppress if duplicate option.

zero option.

format option for string memo fields.

Boolean. Gets or sets the enable thousands separators option.

separator symbol.

Read / Write

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Tim eBase “CRTimeBase”. Gets or sets the time

UseLeadingZero Boolean. Gets or sets the number uses

UseOneSymbolP erPage

UseSystemDefaultsBoolean. Gets or sets the use system

80 Crystal Reports Technical Reference Guide

base.

leading zero option.

Boolean. Gets or sets the use one symbol per page option.

defaults formatting option.

Read / Wri te

Can be written only when formatting idle or active.

Table 44:

2 Report Designer Component Object Model

Property Description

Ye ar Typ e “CRYearType”. Gets or sets the year

type.

ZeroValueString String. Gets or sets the zero value

string for number field format.

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)” on page 87

SetLineSpacing Method (FieldElement Object)

Use the SetLineSpacing method to get and set the line spacing and line spacing type.

Read / Write

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Syntax

Sub SetLineSpacing (LineSpacing As Double,

LineSpacingType As CRLineSpacingType)

Parameters

Table 45:

Parameter Description

LineSpacing Specifies the line spacing.

LineSpacingType Specifies the line spacing type. Use one of “CRLineSpacingType”.

Crystal Reports Technical Reference Guide 81

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

Table 46:

Property Definition

Count Long. Gets the number of objects in the collection. Read

Item (indexAs Long)

Parent “TextObject Object”. Gets reference to the parent

“FieldElement Object”. Gets an item from the

Collection specified by the parameter index.

object.

Read/ Write

only

Read only

FieldElements Collection Methods

The following methods are discussed in this section:

• “Add Method (FieldElements Collection)” on page 88

• “Delete Method (FieldElements Collection)” on page 88

Add Method (FieldElements Collection)

The Add method is used to add a FieldElement object to the Collection.

Syntax

Function Add (position As Long, Field)

Restriction in event handler

None

Table 47:

Parameter Description

position Specifies the index where you would like to add the

Field Specifies the FieldElement that you want to add to the Collection.

82 Crystal Reports Technical Reference Guide

FieldElement 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.

2 Report Designer Component Object Model

Table 48:

FieldMappingData Object Properties

Table 49:

Property Description Read/Write

FieldName String. Gets or sets the field name. Read/Write None

MappingToFie ldIndex

TableName String. Gets or sets field’s table name. Read/Write None

Va lu eTy pe “CRFieldValueType”. Gets the value type

Crystal Reports Technical Reference Guide 83

Integer. Gets or sets the index of the mapping to field index in the field list of the new database.

that is in the field.

Read/Write None

Read only None

Restriction in event handler

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” on page 179, (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

Table 50:

Property Description

AmPmType “CRAMPMType”. Gets or sets the

AM/PM type option.

AmString String. Gets or sets the AM string. Read

BackColor OLE_COLOR. Gets or sets the object

background color.

BooleanOutputType“CRBooleanFieldFormatConditionFor

mulaType”. Gets or sets the Boolean

output type.

BorderColor OLE_COLOR. Gets or sets the object

border color.

BottomLineStyle “CRLineStyle”. Gets or sets bottom

line style.

CanGrow Boolean. Gets or sets can the grow

option.

Read/ Write

Read / Wri te

/ Wri te

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

CharacterSpacing Long. Gets or sets the character

spacing.

84 Crystal Reports Technical Reference Guide

Read / Wri te

Can be written only when formatting idle.

Table 50:

2 Report Designer Component Object Model

Property Description

CloseAtPageBreakBoolean. Gets or sets the close border

on page break option.

ConditionFormulaString. 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.

CssClass String. Gets or sets the cascading style

sheet Class.

CurrencyPosition Ty pe

CurrencySymbol String. Gets or sets the currency

CurrencySymbol Ty pe

“CRCurrencyPositionType”. Gets or

sets the currency position type.

symbol.

“CRCurrencySymbolType”. Gets or

sets the currency symbol type.

Read/ Write

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

DateCalendarType“CRDateCalendarType”. Gets or sets

the date calendar type.

DateEraType “CRDateEraType”. Gets or sets the

date era type.

DateFirstSeparatorString. Gets or sets the date first

separator.

DateOrder “CRDateOrder”. Gets or sets the date

order.

Crystal Reports Technical Reference Guide 85

Read / Wri te

Can be written only when formatting idle.

Can be written only when formatting idle or active.

FieldObject Object

Table 50:

Property Description

DatePrefixSeparatorString. Gets or sets the date prefix

separator.

DateSecondSepar ator

DateSuffixSeparatorString. Gets or sets the date suffix

DateWindowsDef aultType

DayType “CRDayType”. Gets or sets the day

DecimalPlaces Integer. Gets or sets the number

DecimalSymbol String. Gets or sets the decimal

String. Gets or sets the date second separator.

separator

“CRDateTimeFieldFormatConditionF ormulaType”. Gets or sets the date

windows default type.

type.

decimal places.

symbol.

Read/ Write

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

DisplayReverseSignBoolean. Gets or sets the reverse sign

option.

EnableTightHoriz ontal

Field Object. Gets the field definition object

FirstLineIndent Long. Gets or sets the first line indent. Read

86 Crystal Reports Technical Reference Guide

Boolean. Gets or sets the tight horizontal option.

(for example, ParameterFieldDefinition Object).

Read / Wri te

Read only

/ Wri te

Can be written only when formatting idle or active.

None

Can be written only when formatting idle.

Table 50:

2 Report Designer Component Object Model

Property Description

Font IFontDisp. Gets or sets the standard

OLE font.

HasDropShadow Boolean. Gets or sets the border drop

shadow option.

Height Long. Gets or sets object height, in

twips.

HorAlignment “CRAlignment”. Gets or sets the

horizontal alignment.

HourMinuteSepa rator

HourType “CRHourType”. Gets or sets the hour

KeepTogether Boolean. Gets or sets the keep object

String. Gets or sets the hour minute separator.

type.

together option.

Read/ Write

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Kind “CRObjectKind”. Gets which kind of

object (for example, box, cross-tab, field.)

LeadingDayPosition“CRLeadingDayPosition”. Gets or sets

the leading day position option.

LeadingDaySepar ator

LeadingDayType “CRLeadingDayType”. Gets or sets

Crystal Reports Technical Reference Guide 87

String. Gets or sets the leading day separator.

the leading day type.

Read only

Read / Wri te

None

Can be written only when formatting idle.

Can be written only when formatting idle or active.

FieldObject Object

Table 50:

Property Description

Left Long. Gets or sets the object upper left

position, in twips.

LeftIndent Long. Gets or sets the left indent, in

twips.

LeftLineStyle “CRLineStyle”. Gets or sets the left

line style.

LineSpacing Double. Gets the line spacing. Read

LineSpacingType “CRLineSpacingType”. Gets the line

spacing type.

MaxNumberOfLi nes

MinuteSecondSep arator

MinuteType “CRMinuteType”. Gets or sets the

Integer. Gets or sets the maximum number of line for a string memo field.

String. Gets or sets minute second separator.

minute type.

Read/ Write

Read / Wri te

Only

Read Only

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

None

Can be written only when formatting idle or active.

MonthType “CRMonthType”. Gets or sets month

type.

Name String. Gets or sets the object name. Read

NegativeType “CRNegativeType”. Gets or sets

number negative type.

NextValue Variant. Gets the field next value. Read

88 Crystal Reports Technical Reference Guide

Read / Wri te

/ Wri te

Read / Wri te

only

Can be written only when formatting idle or active.

Table 50:

2 Report Designer Component Object Model

Property Description

Parent “Section Object”. Reference to the

parent object.

PmString String. Gets or sets the PM string. Read

PreviousValue Variant. Gets the field previous value. Read

RightIndent Long. Gets or sets the right indent, in

twips.

RightLineStyle “CRLineStyle”. Gets or sets the right

line style.

RoundingType “CRRoundingType”. Gets or sets the

number rounding type.

SecondType “CRSecondType”. Gets or sets the

seconds type.

Read/ Write

Read only

/ Wri te

only

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Suppress Boolean. Gets or sets the object

visibility.

SuppressIfDuplic ated

SuppressIfZero Boolean. Gets or sets the suppress if

TextColor OLE_COLOR. Gets or sets the object

Crystal Reports Technical Reference Guide 89

Boolean. Gets or sets the suppress if duplicate option.

zero option.

text color.

Read / Wri te

Can be written only when formatting idle or active.

FieldObject Object

Table 50:

Property Description

TextFormat “CRTextFormat”. Gets or sets the text

format option for string memo fields.

TextRotationAngle“CRRotationAngle”. Gets or sets the

text rotation angle.

ThousandsSepara tors

ThousandSymbol String. Gets or sets the thousand

Tim eBase “CRTimeBase”. Gets or sets the time

Top Long. Gets or sets the object upper top

TopLineStyle “CRLineStyle”. Gets or sets the top

Boolean. Gets or sets the enable thousands separators option.

separator symbol.

base.

position, in twips.

line style.

Read/ Write

Read / Wri te

Restriction in event handler

Can be written only when formatting idle.

Can be written only when formatting idle or active.

UseLeadingZero Boolean. Gets or sets the number uses

leading zero option.

UseOneSymbolPe rPage

UseSystemDefaultsBoolean. Gets or sets the use system

Value Variant. Gets the field current value. Read

90 Crystal Reports Technical Reference Guide

Boolean. Gets or sets the use one symbol per page option.

defaults formatting option.

Read / Wri te

Only

Can be written only when formatting idle or active.

Table 50:

2 Report Designer Component Object Model

Property Description

Width Long. Gets or sets the object width, in

twips.

Ye ar Typ e “CRYearType”. Gets or sets the year

type.

ZeroValueString String. Gets or sets the zero value

string for number field format.

FieldObject Object Methods

The following methods are discussed in this section:

• “SetLineSpacing Method (FieldObject Object)” on page 97

• “SetUnboundFieldSource Method (FieldObject Object)” on page 97

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)

Read/ Write

Read / Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Parameters

Ta b le 51 :

Parameter Description

LineSpacing Specifies the line spacing.

LineSpacingType Specifies the line spacing type. Use one of “CRLineSpacingType”.

Crystal Reports Technical Reference Guide 91

FormattingInfo Object

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

Table 52:

pUnboundFieldSourceBSTR 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

Table 53:

Property Description

IsEndOfGroup Boolean. Gets whether the current formatting

section is the end of a group.

IsRepeatedGroup Header

Boolean. Gets whether the current formatting section is a repeated group header.

Read/ Write

Read only

Restriction in event handler

None

IsStartOfGroup Boolean. Gets whether the current formatting

section is the start of a group.

92 Crystal Reports Technical Reference Guide

Read only

None

Business objects CRYSTAL REPORTS 10 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

About Crystal Reports

About the online help

Section contents

Product registration

Customer Handbook

Crystal Care technical support

Crystal Training

Crystal Consulting

Document conventions

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

Application Object Methods

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)

Area Object

Area Object Properties

Area Object Methods

SetInstanceIDField Method (Area Object)

SetParentIDField (Area Object)

Areas Collection

Areas Collection Properties

BlobFieldObject Object

BlobFieldObject Object Properties

BoxObject Object

BoxObject Object Properties

ConnectionProperty Object

ConnectionProperty Object Properties

Common Connection Properties

ConnectionProperties Collection

ConnectionProperties Collection Properties

ConnectionProperties Collection Methods

Add Method (ConnectionProperties Collection)

Delete Method (ConnectionProperties Collection)

DeleteAll Method (ConnectionProperties Collection)

CrossTabGroup Object

CrossTabGroup Properties

CrossTabGroups Collection

CrossTabGroups Collection Properties

CrossTabGroups Collection Methods

Add Method (CrossTabGroups Collection)

CrossTabObject Object

Delete Method (CrossTabGroups Collection)

CrossTabObject Object Properties

Database Object

Database Object Properties

Database Object Methods

AddADOCommand Method (Database Object)

AddOLEDBSource Method (Database Object)

LogOffServer Method (Database Object)

LogOnServer Method (Database Object)

LogOnServerEx Method (Database Object)

SetDataSource Method (Database Object)

Verify Method (Database Object)

DatabaseFieldDefinition Object

DatabaseFieldDefinition Object Properties

DatabaseFieldDefinitions Collection

DatabaseFieldDefinitions Collection Properties

DatabaseFieldDefinitions Collection Methods

GetItemByName Method (DatabaseFieldDefinitions Collection)

DatabaseTable Object

DatabaseTable Object Properties

DatabaseTable Object Methods

CheckDifferences Method (DatabaseTable Object)

SetDataSource Method (DatabaseTable Object)