report designer component 9 - archive designer...report designer component connection properties o...

10/21/2004 12:38 PM Copyright © 2003 Crystal Decisions, Inc. All Rights Reserved.

Report Designer Component 9

Connection Properties

Overview The Crystal Reports 9 Report Designer Component (RDC) has a number of new 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 new properties and methods. This document provides a better understanding of how to connect your Crystal Report to your data sources at runtime.

This document is a supplement to cr_rdc_dbconnectivity.pdf. Cr_rdc_dbconnectivity.pdf describes the other connection methods available to the RDC.

Contents INTRODUCTION.........................................................................................................2 DETECTING CONNECTION PROPERTIES .....................................................................2

Where to Find the Connection Properties ...................................................2 CONNECTING TO A DATA SOURCE USING CONNECTION PROPERTIES .........................3 NATIVE CONNECTIONS .............................................................................................4

Native – Microsoft Access............................................................................4 Native - Btrieve ............................................................................................5 Native - Oracle.............................................................................................6

ODBC CONNECTIONS..............................................................................................7 ODBC – Microsoft Access ...........................................................................7 ODBC - SQL Server.....................................................................................8 ODBC - Oracle ..........................................................................................10

OLE DB CONNECTIONS.........................................................................................11 OLE DB – Microsoft Access ......................................................................11 OLE DB - SQL Server................................................................................13 OLE DB - Oracle .......................................................................................14

SETTING DATA SOURCE CONNECTION INFORMATION FOR SUBREPORTS...................16 WHAT ABOUT OLDER REPORTS? ...........................................................................17 LISTING OF ATTRIBUTES FOR CONNECTIONINFO OBJECT.........................................17

Report Designer Component Connection Properties

Introduction In Crystal Reports 9, a new series of database properties were introduced in the report designer. To incorporate these new properties into the Report Designer Control (RDC), a new ConnectionProperties collection was created.

The ConnectionProperties collection is a collection of ConnectionProperty Objects in a report. Each object in the collection is a property bag that contains information on a connection property.

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 hold common properties defined in our database DLLs, connection properties from the supporting drivers, or both.

For example, a report using an OLE DB (ADO) connection to Microsoft SQL Server will contain properties supplied by the database DLL (crdb_ado.dll). These properties include 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 report data source or to change the report data source.

Detecting Connection Properties

Where to Find the Connection Properties Connection properties can be found in the Crystal Reports 9 report designer or listed at runtime through code.

Connection Properties in the Report Designer The connection properties can be found in the report (in the format ‘Description: Value Pairs’) using these steps:

1. Open the report up in the Crystal Reports 9 report designer (crw32.exe). Go to the Database menu and select Set Datasource Location.

2. The Set Datasource location dialog box appears and displays your current database connection, plus the properties/tables used by your report.

3. If you expand the properties under the database connection, all of the properties used by this database connection appear. All of these properties can be set at runtime.

NOTE The connection properties shown are in the format “Description: Value Pairs”.

For most properties, the description and name are the same. At runtime the name of the connection property is required to set a value or add a name value pair.


cr_rdc9_connectionproperties.pdf


Connection Properties at Runtime A complete set of a report table’s connection property can be listed using the following code (the connection property is in the format name value pairs):

'Declare a ConnectionProperty Object

Dim CPProperty As CRAXDRT.ConnectionProperty

For Each CPProperty In Report.Database.Tables(1).ConnectionProperties

'Add the name of the connection property to List 1

List1.AddItem CPProperty.Name

'Add the value of the connection property to List 2

'Any Password property is write only so list the value 'as an empty string

If InStr(1, CPProperty.Name, "Password", 1) > 0 Then

List2.AddItem ""

Else

List2.AddItem CPProperty.Value

End If

Next CPProperty

Connecting to a Data Source Using Connection Properties The ConnectionProperties collection can be used to:

• Connect to the existing data source

o Same data source used in the creation of the report

• Connect to a different data source of the same data type 10/21/2004 12:38 PM Copyright © 2003 Crystal Decisions, Inc. All Rights Reserved.



o Report is created off ODBC to Oracle and connecting to a different server

o Report is created off OLE DB to Microsoft Access and connecting to a different database location

• Connect to a data source of a different data type

o Report is created off OLE DB to SQL Server and connecting to a different OLE DB provider or a different data type such as ODBC or a Native connection.

Connecting to the data source at runtime can be as simple as setting a single property to connect, such as the Password, or changing the data source entirely by deleting the existing ConnectionProperty property bags from the collection and adding the proper name value pairs to connect to the desired data source.

The following sections detail several common data sources a report can connect to, and provides code for connecting to that data source or switching to that data type from a different data source.

Native Connections This section lists the connection properties available for Microsoft Access, Btrieve, and Oracle and demonstrates how to connect those data sources through the native drivers.

The following sample code (for a native connection to Microsoft Access, Btrieve and Oracle) describes how to:

• Connect to a data source of the same data type


Native – Microsoft Access Connection Properties:

• Database Name

• Database Type

• Database Password

• Session UserID

• Session Password

• System Database Path

Connecting Microsoft Access (Native) at Runtime 'Declare a Connection Info Object

Dim ConnectionInfo As CRAXDRT.ConnectionProperties

‘Set the Connection Info to Connection Properties of ‘the table object

Set ConnectionInfo = Report.Database.Tables(1).ConnectionProperties

10/21/2004 12:38 PM Copyright © 2003 Crystal Decisions, Inc. All Rights Reserved. 'Set the database used by the report



ConnectionInfo.Item(“Database Name”) = “C:\Folder\NewDatabase.mdb”

'Set the database level password to the report

ConnectionInfo.Item(“Database Password”) = “Password”

'Set the session level user and password

ConnectionInfo.Item(“Session UserID”) = “User”

ConnectionInfo.Item(“Session Password”) = “Password”

'Set the system database path

ConnectionInfo.Item(“System Database Path”) = “C:\Folder\System.mdw”

Changing to Microsoft Access (Native) at Runtime 'Declare a Connection Info Object


'Set the Connection Info to Connection Properties of the table object


'Set the DLL name to the native Access driver

Report.Database.Tables(1).DLLName = “crdb_dao.dll”

'Clear the ConnectionProperties collection.

ConnectionInfo.DeleteAll

'Add the database used by the report

ConnectionInfo.Add “Database Name”, “C:\Folder\NewDatabase.mdb”

'Add the database level password to the report

ConnectionInfo.Add “Database Password”, “Password”

'Add the session level user and password

ConnectionInfo.Add “Session UserID”, “User”

ConnectionInfo.Add “Session Password”, “Password”

'Add the system database path

ConnectionInfo.Add “System Database Path”, “C:\Folder\System.mdw”

Native - Btrieve Connection Properties:

• Data File

• Data File Search Path

Changing the Btrieve Table Location at Runtime To change the Btrieve table location at runtime in Visual Basic 6 use sample code below: ==================== NOTE:




The 'Data File' and 'Data File Search Path' are global report properties. This means that any changes made to these properties will be applied globally to the report regardless of what table you retrieved the ConnectionProperties from. This means if the new table file exists in both the original (path saved with report) as well as the new data file location (set in code), the table file will be loaded from the path saved with the report. To work around this, set the 'Data File Search Path' to a blank string as shown below. ==================== Report.Database.Tables(1).ConnectionProperties("Data File Search Path") = "" Report.Database.Tables(1).Location = "C:\yourNewPath\Table.DAT" 'If the new table file is different than the original or the original file will no longer exist at runtime, then set the 'Data File' and 'Data File Search Path': Report.Database.Tables(1).ConnectionProperties("Data File") = "C:\yourNewPath\FILE.DDF" Report.Database.Tables(1).ConnectionProperties("Data File Search Path") = "C:\yourNewPath\" 'If you want to change the location for additional Btrieve tables, you only need to set the 'Location' property since the 'Data File' and 'Data File Search Path' are set globally the first time you modify them. Report.Database.Tables(2).Location = "C:\yourNewPath\Table.DAT"

Native - Oracle Connection Properties:

• Server

• User ID

• Password

Connecting Oracle (Native) at Runtime 'Declare a Connection Info Object


'Set the Connection Info to Connection Properties of ‘the table object


'Set the server name

ConnectionInfo.Item(“Server”) = “Server name”

'Set the user name

ConnectionInfo.Item(“User ID”) = “User name”


'Set the password



ConnectionInfo.Item(“Password”) = “Password”

Changing to Oracle (Native) at Runtime 'Declare a Connection Info Object




'Set the DLL name to the native Oracle driver

Report.Database.Tables(1).DLLName = “crdb_oracle.dll”

'Clear the ConnectionProperties collection


'Add the server name

ConnectionInfo.Add “Server”, “Server name”

'Add the user name

ConnectionInfo.Add “User ID”, “User name”

'Add the password

ConnectionInfo.Add “Password”, “Password”

'Set the fully qualified table name if different

'from the original data source

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

ODBC Connections This section lists the connection properties available for Microsoft Access, Microsoft SQL Server, and Oracle and demonstrates how to connect those data sources through the ODBC driver.

The following sample code (for an ODBC connection to Microsoft Access, Btrieve and Oracle) describes how to:



ODBC – Microsoft Access Connection Properties:

• DSN

• Password

Connecting to Microsoft Access (ODBC) at Runtime 'Declare a Connection Info Object







'Set the ODBC DSN

ConnectionInfo.Item(“DSN”) = “ODBC DSN”

'Set the Database level password if required


'Set the table name if different from the original ‘data source

Report.Database.Tables(1).Location = “tablename”

Changing to Microsoft Access (ODBC) at Runtime 'Declare a Connection Info Object




'Set the DLL name to the ODBC driver

Report.Database.Tables(1).DLLName = “crdb_odbc.dll”



'Add the ODBC DSN

ConnectionInfo.Add “DSN”, “ODBC DSN”

'Add the database level password if required


'Set the table name if different from the original 'data source


NOTE If the Microsoft Access database has a session level security, this should be setup in the DSN.

The session level security cannot be passed at runtime.

ODBC - SQL Server Connection Properties:

• DSN

• User ID

• Password

• Database

• Trusted_Connection 10/21/2004 12:38 PM Copyright © 2003 Crystal Decisions, Inc. All Rights Reserved.



Connecting to SQL Server (ODBC) at Runtime 'Declare a Connection Info Object




'Set the ODBC DSN


'Set the database name

ConnectionInfo.Item(“Database”) = “Database name”

'Set the user name


'Set the password


'Set the fully qualified table name if different from ‘the original data source

Report.Database.Tables(1).Location = “database.owner.tablename”

Changing to SQL Server (ODBC) at Runtime 'Declare a Connection Info Object








'Add the ODBC DSN


'Add the database name

ConnectionInfo.Add “Database”, “Database name”

'Add the user name


'Add the password


'Set the fully qualified table name if different from 'the original data source





NOTE If the database uses SQL Authentication and the user has a password, you need to pass at least the Password to the report. You do not need to specify the DSN, User ID or Database unless you are attempting to change any of these at runtime.

If the database uses NT Authentication, do not specify the user name or password.

To set the type of authentication set Trusted_Connection to 0 for SQL Authentication or set Trusted_Connection to 1 for NT Authentication.

ODBC - Oracle Connection Properties:

• Server

• User ID

• Password

Connecting to Oracle (ODBC) at Runtime 'Declare a Connection Info Object




'Set the ODBC DSN


'Set the user name


'Set the password


'Set the fully qualified table name if different from 'the original data source


Changing to Oracle (ODBC) at Runtime 'Declare a Connection Info Object








'Add the ODBC DSN





'Add the user name


'Add the password




OLE DB Connections This section lists the connection properties available for Microsoft Access, Microsoft SQL Server, and Oracle and demonstrates how to connect those data sources through the OLE DB driver.

The following sample code (for an OLE DB connection to Microsoft Access, Btrieve and Oracle) describes how to:



OLE DB – Microsoft Access Connection Properties:

• Provider

• Data Source

• User ID

• Password

• Jet System Database

• Jet Database Password

• Database Type

• Locale Identifier

• OLE DB Services

Connecting to Access (OLE DB) at Runtime 'Declare a Connection Info Object




'Set the OLE DB provider

ConnectionInfo.Item(“Provider”) = “Microsoft.Jet.OLE DB.4.0”




'Set the path and name of the Access database file

ConnectionInfo.Item(“Data Source”) = “C:\Folder\Data.mdb”

'If using database level security:

'Set the database password.

ConnectionInfo.Item(“Jet Database Password”) = “Database Password”

'If using session level security:

'Set the user name ConnectionInfo.Item(“User ID”) = “User”

'Set the system level password ConnectionInfo.Item(“Password”) = “Password”

'Set the location of the system database ConnectionInfo.Item(“Jet System Database”) = “C:\Folder\System.mdw”

Changing to Access (OLE DB) at Runtime 'Declare a Connection Info Object




'Set the DLL name

Report.Database.Tables(1).DLLName = “crdb_ado.dll”



'Add the OLE DB provider

ConnectionInfo.Add “Provider”, “Microsoft.Jet.OLE DB.4.0”

'Add the path and name of the Access database

ConnectionInfo.Add “Data Source”, “C:\Folder\Data.mdb”

'If using database level security:

'Add the database password.

ConnectionInfo.Add “Jet Database Password”, “Database Password”

'If using session level security:

'Add the user name. ConnectionInfo.Add “User ID”, “User name”

'Add the system level password. ConnectionInfo.Add “Password”, “Password”

'Add the location of the system database. ConnectionInfo.Add “Jet System Database”, “C:\Folder\System.mdw”

'Set the table name if different from the original 'data source.





OLE DB - SQL Server Connection Properties:

• Provider

• Data Source

• Initial Catalog

• User ID

• Password

• Integrated Security


• Connect Timeout

• General Timeout

• OLE DB Services

• Current Language

• Initial File Name

• Use Encryption for Data

• Replication server name connect option

• Tag with column collation when possible

Connecting to SQL Server (OLE DB) at Runtime 'Declare a Connection Info Object




'Set the OLE DB Provider

ConnectionInfo.Item(“Provider”) = “SQLOLEDB”

'Set the physical server name

ConnectionInfo.Item(“Data Source”) = “Server name”

'Set the database name

ConnectionInfo.Item(“Initial Catalog”) = “Database name”

'Set the integrated security

ConnectionInfo.Item(“Integrated Security”) = True

'Set the user name


'Set the password







Changing to SQL Server (OLE DB) at Runtime 'Declare a Connection Info Object




'Set the DLL name

Report.Database.Tables(1).DLLName = “crdb_ado.dll”



'Add the OLE DB Provider

ConnectionInfo.Add “Provider”, “SQLOLEDB”

'Add the physical server name

ConnectionInfo.Add “Data Source”, “Server name”

'Add the database name

ConnectionInfo.Add “Initial Catalog”, “Database name”

'Add the user name


'Add the password




NOTE If the database uses SQL Authentication and the user has a password, you need to pass at least the Password to the report. You do not need to specify the DSN, User ID or Database unless you are attempting to change any of these at runtime.

If the database uses NT Authentication, do not specify the user name or password.

To set the type of authentication set Trusted_Connection to 0 for SQL Authentication or set Trusted_Connection to 1 for NT Authentication. For an OLEDB connection, you will need to set "Integrated Security" to 0 or 1 for SQL or NT authentication respectively.

OLE DB - Oracle Connection Properties:

• Provider

• Data Source

• User ID

• Password





• OLE DB Services

Connecting to Oracle (OLE DB) at Runtime 'Declare a Connection Info Object




'Set the OLE DB Provider

ConnectionInfo.Item(“Provider”) = “SQLOLEDB”

'Set the physical server name

ConnectionInfo.Item(“Data Source”) = “Server name”

'Set the user name


'Set the password




Changing to SQL Server (OLE DB) at Runtime 'Declare a Connection Info Object








'Add the OLE DB Provider

ConnectionInfo.Add “Provider”, “MSDAORA”

'Add the physical server name

ConnectionInfo.Add “Data Source”, “Server name”

'Add the user name


'Add the password







Setting Data Source Connection Information for Subreports If a report contains one or more subreports, the connection information must be provided to tables in those subreports. To do this, your code must loop through each section of the main report to locate subreports. When the subreport has been located the connection properties can be set similarly to those of the main report.

The following code is not database or connection type specific.

'Declare variables for the report, subreport, table, and 'collections of those objects.

Dim crxTables As CRAXDRT.DatabaseTables

Dim crxTable As CRAXDRT.DatabaseTable

Dim crxSections As CRAXDRT.Sections

Dim crxSection As CRAXDRT.Section

Dim crxSubreportObj As CRAXDRT.SubreportObject

Dim crxReportObjects As CRAXDRT.ReportObjects

Dim crxSubreport As CRAXDRT.Report

Dim ReportObject As Object

'The following code can be used in the Form_Load event

'of the startup form that contains the viewer.

'Get the sections from the main report

Set crxSections = Report.Sections

'Loop through each section in the main report

For Each crxSection In crxSections

'Get all the objects in this section

Set crxReportObjects = crxSection.ReportObjects

'Loop through each object in the ReportObjects

'for this section.

For Each ReportObject In crxReportObjects

'Find the SubreportObject object

If ReportObject.Kind = crSubreportObject Then

'Find a subreport and get a handle to it

Set crxSubreportObj = ReportObject

'Open the subreport

Set crxSubreport = crxSubreportObj.OpenSubreport

'You will need to log on for every table in the 'subreport.


With crxSubreport.Database.Tables(1)



.DeleteAll '*******************************************

'Add subreport connection information here as per 'the connection properties appropriate for the 'database connection

'*******************************************

End With

'Set the location of the table in the report to the 'name of the table in the data source

crxSubreport.Database.Tables(1).SetTableLocation _

"", "DBTableName", ""

End If

Next ReportObject

Next crxSection

What About Older Reports? For any reports that were not created or upgraded to version 9, you can still list the connection properties through code. Refer to the section “Connection Properties at Runtime” for further information.

Once you have a listing of the connection properties, you can set them using the code samples provided in this document.

Other options include deleting all the connection properties and then adding the name values pairs for the desired data source connection. Another option is to use the older methods described in “cr_rdc_dbconnectivity.pdf” to set the connection information. Download this document from http://support.crystaldecisions.com/docs.

Listing of Attributes for ConnectionInfo Object The following are the valid properties of the Attributes property bag for the ConnectionInfo object:

NOTE "L" - denotes a logon property set in the Crystal Reports Designer during the initial logon to the data source.

"S" - denotes a Set Datasource Location property in the Crystal Reports Designer. These properties are set in order to change the database used by the report. When some of these properties are set at runtime, they are visible in the Set Datasource Location dialog box (not all of the properties that appear in this dialog box are available for editing).



http://support.crystaldecisions.com/docs


Data Source Connection

Property Description

ODBC - SQL Server

DSN ODBC data source name. (S, L)

File DSN Path to the file DSN. (L) Connection String The complete connection string containing the

driver information. This can be obtained from the contents of a File DSN. (L)

Password Password used to connect to the data source. (L) User ID User name required to connect to the data source.

(S, L) Database The name of the database. (L) Database type Type of connection. (S) Trusted Connection Set to True if you want the connection to use NT

Authentication. (L) Use DSN Default

Properties When selected, use default properties of the DSN. (S)

ODBC – Access DSN ODBC data source name. (S, L) File DSN Path of the file DSN. (L) Connection String The complete connection string containing the


Database Password Password used to connect to the data source. (L) Database The name of the database. (L) Database type Type of connection. (S) ODBC – DB2 DSN ODBC data source name. (S, L) File DSN Path of the file DSN. (L) Connection String The complete connection string containing the


Database Password Password used to connect to the data source. (L) User ID User name required to connect to the data source.

(S, L) Database The name of the database. (L) Database type Type of connection. (S) ODBC – Sybase DSN ODBC data source name. (S, L) File DSN Path of the file DSN. (L) Connection String The complete connection string containing the



(S, L) Database The name of the database. (L) Database type Type of connection. (S) 10/21/2004 12:38 PM Copyright © 2003 Crystal Decisions, Inc. All Rights Reserved.



ODBC (RDO) –Informix

DSN ODBC data source name. (S, L)

File DSN Path of the file DSN. (L) Connection String The complete connection string containing the



(S) Database type Type of connection. (S) Database The name of the database. (S, L)




Data Source Connection Property Description DAO – Access Database Name The name of the database. (S, L) Database type Type of connection. (S, L) Secure Logon Set to true if data source requires secure logon and

complete the information required by the following four properties. (L)

Database password Password used to logon to database. (L) Session User ID The user ID for the current session. (S, L) Session Password The password associated with the Session User ID.

(L) System Database Path The path of the database. (S, L) OLEDB - SQL Server

Provider The OLE DB initialization property containing provider-specific connection information. (S, L)

Use Data Link File Set to true if the connection will use a Data Link File. (L)

Server ("Data Source" in Current Data Source window)

Network name of the database server. (S, L)

User ID User name required to connect to the data source. (S, L)

Password Password for specified User ID. (L) Database ("Initial

Catalog" in Current Data Source window)

SQL Server database name. (L)

Integrated Security Set to true to use NT Authentication. (S, L) Database Type Type of connection. (S) Advanced Information It is not recommended that you modify the

advanced properties. See the database driver information for details. (S, L)

ADO .NET - SQL Server

Database Type Type of connection. (S)

File Path Full path to customer data provider DLL. (S, L) Use Classes from Project Set to true to use classes from project. If true, next

property is enabled. (L) Class Name Name of class used to connect to data source. (S,

L) Oracle native driver

Service Database alias as defined in the TNSnames file. (S, L)


Password Password for specified User ID. (L) OS Authentication Use NT Authentication. (L) Database Type Type of connection. (S) Command in Repository

Database Type Type of connection. (S)




Use Saved Properties Indicates if user opened report with refresh from Repository=TRUE. (S)

Repository URI Repository URI. (S, L) Repository Object Name Repository object name. (S, L) Author Name of author. (S, L) Description Select statement. (S) Refreshed from

Repository True if refresh from repository was successful. (L)


Location Full path for location of repository. (L)




For reports created before 9, the following are the valid properties of the Attributes property bag for the ConnectionInfo object:

Key/Attribute Explanation

Database DLL The DLL that is being used to communicate with the database. Applies to all connections.

URI The URI (Uniform Resource Identifier) or path of the database file. Applies to Crystal Business Views, Query, and File connections.

Server Type The type of the server. Applies to SQL connections. Server Name The name of the server. Applies to SQL connections. Database Name The name of the database being accessed. Applies to SQL connections. Connection String A string that supplies extra parameters to the SQL server if it needs

them. Applies to SQL connections. Private Data This string is used to contain additional information that RAS may need

to connect to a specific database. The contents of this string are dependent on the database driver. Refer to your database documentation for information on what the driver requires to make a connection. The following databases use Private Data:

• Open Database Connectivity (ODBC) databases • OLE Databases • OLAP Databases

Applies to SQL connections. QE_DatabaseName The name of the database being accessed. Applies to Crystal Report

Query Engine (CRQE) connections. QE_DatabaseType A user-friendly description of the database being accessed. Applies to

CRQE connections. QE_LogonProperties The logon properties that form the connection string. Applies to CRQE

connections. QE_ServerDescription A user-friendly description of the server. Applies to CRQE connections.QE_SQLDB True if the data source supports SQL.



report designer component 9 - archive designer...report designer component connection properties o...

Documents