Crystal Reports. Overview. Contents. Connecting the Report Designer Component to a Data Source

Transcription

1 Connecting the Report Designer Component to a Data Source Overview Contents 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. 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 LogonServer and LogonServerEx CONTACTING CRYSTAL DECISIONS FOR TECHNICAL SUPPORT /24/2002 2:58 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 1

2 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: Persistent Data: SetDataSource, SetTablePrivateData AddADOCommand AddOLEDBSource 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

3 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 optional. Database Object 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

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

5 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 onthe-fly (using Report Creation API) against a data source with varying structure. 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. 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 c at 6/24/2002 2:58 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 5

6 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 For more information on how to create an OLE DB connection string, see Microsoft Knowledge Base article Q at 6/24/2002 2:58 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 6

7 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. Arguments in square brackets are optional. Syntax for SetLogonInfo method Sub SetLogonInfo(pServerName as string, [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

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

9 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

10 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" 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

11 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

12 SetLogonInfo and LogonServer methods have no way of passing Jet security information when using OLE DB. For more information, see Knowledge Base article c at 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: Support: Telephone Support: 6/24/2002 2:58 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 12