Crystal Reports. Overview. Contents. Getting Started with the Crystal Report Designer Component in Microsoft Visual C++

Size: px

Start display at page:

Download "Crystal Reports. Overview. Contents. Getting Started with the Crystal Report Designer Component in Microsoft Visual C++"

Valentine Rudolph Baker
6 years ago
Views:

1 Crystal Reports Getting Started with the Crystal Report Designer Component in Microsoft Visual C++ Overview Contents This document discusses integrating the Crystal Report Designer Component (RDC) in Microsoft Visual C++. General C++ language considerations are also discussed. Finally, a number of examples of common report handling tasks are given and explained. This document is for use with Crystal Reports 7 and higher. INTRODUCTION...2 ADDING THE RDC RUNTIME LIBRARY IN VISUAL C WORKING WITH THE REPORT OBJECT...3 VARIANT AND BSTR...4 BSTR... 4 VARIANT... 5 Table of Variant Types... 5 WORKING WITH THE CRYSTAL REPORT VIEWER CONTROL...6 CLEANING UP...6 LOGGING ON TO A DATABASE...7 LogonServer... 7 SetLogonInfo... 8 PASSING AN ACTIVE DATA RECORDSET TO A REPORT...9 PASSING PARAMETER VALUES...10 Passing a String parameter Passing a Number parameter Passing a DateTime parameter OPENING A SUBREPORT...11 APPENDIX A - THE INTERFACES OF THE RDC...14 CONTACTING CRYSTAL DECISIONS FOR TECHNICAL SUPPORT /24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 1

2 Introduction The Crystal Report Designer Component Automation Server (Craxdrt.dll, often referred to as the RDC or Report Designer Component) is designed to take advantage of several features of the Microsoft Visual Basic IDE. However, the RDC can be integrated into other developer tools such as Microsoft Visual C++. Visual C++ 5 and 6 provide native COM support which the RDC requires. Accessing and implementing this support in Visual C++ is somewhat more involved than is the case with Visual Basic. The method used to expose the RDC s object model in Visual C++ also differs as to how it is exposed in Visual Basic. The RDC is broken into two main components. The Automation server component (Craxdrt.dll), and the Crystal Report Viewer control (Crviewer.dll) The Previewing a Report section of this paper shows how to use these two components of the RDC to preview a report. The Setting report properties section extends on this and shows how to pass values (such as database logon information or parameter field values) to a report at runtime. NOTE You may find the RDC Browser utility helpful to understand and visualize the RDC s object hierarchy. The RDC Browser utility allows you to navigate through the object hierarchy using an "Explorer tree" type interface. RDC Browser can be downloaded from the Crystal Decisions Support site at: support.crystaldecisions.net/docs If you are using Crystal Reports 8.0 or higher, download the file: RDC8_Browser.exe If you are using Crystal Reports 7.0, download the file: RDC_Browser.exe Adding the RDC runtime library in Visual C++ 1. Start a new project in Visual C++. Click the File menu and then click New. Select MFC AppWiz and name the project. Click OK. Choose "Dialog Based" in the first screen of the wizard and select "Finish" 2. In the application s header file add the runtime library using the #import keyword, for example: #import craxdrt.dll no_namespace; 3. In the application s header file, use the IApplicationPtr class to declare an Application object, for example: IApplicationPtr papplication; 4. In the class where you want use the Application object, create the Application object, for example: 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 2

3 extern CMyApplicationApp theapp; theapp.papplication.createinstance("crystalruntime.applicat ion"); Whereas the steps for Visual Basic are fairly intuitive, the same perhaps cannot be said for the Visual C++ example given above. A few points bear explanation. The #import keyword exposes the various interfaces of Craxdrt.dll. You should add the c:\program files\seagate software\report designer component\ directory to the list of directories in Visual C++. To add the directory, go the Tools menu, select Options and click the Directories tab. The no_namespace keyword indicates that you are not concerned with creating a namespace for the set of interfaces you are importing. Craxdrt.dll exposes an interface called IApplication, however, the #import keyword adds "Ptr" to the end of each interface to indicate that it has wrapped the interfaces into smart pointers. Smart pointers do a bit of the work for you, such as managing the life-cycle of the object created from the interface and wrapping arguments into safe-arrays. Microsoft Foundation Classes (MFC) applications automatically create a global application variable called theapp. Since you ve declared RDC interfaces in the application's header, they too are global and can be accessed from the theapp variable. To do so, you need to declare theapp in any class where we are using it using the extern keyword. Although you have an Application object declared, you need to create the object using the runtime. To do so, use the CreateInstance method of the object. The method takes the programmatic identifier (ProgID) of the interface (for example, CrystalRuntime.Application). Working with the Report object The Application object is the root object in the RDC object model. By creating this object, we can access any of the other objects in the RDC. Two objects are mandatory when working with the RDC, the Application object and the Report object. Other objects may or may not be necessary when working with a particular.rpt file (for example, if you need to connect a report to its ODBC datasource, you would also need to use the Database object, DatabaseTables collection and DatabaseTable object). However, as a bare minimum, you need to instantiate at least an Application object and Report object, for example: theapp.papplication.createinstance("crystalruntime.applicat ion"); _bstr_t FileName("c:\\Reports\\myReport.rpt"); theapp.preport = theapp.papplication->openreport(filename); 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 3

4 Since the RDC runtime uses the IDispatch interface, method arguments need to be passed using Basic Strings (type BSTR) for strings, and as variants for every other data type. There will be more details on this in the next section. _bstr_t is a class that creates a BSTR by passing a string in quotations to the classes constructor. The back-slash is an escape character in Visual C++ so we need to double them up. The first slash indicates that the next is to be interpreted literally. The OpenReport method creates the Report object preport. The OpenReport method of the Application object takes the path to the.rpt file as a BSTR and returns an IReport object. VARIANT and BSTR BSTR When calling methods of the various objects and collections of the RDC, it is necessary to give the method arguments special treatment. String arguments can most easily be passed using BSTR. The _bstr_t class is a handy shortcut. When building a user-interface, CStrings are typically used to collect user input. Fortunately, the CString class has a method called AllocSysString() which turns the CStrings contents into a convenient BSTR. For example, to instantiate an Application and Report object using a file dialog prompting for a.rpt file, use the following lines of code: theapp.papplication.createinstance("crystalruntime.applicat ion"); //Create a FileDialog object using the MFC //CFileDialog class and display the FileDialog using //the DoModal() method. CFileDialog Dlg(TRUE); Dlg.DoModal(); _bstr_t FileName(Dlg.GetPathName().AllocSysString()); theapp.preport = theapp.papplication->openreport(filename); Create a BSTR using the _bstr_t class using the AllocSysString() method of the CString returned by the GetPathName() method of the FileDialog. If the nested construct is a little confusing, keep in mind that this is the same as using: Dlg.DoModal(); CString FilePath(Dlg.GetPathName()); _bstr_t FileName(FilePath.AllocSysString()); 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 4

5 With the BSTR containing the path to the.rpt file ready, the BSTR can now be passed to the OpenReport() method of the Application object. This creates a Report object that has all of the attributes of the.rpt file VARIANT For other argument data types, such as number, use a VARIANT. Whereas VARIANT is a data type in VB, in Visual C++ VARIANT is a union. There are always two members of the union that you need to set values to. When using the VARIANT union, the first member indicates the VariantType (.vt). The second member contains a value dependent upon the first member. For example, if you want a VARIANT to contain an Integer value of 3, use the following code: //Declare a Variant, var VARIANT var; //Initialize var using VariantInit, passing in the //address of the Variant. VariantInit(&var); //The first member,.vt, is set to VT_12, which is //the Variant Type for Short. var.vt = VT_I2; //The second member is set to ival (integer value) //to correspond to the first member. var.ival = 3; Table of Variant Types C++ Type VARIANT TYPE VARIANT MEMBER LONG VT_I4 lval BYTE VT_UI1 bval SHORT VT_I2 ival FLOAT VT_R4 fltval DOUBLE VT_R8 dblval BOOL VT_BOOL boolval CY (currency) VT_CY cyval DATE VT_DATE date IUnknown VT_UNKNOWN *punkval IDispatch VT_DISPATCH *pdispval SAFEARRAY VT_ARRAY *parray 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 5

6 Working with the Crystal Report Viewer Control The Crystal Reports Viewer Control (CRViewer) is an ActiveX control placed on a form to preview a report. If your application only prints or export reports, then the CRViewer is not needed in your C++ project. To add the Crystal Viewer to a project, open the Dialog resource for the class that is too be responsible for displaying the report. With the Dialog resource displayed, right-click on the dialog and choose "Insert ActiveX control " from the contextual-menu. A list of all of the registered controls will appear from which the Crystal Viewer Control should be chosen. This will place the Crystal Viewer control on the Dialog on which it should be resized as appropriate. The Crystal Viewer control has properties and methods that can be accessed using the following steps: 1. Go to the Class Wizard and, ensuring that your Dialog's class is selected in the Class Drop-down list, click on the Member Variables Tab. There will be a CRViewer object listed in the tabbed page. Double-click on this item and a prompt appears asking whether to add the CRViewer's class to the project, click OK then give the Crystal Viewer a meaningful name like m_viewer. 2. Go to the InitDialog() method of the Dialog's class. In order to preview a report, you must let the Crystal Viewer know which report to preview using the SetReportSource() method. m_viewer.setreportsource(theapp.preport); 3. Once the Crystal Viewer knows which report to preview, use the ViewReport() method to display the report in the Crystal Viewer control. m_viewer.viewreport(); Cleaning Up After the report has been previewed, there are some clean-up tasks that should be attended to. Assuming that clicking the OK button in your application dismisses the preview dialog and terminates the application, some housekeeping code should be added to the handler for the OK button. In this example, only an Application and Report object have been created. These objects should be released and destroyed in reverse order from which they were created. theapp.preport.release(); theapp.preport = NULL; 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 6

7 theapp.papplication.release(); theapp.papplication = NULL; Logging on to a Database There are two methods that can be used to connect a report to a database: LogonServer SetLogonInfo LogonServer When connecting a report to a database at runtime, if the logon information is the same, as used when designing the report, the LogOnServer method of the Application object should be used. To use the LogonServer method: 1. The LogOnServer method takes five BSTR arguments. Use the _bstr_t class to create BSTRs for the arguments. //The Server member should be set to the server name //if connecting directly (natively), if connecting //using ODBC, use the datasource (DSN) name instead. _bstr_t Server("TSVANFPS01"); _bstr_t Database("pubs"); _bstr_t UserID("vantech"); _bstr_t Password("vantech"); _bstr_t DLLName("p2ssql.dll"); NOTE To find the DLLname for a report, click Convert Database Driver from the Database menu in the Crystal Reports Designer. The DLLname is the value displayed beside the From field. The Server, Database, UserID, parameters for the LogonServer method can be found by clicking Set Location from the Database menu in the Crystal Report Designer. The dialog screen that appears will contain the members just mentioned. 2. Check if the LogonServer connection to the database has failed or succeeded by obtaining the return value with an HRESULT. Then, check the HRESULT value for SUCCEEDED (or, conversely, FAILED) and display a message box with a status message. For example: HRESULT hr = theapp.papplication->logonserver(dllname, Server, Database, UserID, Password); if (SUCCEEDED(hr)) AfxMessageBox("Connected Successfully"); 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 7

8 3. Once the connection succeeds, dispose of the BSTRs using the SysFreeString function. SysFreeString(Server); SysFreeString(Database); SysFreeString(UserID); SysFreeString(Password); SysFreeString(DLLName); SetLogonInfo The other method that can be used to connect a report to a database is the SetLogOnInfo method of the DatabaseTable object. This method does not establish a connection immediately, but rather provides the report with the information it needs to create a connection. SetLogoninfo functions on a table-by-table basis. If a report connects to multiple servers or databases, individual tables can be provided with the appropriate log on criteria. Additionally, SetLogonInfo propagates the log on criteria to other tables in the report with the same originating criteria (for example, if all tables in the report are pointing at the same datasource (DSN), database and userid, then using the SetLogOnInfo method of the first DatabaseTable object in the report is sufficient to connect to all of the tables in the report). To use the SetLogonInfo method: 1. The LogOnServer method takes four BSTR arguments. Use the _bstr_t class to create BSTRs for the arguments. NOTE Unlike LogOnServer, there is no need to pass the DLL name argument (the DLL is read from the report. //The Server member should be set to the server name //if connecting natively, if connecting via ODBC, use //the DSN name instead. _bstr_t Server("TSVANFPS01"); _bstr_t Database("pubs"); _bstr_t UserID("vantech"); _bstr_t Password("vantech"); NOTE The Server, Database, UserID, parameters for the LogonServer method can be found by clicking Set Location from the Database menu in the Crystal Report Designer. The dialog screen that appears will contain the members just mentioned. theapp.preport->database->tables->getitem(1)- >SetLogOnInfo(Server, Database, UserID, Password); 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 8

9 NOTE The last line of code above (used to access the first DatabaseTable object) is equivalent to the following lines of code: IDatabasePtr pdatabase; pdatabase = theapp.preport->getdatabase(); IDatabaseTablesPtr ptables; ptables = pdatabase->gettables(); IDatabaseTablePtr ptable; ptable = ptables->getitem(1); Passing An Active Data RecordSet to a Report If a report has been designed to report off of an Active Data Recordset (such as ADO, RDO, DAO or CDO), the SetDataSource method of the Database object is used. To pass an ADO Recordset to a report: 1. Import the ADO library and rename EOF as EndOfFile to avoid naming conflicts // reference the ADO object model and declare a //RecordSet and Connection object #import "msado15.dll" no_namespace rename("eof", "EndOfFile") _RecordsetPtr precordset = NULL; _ConnectionPtr pconnection = NULL; 2. Use the _bstr_t function to create a connection string // set up a connection string _bstr_t conn("provider=msdasql.1;persist Security Info=False;Data Source=Xtreme Sample Database"); 3. When uncertain of the ProgID of an object, use the uuidof() function to access it automatically. pconnection.createinstance( uuidof(connection)); 4. Open the connection using the connection string. pconnection->open(conn, "", "", NULL); ::SysFreeString(conn); 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 9

10 5. In the Open method of the Recordset, cast the Connection object as a VARIANT DISPATCH (for example, using _variant_t(idispatch *) ) since the method involves passing an object as an argument. The recommended cursor type is adopenkeyset just as adlockbatchoptimistic is the preferred Lock setting for the cursor when binding a recordset to a report. precordset.createinstance( uuidof(recordset)); precordset->open("customer", _variant_t((idispatch *)pconnection,true), adopenkeyset, adlockbatchoptimistic, 8); 6. When passing the Recordset argument in the SetDataSource method, be sure to cast the object as a VARIANT DISPATCH. theapp->preport->database->tables->getitem(1)->setdatasource (_variant_t((idispatch *)precordset,true)); Passing Parameter Values When reports have parameters, it is often desirable to handle parameter value assignment either in a custom dialog or programmatically. To pass a parameter value to a report, use the AddCurrentValue method of the ParameterFieldDefinition object. The following examples demonstrate how to pass a string parameter, a number parameter and a datetime parameter. Passing a String parameter Since the string value is being hard-coded, use an OLECHAR to hold the string value, convert the OLECHAR to a BSTR using the SysAllocString function. Create a VARIANT BSTR and assign the BSTR to the VARIANT. OLECHAR str[] = "a string parameter"; BSTR bstr; bstr = ::SysAllocString(str); VARIANT StringParam; VariantInit(&StringParam); StringParam.vt = VT_BSTR; StringParam.bstrVal = bstr; app->preport->parameterfields->item[1]->addcurrentvalue(stringparam); 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 10

11 Passing a Number parameter Since the number value is also being hard-coded, create a VARIANT of type VT_I2 (short) and assign the number to the VARIANT. VARIANT NumberParam; VariantInit(&NumberParam); NumberParam.vt = VT_I2; NumberParam.iVal = 10; app->preport->parameterfields->item[2]- >AddCurrentValue(NumberParam); Passing a DateTime parameter In the case of the date-time, m_date is a CTime object obtained from a DateTime picker control. VARIANT DateParam; VariantInit(&DateParam); DateParam.vt = VT_DATE; // Declare a SYSTEMTIME variable. SYSTEMTIME systime; // Use the GetAsSystemTime method of the Ctime // object. m_date.getassystemtime(systime); //Declare a DATE variable DATE vardt; // Convert the SYSTEMTIME into a DATE using the // SystemTimeToVariantTime function. SystemTimeToVariantTime(&sysTime, &vardt); DateParam.date = vardt; app->preport->parameterfields->item[3]->addcurrentvalue(dateparam); Opening A Subreport Sometimes it is necessary to open a subreport into its own Report object. For example, you may want to log on for each table in the subreport using the SetLogonInfo method. 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 11

12 In order to open the subreport, it is necessary to go through the Sections collection and then though the ReportObjects collection within each Section Object. To open a subreport: 1. Get the number of sections in the report in order iterate through each section searching for subreport objects. // Some objects we'll need later on... ISectionsPtr psections = NULL; ISectionPtr psection = NULL; IReportObjectsPtr prepobjects = NULL; IReportObjectPtr prepobject = NULL; ISubreportObjectPtr psubobject = NULL; IReportPtr psubreport = NULL; // Get the number of sections in the report psections = theapp.preport->getsections(); 2. Search through two separate collections (the collection of Section Objects and the collection of ReportObject objects). Set up a pair of nested loops using the Count property of the Sections collection and ReportObjects collection. // Loop through each section in the report for (long i = 1;i <= psections->getcount();i++) { // Create a variant to hold the value of i VARIANT var2; VariantInit(&var2); var2.vt = VT_I4; var2.lval = i; // Pass the value of i to get the i-th section psection = psections->getitem(var2); // Get the report objects collection from the section prepobjects = psection->getreportobjects(); // as long as there are report object... if (!prepobjects->getcount() == 0) { 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 12

13 //... loop through each for (long j = 1;j <= prepobjects->getcount(); j++) { // Create a variant to hold the value of j VARIANT var; VariantInit(&var); var.vt = VT_I4; var.lval = j; // Pass the value of j to the the j-th report // object prepobject = prepobjects->getitem(var); 3. Test each ReportObject's Kind property to see if it is a SubreportObject using the crsubreportobject enumerated type. // if the report object is a subreport if (prepobject->getkind() = crsubreportobject) { 4. Once a SubreportObject is identified, the ReportObject is assigned to the SubreportObject object. Then, the OpenSubreport() method of the SubreportObject is used to populate a Report object. // Re-assign the report object as a subreport object psubobject = prepobject; 5. The OpenSubreport() method of the SubreportObject object is used to populate a Report object with the attributes of the subreport. // Open the subreport psubreport = psubobject->opensubreport(); // To ensure that the subreport is really open // create a message box AfxMessageBox(pRepObject->GetName()); // You can now use the methods from the subreport's // report object } } } 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 13

14 Appendix A - The Interfaces of the RDC The following is a complete listing of the Interfaces exposed in version of Craxdrt.dll. For information on the methods and properties of these interfaces, please refer to the Developer's Help file (Developr.hlp) installed with Crystal Reports. These objects and collections are listed in the Developer s Help file index (minus the leading "I"). IApplication IArea IAreas IBlobFieldObject IBoxObject ICROleObject ICrossTableGroup ICrossTablGroups ICrossTabObject IDatabase IDatabaseFieldDefinition IDatabaseFieldDefinitions IDatabaseTable IDatabaseTables IExportOptions IFieldDefinition IFieldDefinitions IFieldMappingData IFieldObject IFormattingInfo 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 14

15 IFormulaFieldDefinition IFormulaFieldDefinitions IGraphObject IGroupNameFieldDefinition IGroupNameFieldDefinitions ILineObject IMapObject IObjectSummaryFieldDefinitions IOlapGridObject IPage IPageEngine IPageGenerator IPages IParameterFieldDefinition IParameterFieldDefinitions IPrintingStatus IReport IReportEvent IReportObject IReportObjects IRunningTotalFieldDefinitions IRunningTotalFieldDefintion ISection ISectionEvent ISections 6/24/2002 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 15

16 ISortFields ISpecialVarFieldDefinition ISQLExpressionFieldDefinition ISQLExpressionFieldDefinitions ISubreportLink ISubreportLinks ISubreportObject ISummaryFieldDefinition ITableLink ITableLinks ITextObject 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 3:52 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 16

Crystal Reports 8. Overview. Contents. Using Data Definition (TTX) files to pass an ADO recordset to a Crystal Report.

Crystal Reports 8. Overview. Contents. Using Data Definition (TTX) files to pass an ADO recordset to a Crystal Report. Crystal Reports 8 to pass an ADO recordset to a Crystal Report. Overview Contents This document provides information about using Data Definition (TTX) files and Active Data with Crystal Reports. This document