Crystal Reports

Connecting the Report Designer Component to a Data Source

Overview
The Crystal Reports Report Designer Component (RDC) has a number of
properties and methods available at runtime to connect a report to its data
source. This document provides an in depth look at each of these properties,
methods and their arguments. Developers can expect a better understanding of
how to connect Crystal Reports to their data sources at runtime.

Contents
INTRODUCTION ............................................................................................2
ACTIVE DATA SOURCES ..............................................................................2
SetDataSource and SetTablePrivateData ................................................... 2
Data Environments...................................................................................... 4
AddADOCommand and AddOLEDBSource................................................ 5
PERSISTENT DATA SOURCES .......................................................................7
SetLogonInfo ............................................................................................... 7
Location Property ....................................................................................... 9
SetSessionInfo Method .............................................................................. 10
LogonServer and LogonServerEx.............................................................. 10
CONTACTING CRYSTAL DECISIONS FOR TECHNICAL SUPPORT ....................12

6/24/2002 2:58 PM Copyright  2001 Crystal Decisions, Inc. All Rights Reserved. Page 1
Crystal Reports Connecting the RDC to my data source

Introduction
Using the RDC, Crystal Reports is able to report off of both active data sources
and persistent data sources. Active data sources are recordsets, resultsets, data
arrays and Data Environments that only exist in memory while the application is
running. Persistent data sources are databases, tables, log files, directory
structures, etc. that reside and exist outside of the application. Persistent data can
be broken down further into PC-type data sources and server-type data sources.

The methods/properties of the RDC used to connect reports to these varying data
sources include:

Active Data:

SetDataSource, SetTablePrivateData

AddADOCommand

AddOLEDBSource

Persistent Data:

SetLogonInfo

Location, SetTableLocation

SetSessionInfo

LogonServer, LogonServerEx

Active Data Sources

All reports designed to use Active Data will use the Crystal Reports Active Data
driver, p2smon.dll. The Active Data driver is not designed to report off of a
persistent data source.

SetDataSource and SetTablePrivateData

The SetDataSource method and SetTablePrivateData method are designed to do
exactly the same thing: Pass a populated connected or disconnected recordset to
a report. The SetTablePrivateData is a hidden member of the DatabaseTable
object and is maintained for backwards compatibility. The SetDataSource of the
Database object should be used instead.

6/24/2002 2:58 PM Copyright  2001 Crystal Decisions, Inc. All Rights Reserved. Page 2

cr_rdc_dbconnectivity.pdf
Crystal Reports Connecting the RDC to my data source

Syntax for SetTablePrivateData Method

The syntax of the SetTablePrivateData method is:

Sub SetTablePrivateData(DataTag as long, data)

The first argument, DataTag, is always passed in as the value 3 (this refers to
Active Data). The second argument, data, is one of the following:

• An ActiveX Data Object (ADO) recordset

• A Crystal Data Object (CDO) rowset

• A Remote Data Object (RDO) resultset

Sample code using the SetTablePrivateData Method

Dim Report As New CrystalReport1
Dim ADOrs As New ADODB.Recordset

ADOrs.Open “Select * from Customer”, _

“DSN=Xtreme Sample Database”

‘Pass the ADO Recordset to the first Table in Report

Report.Database.Tables(1).SetTablePrivateData _
3, ADOrs

Syntax for the SetDataSource Method

The syntax for the SetDataSource method is:
Arguments in square brackets are Database Object
optional.
Sub SetDataSource(data, [dataTag], [tableNumber])

DatabaseTable Object
Sub SetDataSource(data, [dataTag])
The first argument, data, is the recordset/resultset (as mentioned above). The
second optional argument, dataTag, is optional and should always be 3 when
used. Using any other value for dataTag will cause unexpected results. The
third optional argument, tableNumber, specifies which table in the report to
pass the recordset to (the numbering is 1-based with the first table in the report
having the value 1, the second table having the value 2, and so on).

When calling SetDataSource at the DatabaseTable object level, the

tableNumber argument is redundant and should be omitted.

6/24/2002 2:58 PM Copyright  2001 Crystal Decisions, Inc. All Rights Reserved. Page 3

cr_rdc_dbconnectivity.pdf
Crystal Reports Connecting the RDC to my data source

Sample code using the SetDataSource Method

Dim Report As New CrystalReport1
Dim ADOrs As New ADODB.Recordset

ADOrs.Open “Select * from Customer”, _

“DSN=Xtreme Sample Database”

‘Pass the ADO Recordset the Report

Report.Database.SetDataSource ADOrs

Whenever possible it is recommended to use the SetDataSource method of the

Database object and not the DatabaseTable object. This is due to the nature of
active data, and the design of the p2smon.dll.

Reports designed against an active data source should be designed to expect one
recordset. Linking between multiple recordsets defeats the purpose of active
data. A properly designed recordset will perform all of the linking and filtering
prior to passing the data to the Crystal Reports Active Data driver, p2smon.dll.

Once a recordset is populated, it is a huge array of data in memory (without any

indexes). Crystal Reports Active Data driver does not perform the linking or
filtering as quickly as a persistent data sources given that there are no indexes to
work with.

NOTE This document does not discuss how to create recordsets or how to design reports to use
Active Data. For more information on designing reports using active data, refer to the file:
scr8_ttxado.pdf
at http://support.crystaldecisions.com/library

Data Environments
The most important thing to remember when working with a Data Environment
is that a Data Environment is just a graphical interface for ADO recordsets.
When designing a report against a Data Environment, Crystal Reports needs a
method to save the structure of a recordset generated from the Data
Environment. Crystal Reports needs to know the order of the fields and their
data types to allow a report to be designed against the Data Environment.

Crystal Reports Active Data driver creates this structure internally by saving the
Data Environment’s (or ADO’s) Command object. However when an
application fails to properly pass a recordset to the report at runtime, unexpected
results can occur. This includes error messages such as “Server not yet open” or
“Physical Database not found” when the report is distributed, the database is
moved, or the Data Environment is changed.

The report is designed to only read the Command object once (at the original
design of the report) to retrieve the recordset’s structure. Any changes to the
Command object or Data Environment are not actively updated.

6/24/2002 2:58 PM Copyright  2001 Crystal Decisions, Inc. All Rights Reserved. Page 4

cr_rdc_dbconnectivity.pdf
Crystal Reports Connecting the RDC to my data source

At runtime, the report is always expecting to be passed a recordset using the

SetDataSource method mentioned above.

Sample Code using a Data Environment

Dim Report As New CrystalReport1
DataEnvironment1.Command1

Report.Database.SetDataSource _
DataEnvironment1.Recordsets(1)

Notice that the code is identical to populating a recordset and using the
SetDataSource method.

AddADOCommand and AddOLEDBSource

These methods are designed to add tables to a report at runtime. Generally
speaking, these methods only need to be used when a report is being created on-
the-fly (using Report Creation API) against a data source with varying structure.

NOTE If the report’s data structure is static (field names and field data types do not change; only
the volume of data changes from run to run of the report) then the report’s tables should
be added at design time using a Data Definition (TTX) file, and a recordset passed to the
report at runtime using the SetDataSource method.

Syntax for the AddADOCommand Method

The syntax for the AddADOCommand method is:

Sub AddADOCommand(pConnection, pCommand)

AddADOCommand is designed to work with a connected recordset. The report

uses the first argument, the ADO Connection object (pConnection), to connect
to the data source. It uses the second argument, the ADO Command object
(pCommand), to obtain table structure and populate the report with data
returned from the Command object.

NOTE AddADOCommand is not designed to work with stored procedures. As a workaround,

populate a recordset from the stored procedure and use the DatabaseTable’s Add
method to pass the recordset to the report.
For more information, see Knowledge Base article c2007177 at
http://support.crystaldecisions.com/kbase

6/24/2002 2:58 PM Copyright  2001 Crystal Decisions, Inc. All Rights Reserved. Page 5

cr_rdc_dbconnectivity.pdf
Crystal Reports Connecting the RDC to my data source

Sample Code Using the AddADOCommand Method

Dim Report As New CrystalReport1
Dim ADOcn As New ADODB.Connection
Dim ADOcmd As New ADODB.Command

ADOcn.CursorLocation = adUseClient
ADOcn.Open "DSN=Xtreme Sample Database"

ADOcmd.ActiveConnection = ADOcn
ADOcmd.CommandText = "Select * from Customer"

Report.Database.AddADOCommand ADOcn, ADOcmd

AddOLEDBSource is designed the same way as AddADOCommand in that it

adds a new table to the report. The difference is that it does not work with
active data; instead it adds a table connecting through OLE DB to a persistent
data source. The Crystal Reports database driver used is the P2soledb.dll.

Syntax for the AddOLEDBSource Method

The syntax for the AddOLEDBSource method is:

Sub AddOLEDBSource(pConnectionString As String,

pTableName As String)

The first argument, pConnectionString, is an OLE DB connection string

specifying which data source to connect to. The second argument,
pTableName, is the name of the table in the data source to be added to the
report.

Sample code using the AddOLEDBSource Method

Dim Report As New CrystalReport1

Report.Database.AddOLEDBSource _
"DSN=Xtreme Sample Database”, “Customer”

NOTE For more information on how to create an OLE DB connection string, see Microsoft
Knowledge Base article Q218600 at http://msdn.microsoft.com

6/24/2002 2:58 PM Copyright  2001 Crystal Decisions, Inc. All Rights Reserved. Page 6

cr_rdc_dbconnectivity.pdf
Crystal Reports Connecting the RDC to my data source

Persistent Data Sources

Unlike active data sources, which only exist for the duration of an application’s
execution, persistent data sources (databases) reside on either a local computer
or a server. Whether a database is a local PC database or a server-type database,
the properties/methods used to connect to the database using the RDC will be
one or more of the following:

SetLogonInfo

Location, SetTableLocation

SetSessionInfo

LogonServer, LogonServerEx

SetLogonInfo
The SetLogonInfo method of the DatabaseTable object is the most popular
method for connecting a report to its database. SetLogonInfo is primarily used
for connecting to ODBC and server-type databases. Server-type databases
include MS SQL Server, Oracle, DB2, Informix, Sybase, Pervasive SQL Server,
etc.

Syntax for SetLogonInfo method

Arguments in square brackets are Sub SetLogonInfo(pServerName as string,
optional.
[pDatabaseName],[pUserID],[pPassword])

pServerName is the physical name of your server (i.e. computerName) or

ODBC Data Source Name (DSN).

PDatabaseName is the name of your database (i.e. pubs).

pUserID, and pPassword are the user ID and password.

TIP To use the logon values already stored in a report (RPT) file, use empty strings (“”) for the
pServerName, pDatabaseName, and pUserID arguments. You will always need to set a
value for the pPassword.

6/24/2002 2:58 PM Copyright  2001 Crystal Decisions, Inc. All Rights Reserved. Page 7

cr_rdc_dbconnectivity.pdf
Crystal Reports Connecting the RDC to my data source

NOTE When connecting through OLE DB to an MS Jet provider, pServerName is the path to the
Access Database (such as “c:\path\to\database.mdb”).
When using an Oracle database, pDatabaseName should be set to an empty string (“”).

NOTE When using ODBC, pServerName sets the data source location to a new ODBC DSN.
PServerName cannot be used to specify a different path/location than what is specified in
the ODBC DSN.
To change the path to a PC-type data source when using a single ODBC DSN, pass in a
database qualifier as the value for PdatabaseName using the syntax:
"<CRWDC>DBQ=<path to the new database>"

Sample Code using the SetLogonInfo method

‘Connect through ODBC to CRSS DSN (MS SQL Server)
Report.Database.Tables(1).SetLogonInfo “CRSS”, _
“pubs”, “sa”, “sa”

‘Connect natively to Oracle Service (TSN)

Report.Database.Tables(1).SetLogonInfo “Service”, _
“”, “Scott”, “Tiger”

‘Pass Database level security to a PC database

through ODBC (Access mdb)
Report.Database.Tables(1).SetLogonInfo “”, “”, “”, _
“password”

‘Connect to a PC database through ODBC. Use a

different path to the database than that specified in
the DSN.
Report.Database.Tables(1).SetLogonInfo _
“”, “<CRWDC>DBQ=C:\path\to\Database.mdb”, “”, “”

‘Connect through OLEDB to an Access Database

Report.Database.Tables(1).SetLogonInfo _
“C:\path\to\Database.mdb”

6/24/2002 2:58 PM Copyright  2001 Crystal Decisions, Inc. All Rights Reserved. Page 8

cr_rdc_dbconnectivity.pdf
Crystal Reports Connecting the RDC to my data source

Tip To see the pServerName, pDatabaseName and pUserid values that your report is
designed against, check the Set Location box under the Database | Set Location menu
in Crystal Reports.
This example shows an ODBC connection to a MS Access database:

Location Property
The Location property of the DatabaseTable object is used to change tables
when connecting to a server type-database. The Location property also sets the
path to a PC-type database.

Syntax for Location property

Property Location as string
The location property is a read/write property

Sample code for the Location Property

‘Changing Databases and/or Table names to a SQL Table
Report.Database.Tables(1).Location =
“pubs.dbo.Authors”

‘Oracle does not have a database concept

Report.Database.Tables(1).Location =
“schema.TableName”

‘Connecting natively to a PC type database

Report.Database.Tables(1).Location = _
“c:\path\to\database.mdb”

6/24/2002 2:58 PM Copyright  2001 Crystal Decisions, Inc. All Rights Reserved. Page 9

cr_rdc_dbconnectivity.pdf
Crystal Reports Connecting the RDC to my data source

Syntax for SetTableLocation Method

Sub SetTableLocation(pLocation As String,
pSubLocation As String, pConnectBufferSting As
String)

The SetTableLocation method of the DatabaseTable object works similarly to

setting the Location property. The main difference being that SetTableLocation
also allows writing to the SubLocation property, which is a read-only property.
The SubLocation property changes MS Access table names when connecting
natively.

The pConnectBufferSting property should be set to an empty string (“”) when

using MS Access.

SetSessionInfo Method
The SetSessionInfo method of the DatabaseTableObject is used when
connecting natively to a MS Access database that contains either session level
(user level) security, database level security, or both.

Syntax for SetSessionInfo Method

Sub SetSessionInfo(pSessionUserID As String,
pSessionPassword As String)

Sample code for SetSessionInfo Method

‘Just Database Level security
Report.Database.Tables(1).SetSessionInfo _
"userID", Chr(10) & "dbpassword"

‘Just Session Level security

Report.Database.Tables(1).SetSessionInfo _
"userID","sesspswd"

‘Both Database and Session Level security

Report.Database.Tables(1).SetSessionInfo _
"userID", "sesspswd" & Chr(10) & "dbpassword"

NOTE When connecting through OLE DB to a secure MS Access database use LogonServerEx

LogonServer and LogonServerEx

LogonServer and LogonServerEx are probably the most misunderstood methods
available for making a connection to a database server. These two methods are

6/24/2002 2:58 PM Copyright  2001 Crystal Decisions, Inc. All Rights Reserved. Page 10

cr_rdc_dbconnectivity.pdf
Crystal Reports Connecting the RDC to my data source

easier to understand when looked at as only belonging to the Application object

(even though both also exist at the Database object level).

For simplicity, assume that both of these methods, LogonServer and

LogonServerEx, only exist at the Application object level. These methods are
designed to create a global connection, where they only need to be called once
and existing reports designed to use the connection are eligible to use it.
Reports not designed with the same connection information cannot use it.

Syntax for LogonServer

Sub LogOnServer(pDllName As String, pServerName As
String, [pDatabaseName], [pUserID], [pPassword])

pDllName is the Crystal Reports database driver used in the report (such as
P2sodbc.dll). This can be checked under the Database | Convert Database Driver
menu in Crystal Reports.

pServerName is the same as the pServerName argument in SetLogonInfo, it is

either the physical name of the server, or when connecting through ODBC, the
ODBC DSN.

pDatabaseName is the name of the database to log on to.

pUserID and pPassword are the user ID and password.

Sample code for LogonServer

Dim crApplication As New CRAXDRT.Application

crApplication.LogonServer “p2sodbc.dll”, “CRSS”, _

“pubs”, “sa”, “sa”

Syntax for LogonServerEx

Sub LogOnServerEx(pDllName As String, pServerName As
String, [pDatabaseName], [pUserID], [pPassword],
[pServerType], [pConnectionString])

Notice that the LogonServerEx arguments are exactly the same as those for
LogonServer, with the addition of pServerType and pConnectionString. The
pServerType argument value should be identical to the Server Type field found
in the Set Location box in Crystal Reports. The pConnectionString argument
value is used for setting OLE DB connection strings. This allows more
flexibility when using OLE DB as a connection string can be used in place of
the separate pDatabaseName, pUserID, pPassword arguments.

The LogonServerEx method is particularly useful when connecting through

OLE DB to a secure MS Access database with the MS Jet provider. The

6/24/2002 2:58 PM Copyright  2001 Crystal Decisions, Inc. All Rights Reserved. Page 11

cr_rdc_dbconnectivity.pdf
Crystal Reports Connecting the RDC to my data source

SetLogonInfo and LogonServer methods have no way of passing Jet security

information when using OLE DB.

For more information, see Knowledge Base article c2006622 at

http://support.crystaldecisions.com/kbase

Sample code using LogonServerEx

Report.Database.LogOnServerEx "p2soledb.dll", _
"C:\databases\Xtreme2000LiteDBSecure.mdb", "", "", _
"", "OLE DB", "Provider=Microsoft.Jet.OLEDB.4.0;Data
Source=C:\databases\Xtreme2000LiteDBSecure.mdb;Persis
t Security Info=False;Jet OLEDB:Database
Password=password"

Contacting Crystal Decisions for Technical Support

We recommend that you refer to the product documentation and that you visit
our Technical Support web site for more resources.

Self-serve Support:
http://support.crystaldecisions.com/

Email Support:
http://support.crystaldecisions.com/support/answers.asp

Telephone Support:
http://www.crystaldecisions.com/contact/support.asp

6/24/2002 2:58 PM Copyright  2001 Crystal Decisions, Inc. All Rights Reserved. Page 12

cr_rdc_dbconnectivity.pdf