Programming Tips

The following topics are discussed in this section.

Always Set ReportName First, Page 209

Discard Saved Data, Page 210

Verify Database, Page 210

Connecting to SQL Servers, Page 210

Changing Tables & Formulas, Page 211

Changing Groups & Summary fields, Page 211

Using the Send methods, Page 211

Using the JobNumber property, Page 212

Always Set ReportName First

When writing code to run a report using the VCL component, be sure to set the ReportName property first. The reason for this is that the VCL monitors any changes to ReportName, and when it is changed, it clears out any subreport information as well as the following properties for the main report:

AreaFormat	Margins
AreaFormatFormulas	ParamFields
Connect	PrintDate
DetailCopies	ReportTitle
Formulas	SectionFont
GraphData	SectionFormat
GraphOptions	SectionFormatFormulas
GraphText	Selection
GraphType	SectionMinHeight
GroupCondition	SessionInfo
GroupOptions	SortFields
GroupSelection	SQLQuery
GroupSortFields	SQL.Params
LogOnInfo	Tables

Therefore, if any of these properties have been set before ReportName, they will be cleared when the ReportName property is assigned a new value.

Seagate Crystal Visual Component Library

209

Discard Saved Data

Beware of saving Reports from the Seagate Crystal Report Designer with the Saved Data toggle on (this option is located on the Report Options dialog box from the File menu), unless you want them that way. When they are run from Delphi, if you don't set the DiscardSavedData property to True, the report will run from the Saved Data (which is the default mode), and will not show the changes that have been made to the database.

After a report has been run via the VCL once, and the Print Job has not been closed (either via the CloseJob method or changing the ReportName property), the report that is currently in memory now has Saved Data. If you run it again, it will run with the Saved Data from the first run. This means that some of the changes you pass in the second time, may not have any effect. The solution is to set the DiscardSavedData property to True.

Verify Database

Under the Database menu in Seagate Crystal Report Designer, there are two menu items: Verify Database and Verify on Every Print. Since the database structure and index information are stored in a report file when it is saved, the report may have problems running if the database structure changes.

One solution is to load the report into the Designer, and choose Verify Database, then resave the report. This works fine during development, but if the database structure will be changing during runtime operation, there is no equivalent for these Verify commands in the runtime engine. Therefore, Verify on Every Print should be turned on in these instances. With this option on, the report will reread the database structure every time the report runs. The amount of time taken to do this extra step is usually minimal. If the database structure will not change after deployment, there is no reason to turn this feature on.

Connecting to SQL Servers

With this Component, you have three different ways of establishing a connection to an SQL DataSource or Server: LogOnServer, LogOnInfo, and Connect. We recommend you review these sections in the Help file to determine which method suits your needs best.

One thing to keep in mind when connecting to SQL databases, is that if the database is being accessed via ODBC drivers in the report, then the ServerName property of the above-mentioned methods represents the ODBC DataSource Name, not the actual Server Name. On the other hand, if the database is being accessed via Crystal's native SQL drivers, then the ServerName property of the LogOnServer, LogOnInfo, and Connect objects represents the actual SQL Server name.

Another thing to watch for is that some table locations are stored in a report as <db name>.<owner>.<table name>. Attempting to change the ServerName for such a report at runtime could cause it to look for the tables on the original Server instead of the new one, which usually results in a connection error. The solution is to remove the <db name> and <owner> prefixes so that just the table name is listed. This can be done in the report (Set Location dialog box in Crystal Reports), or via the Component’s Tables object.

Seagate Crystal Visual Component Library

210

Changing Tables & Formulas

When changing the table names that a report is based on, it is important to remember that formula fields will use the report's alias name for the table, and not the new table name.

For example, suppose you have a report which uses the Company1 table. When you added Company1 to the report, an Alias was created for it by Seagate Crystal Reports called Company1. When the field is used in a Formula, it appears like this:

(* company1.Field *)

However, company1 represents the alias and not the actual table name. So, in the Delphi program, when you change the table name from company1 to company2, the formula still sees the field as (* company1.Field *), and not (* company2.Field *), since the alias Seagate Crystal Reports assigned remains the same. One thing to remember in this respect is that Seagate Crystal Reports’ aliases can only be changed in the designer, not at runtime.

Changing Groups & Summary fields

When changing Grouping fields at runtime via the GroupCondition or GroupOptions object, remember that any inserted summary fields, or formulas containing summary fields in the report may cause errors, since they contain the grouping field name as the second element of their parameters. For example, take the following Summary field:

Sum((* company.SALES *), (* company.STATE *))

This formula sums the amount of company sales per State. This summary field assumes that (* company.STATE *) is one of the grouping fields. If the grouping field is changed from (* company.STATE *) to (* company.COUNTRY *), this formula field will generate an error.

The way to avoid this problem is to insert the grouping field into a formula field when designing the report. Then when you create the group, base it on the formula field. Any summary fields inserted will also look at the formula field as the grouping field, regardless of what it contains. Then to change the group field at runtime, simply pass a new (* table.field *) value to the formula field. All the summaries will automatically change.

Using the Send methods

Since the VCL's Execute method uses the Send methods from the VCL's sub-class objects, there is usually no need to call these methods in code. However, there are at least two cases where this can be advantageous:

1.For changing the order in which items get sent to the Print Engine. For example, the Execute method of the VCL sends the Formulas first, and then the Grouping information. If GroupOptions.Send is called just before Execute, this has the effect of sending in the Grouping information before the Formulas.

2.For testing the VCL and/or the Print Engine. Properties can be set and then passed from the VCL to the Print Engine by calling the Send method. Then the values can be retrieved using the Retrieve method and examined to make sure they are getting passed correctly.

Seagate Crystal Visual Component Library

211