Guideline FAQ

If you like to enable the logging of i‑net Crystal-Clear then you need to set the value of the property log.engine to true (log.engine=true).
If you use i‑net Crystal-Clear as servlet or in an Application Server then you need to specify a log file to get the logging output. You can specify this log file in the property log.file, e.g.: log.file=C:/CrystalClear_Log.txt.
Also you can set different log levels (e.g. log.level=1) to configure the logging output:

You can change the values of these properties in the file: crystalclear.properties or with the Configuration Manager. The changes will take effect after the restart of the i‑net Crystal-Clear application or Servlet.

If you want to disable the logging then you need to set the value of the property log.engine to false (log.engine=false) and restart i‑net Crystal-Clear.

Please note: Please enable the logging of i‑net Crystal-Clear only if you need it to find a problem because i‑net Crystal-Clear will have a better performance without the logging.

Please refer to the i‑net Crystal-Clear documentation for more information.

The logging of the i‑net Crystal-Clear Java viewer is enabled by default. You can see the logging output in the Java console of the Java VM running the Java viewer. If you use the Sun Java plug-in as Java VM then you need to use the Java console of the Sun Java plug-in.

You can enable/disable the logging output of the Java viewer with:

1. the parameter “hasloggingenabled” in the report URL, e.g.: http://<servername>:9000?report=file:c:/Report1.rpt&hasloggingenabled=false
2. an applet parameter in your own page:

   <applet code="com.inet.viewer.ViewerApplet"
   	codebase="/client" id="ReportViewer" width="100%" height="95%">
   	<param name="HasGroupTree" value=false>
   	<param name="PromptOnRefresh" value=false>
   	<param name="HasExportButton" value=true>
   	<param name="HasRefreshButton" value=true>
   	<param name="HasPrintButton" value=true>
   	<param name="HasLoggingEnabled" value=false>
   	<param name="HasTextSearchControls" value=true>
   	<param name="ReportName" value="http://<servername>:9000/?report=file:C:/Report1.rpt">
   	<param name="Archive" value="../core/CC-Viewer.jar">
   </applet>

3. the method “checkHtmlPageProperties(…)” in the ReportServlet or server application.
   To do this you need to write a class that extends from com.inet.report.ReportServlet or from com.inet.report.Listener and that override the method “checkHtmlPageProperties(…)”:

   public void checkHtmlPageProperties(Properties props) {
   	props.put("hasloggingenabled", "false");
   }

   For more information please refer to the Java code samples that you can install using the i‑net Crystal-Clear setup that you can download from our website.

4. the API of the Java viewer: com.inet.viewer.SwingReportViewer.setLogStream(PrintStream)
   Please refer to the API documentation of the Java viewer for more information.

I-net Crystal-Clear can save the data of the report in CCcore files if it is necessary for the technical support team to execute your reports without the database.

It is strongly recommended to leave this off unless you are asked to switch it on by i‑net software's technical support, since it can be extremely performance-intensive.

You can enable the creation of CCcore files in the Configuration Manager:

• Enable the property “Log Database Data”.
• Specify path and prefix of the CCcore files in the property “Database Data Path”, e.g. “C:/CrystalClear/CCcore/CCcore”.

After you have saved the modified configuration, restart the execution of the report.
Now, i‑net Crystal-Clear will create CCcore<engine-id> - files<engine-id> in the specified directory during report execution. If it does not work, then restart i‑net Crystal-Clear and try it again.

You can use parameter fields (prompts) to send values from your Java application to a formula field used in the report.

At design time you add one or more parameter fields to the report. Thn you can use these parameter fields in your formula, e.g.:

if ({?numberPrompt} > 5) then
	… else
	… 

At runtime you can set the value(s) for the prompts either in the report URL:

 …&prompt0=5&prompt1=Date(2002,05,18)… 

or in the method checkProperties on the i‑net Crystal-Clear server side:

public void checkProperties(Properties reportProperties) {
	String currentReportName;
	currentReportName = ((String)reportProperties.get("report")).toLowerCase();
 
	// check report name
	if (currentReportName.indexOf("report1.rpt") != -1) {
		reportProperties.put("prompt0", "5")
		reportProperties.put("prompt1", "Date(2002,05,18)");
	}
}

I-net Crystal-Clear supports user defined formulas. For more information about user defined formulas please refer to the i‑net Crystal-Clear documentation.
You can install the documentation using the installer or you can read it online on our website.

You can set the codepage as follows:

java -classpath core/CrystalClear.jar -Dfile.encoding=Cp1252 com.inet.report.Listener

The list of encodings can be found on Sun's website.

Problem: The JDBC-ODBC bridge requires the default codepage.
Solution: Use a native JDBC driver instead of JDBC-ODBC bridge.

If you like to use TTF fonts in the Java viewer then you need to do the following:

1. You need to use a Java 2 compatible Java VM for the viewer (e.g. Sun Java PlugIn) because the JDK 1.1.x compatible JavaVMs only provide the following fonts: Arial, TimesNewRoman, SansSerif and Courier. All the other fonts will be mapped to these 4 fonts.
   
2. The used TTF fonts need to be installed on the client machine on that the viewer is running.
3. The value of the property “useNativeFonts” need to be true (see Configuration Manager).

Since i‑net Crystal-Clear version 3.1 the PDF export supports the embedding of TrueType Fonts into the created PDF files. The directory that contains the TTF files need to be specified in the i‑net Crystal-Clear Configuration Manager. It is not recommended to use the server font directory (e.g. C:/Winnt/fonts). Instead of this you should use a directory for the TTF files used with i‑net Crystal-Clear (e.g. “C:/CrystalClear/fonts” or ”/$HOME/Fonts/”). For the PDF export it is not necessary to install the TTF fonts on the client machine.

See: Which fonts are supported by i-net Crystal-Clear?

With the following code you can replace an image in the report design with another image while the engine is executing it:

Engine eng = new Engine();
eng.setReportFile( "file:c:/MyReport.rpt" );
Area pageHeaderArea = eng.getArea( "PH" ); // Page Header section
Section pageHeaderSection = pageHeaderArea.getSection( 0 );
 
Vector elements = pageHeaderSection.getElementsV(); //all elements in section
for (int i=0;i<elements.size();i++) {
	Element element = (Element)elements.elementAt(i);
	int x,y; 
	if (element instanceof com.inet.report.Picture) {
		// position of the old picture
		x = element.getX();
		y = element.getY();
		// remove old picture 
		pageHeaderSection.remove(element);
		// add new picture
		pageHeaderSection.addPicture(x, y, 3000, 700, "c:/newPicture.gif");
	}
}

You can find the complete sample “ChangePicture_at_Runtime.java” in the directory “samples/rdc” that is part of the i‑net Crystal-Clear documentation.

I-net Crystal-Clear supports report templates designed with the Crystal Reports Designer version 9 (or higher).

For more information please refer to the document ”Reading reports designed with Crystal Reports 9 (or higher)” in the i-net Crystal-Clear documentation.

If a report is requested with the same report URL as before then the engine will load the report from cache (if it is included in the cache) instead of re-executing it.

If the value of the property “ReloadOnNewRequest” is true (default: false) then the engine will execute the report for each report request.

Also it is possible to use a dummy parameter, e.g. with a random number as value, in the report URL.

If you send URL requests to i‑net Crystal-Clear, then these requests must conform to the URL specification (http://www.w3.org/Addressing/rfc1738.txt). The following URL examples are valid:

http://localhost:9000?report=file:c:/sample.rpt
http://localhost:8080/crystal/sample.rpt

In contrast, the following URL examples are not valid:

http://localhost:8000/CrystalClear/ReportServlet?/tmp/test.rpt

–> URL is invalid because /tmp/test.rpt is not a key/value pair

http://localhost:8000/CrystalClear/ReportServlet?report=file:/tmp/test.rpt&sf={table.field}=value

–> URL is invalid because the string ”{table.field}=value” must be URL encoded

http://localhost:8080/crystal/sample.rpt& report=file:d:/Test.rpt&dll=pdssql.dll

–> URL is invalid because the ? is missing

A most common error is that the parameters of a URL getline are not properly URL encoded. For example the example #2 above should be written as:

http://localhost:8000/CrystalClear/ReportServlet?report=file:/tmp/test.rpt&sf={table.field}%3Dvalue

Please see URLEncoding for more information.

If you have special characters in your request URL, for example:

http://localhost:9000/?report=1+2.rpt&...

then you must URL encode the parameter value (the string that starts after the = and ends at the next & or at the end of the line).

Please compile the following simple java program:

public class urlencode {
	public static void main(String s[]) {
		System.out.println("-->" + java.net.URLEncoder.encode(s[0]));
	}
}

And then run it as follows:

java urlencode ''1&2" -->1%262

For example if you have the following URL:

http://localhost:9000/?report=1+2.rpt&SF=if a = 3 then 4&prompt0=Date(2001,01,01)

then you need to URL encode the URL as follows:

http://localhost:9000/?report=1%2B2.rpt&SF=if+a+%3D+3+then+4&prompt0=Date%282001%2C01%2C01%29

You need to set the value of a date type in a parameter field (prompt) that is included in a Crystal Reports report (.rpt file) in the following format (report url):

...&prompt#=Date(YYYY,mm,dd)…,
e.g....&prompt#=Date(2000,04,18)...

The example above sets the April 18, 2000 in a prompt field.

On Windows XP / NT / 2000 / 2003 Server / Vista you can use the setup tool to install i‑net Crystal-Clear as Windows service.

Please note: If the service runs under the System account then it can not access the network, e.g. network printers or network drives.

If you need to increase the memory heap of the JVM executing the service (e.g. for large reports) or you need to set other JVM command line parameters then you can do this with the ccservice.exe (since version 1.0.4.0). To (re-) install the i‑net Crystal-Clear service with JVM command line parameter(s) you need to execute, e.g.:

• increase the JVM memory to 512 MB

  ccservice -i -Xmx512m

• command line parameter to disable ddraw, sometimes necessary to workaround a JVM bug

  ccservice -i -Dsun.java2d.noddraw=true 

• increase the JVM memory to 512 MB and have a -D parameter

  ccservice -i -Xmx512m -D… 

On Linux or Unix, you have to create two shell scripts which respond to the commands start and stop and the program Xvfb.

The first shell script must start (and kill) the program xvfb as follows:

xvfb :10 and should be linked to S80xvfb and K20xvfb.

The second one must start (and kill) i‑net Crystal-Clear as follows:

DISPLAY=:10 java -classpath /opt/CrystalClear-2.0 com.inet.report.Listener

and should be called S90crystalclear and K10crystalclear.

These two scripts should be copied to /etc/init.d and the links should be created in the sub-directory of the runlevel that should start i‑net Crystal-Clear. For example if you want to start i‑net Crystal-Clear in multi-user-mode, link the two scripts to runlevel 2 so that the directory /etc/init.d/rc2.d contains the 4 links mentioned above.

The API of the ReportServlet and the ReportSocket has three checkProperties call-backs that can be used:checkHtmlPageProperties(), checkProperties(Properties p, Object servletRequest) and checkProperties(Engine initializedEngine, Properties p, Object servletRequest).

The first one determines the look of the report viewer bean. Use this call-back when you want to switch off the Export and Print button in a servlet. However, in a JSP page the following code replaces the first checkProperties() call-back. Please note how HasExportButton is set according to the report name above:

<!-- The following code creates a HTML Page with a report viewer applet -->
<!-- embedded. The parameters you set here will be sent to the client and -->
<!-- are visible in your HTML browser. -->
<HTML>
	<HEAD><TITLE>i-net Crystal-Clear Java Viewer</TITLE></HEAD>
<BODY bgcolor="C6C6C6">
	<applet code="com.inet.viewer.ViewerApplet" codebase=
		<%=props.getProperty("http_server_port") + "/client" %>
		id="ReportViewer" width="100%" height="95%">
		<param name="ReportName" value=<%=props.getProperty("report") %> >
		<param name="HasGroupTree" value=false>
		<param name="ShowGroupTree" value=false>
		<param name="HasExportButton" value=
		<%=props.getProperty("report") == "MyReport" ? false : true %> >
		<param name="HasRefreshButton" value=false>
		<param name="HasPrintButton" value=true>
		<param name="Archive" value=
		<%=props.getProperty("http_server_port") + "/core/CC-Viewer.jar"%> >
	</applet>
</BODY>
</HTML>

The second call-back can be used to further modify the report parameter and to change prompt0, dll and other report parameters. It is run right before the report file is opened.

The third call-back should be used to change the values red from the report file. For example if the report design has a formula and you want to change the formula depending on whatever, you can examine the formula, change it and store it back into the report again.

After the third call-back is run, the engine executes the report and sends the data back to the client.

With the URL parameters archive. For example:

http://<servername>:9000/?report=...rpt&archive=http://localhost:81/crystalclear_V/CC-Viewer.jar

will create a HTML page which loads the viewer from the directory crystalclear_V from port 81 instead of the default location.

If you have a system without a graphical interface you cannot run the setup on this system directly. A solution is to use a system with a working X server to run the setup remotely. The X server has to be running on the local system and the ssh server has to be running on the remote system. Then you can connect to the remote system using “ssh -X <user>@<remote system>”. This will export the display to the system you're connecting from. After this, you can run the setup from the ssh console using the command “setup.sh” as you would locally.

You can ignore these FAQ if you use i‑net Crystal-Clear with JDK 1.4.x (or higher) and start the java virtual machine with the option -Djava.awt.headless=true. Please also read the FAQ: Support for Headless AWT (JDK 1.4) and IBM's RAWT. However, if you want to use the i‑net Crystal-Clear report viewer bean to print on the server-side then the following discussion matters because server-side AWT is incomplete and cannot handle printing.

On Unix the JVM which runs i‑net Crystal-Clear must have access to the display to handle Java AWT drawing requests (the drawing does not appear on the screen, but the display instance is required). Drawing is handled by a separate program called X11 and the JVM connects to the X11 program using sockets (or shared memory if available) by using the standard X11 network protocol. – One may argue that passing on drawing requests to a separate program just to obtain images is expensive, but this is the architecture of AWT and Swing.

You inform the process about the location of the display by setting an environment variable:

export DISPLAY=<hostname>:socketNumber-offset

On Unix an environment variable is inherited from the parent to the child processes. The very first process started by the kernel is called “init” (process ID 0). You must issue the command “export DISPLAY=:10” in one of the parent processes of the process that spawns i‑net Crystal-Clear but as a child of init. For example if you start apache as a service (assuming apache spawns the servlet engine in which i‑net Crystal-Clear runs), then you should add the above command to the service script (located in /etc/init.d) that starts apache. Of course you must start the display program “xvfb” (which is a dummy display without a screen) or X11 right before the apache service.

First, you should check if everything works fine:

• Log into your Unix machine using the graphical chooser screen and start an X11 terminal “xterm”.
• Within the xterm point the environment-variable “DISPLAY” to the running X11 server (e.g.: export DISPLAY=:0)
• Start the application server and all other programs needed from within the xterm.

After that you may add i‑net Crystal-Clear to the system init scripts so that i‑net Crystal-Clear will be started at boot-time. Assuming you have a standard SysV boot concept, create a start script that looks as follows:

…
# start the dummy X11 server listening on X11 port number offset 10
xvfb :10&
sleep 120
# start the application server
export DISPLAY=:10
/opt/weblogic/weblogic.sh start
…

You can find xvfb on the Solaris installation CD or, if you're running Linux, download the RPM from your Linux vendor.

If you use the Oracle Application Server (OC4J) then you need to set the DISPLAY in its xml setting file: opmn.xml.

For more details, see: UIX Developer's Guide.

For more details please refer to:

• SUN java FAQ
• Solaris Technical Articles & Tips. UIX Developer's Guide
• Install the software for the XFVB on various versions of AIX

During rendering it is not possible to access the total number of pages that the report will have. If you want to use a formula that print the number of pages in the report, then do the following:

1. Add a the following code to your checkProperties(Engine engine) call-back static public Object copyObj( Object obj ) throws Exception {
   ByteArrayOutputStream baos = new ByteArrayOutputStream( 1024 );
   ObjectOutputStream oos = new ObjectOutputStream( baos );
   oos.writeObject( obj );
   return new java.io.ObjectInputStream(new java.io.ByteArrayInputStream(baos.toByteArray())).readObject();
   }
   public void checkProperties (Engine engine, Properties prop, Object req) throws ReportException{
   Engine e = copyObj(engine);
   e.execute();
   engine.setPrompt(“TotalPageCount”, String.valueOf(e.getPageCount());
   }
2. Add a Prompt called “TotalPageCount” to your report design and then use the TotalPageCount prompt in your formula.

Please use isNull to suppress a null value. From the Crystal Reports documentation:

If IsNull({Product.Color}) Or InStr({Product.Color}, " ") = 0 Then
	formula = "basic"
Else
	formula = "fancy"
End If

Yes, at runtime you can pass the values for the report parameters like parameter fields (prompts), selection formula (sf), stored procedure parameter (sproc) and … to the report engine.

You can set the values for the report parameters:

1. in the report url on the client, like: …&prompt0=1&prompt1=USA… or …&sf=columnID=25… or
2. in the servlet or Java application on the serverside. See the sample files “MyListener_withMyReportProperties.java” and “MyReportServlet_withMyReportProperties.java”.

Also, with i‑net Crystal-Clear it is possible to use another database connection or another database driver at runtime than used at report definition (design time). For example, you can create a report based on the Oracle Server and at runtime you can use this report with the Oracle Server and/or with the MS SQL Server (or another database that can be accessed by JDBC or ODBC).

For more information about the URL parameters please refer to the i‑net Crystal-Clear documentation. You can install it using the setup (download) or you can read it online.

If you like to use query files with your reports then you need to store the query files (.qry) in the same directory as the report templates (.rpt). This differs from Crystal Reports; there it isn't possible to move the query file and the report definition file into another directory structure.

If the paper size of a page printed with i‑net Crystal-Clear is not the paper size that you have selected at design time in the Crystal Reports Designer then please note the following:

1. If the checkbox “No Printer” is selected in the “Printer Setup” dialog of the Crystal Reports Designer then the default values for the paper size and paper orientation will be used. This default values are saved in the file crystalclear.properties.
2. If the checkbox “No Printer” is not selected and the checkbox “Default Properties” is selected in the “Printer Setup” dialog of the Crystal Reports Designer then the default value for the paper size will be used. This default value is saved in the file crystalclear.properties.
3. If you haven't set the paper size and paper orientation via the RDC API of i‑net Crystal-Clear then the either the default properties from the crystalclear.properties or the paper size from the report design will be used, depending on the “No Printer” and “Default Properties” settings above.

To make i‑net Crystal-Clear use the paper size stored in the report file, please uncheck “No Printer”, “Default Properties” or set the paper size/paper orientation via the RDC API.

In any case, please note that if the JavaClient uses the java printing API (java.awt.PrinterJob), then it will scale up or down to the actual paper size. So you can print a A3 report onto a A4 sheet of paper. On certain operating systems which either do not have a printing API (or where the printing API is not supported by your java implementation), only a fixed set of paper sizes are available. To check if a paper size is available please go to the java viewer's page setup dialog (which is available in jdk>=1.2).

You can use the method checkProperties on the i‑net Crystal-Clear server side to set values for parameters that should not be passed from client to server via the report url. To do this you need to write a class that extends from com.inet.report.Listener (standalone or server application) or com.inet.report.ReportServlet (servlet) and in this class you need to override the method checkProperties (…). The parameter “properties” contains all parameters specified in the report url.

For more information about this method please refer to the API documentation of the ReportServlet and/or the Listener and see the sample files listenerwithmyreportproperties.java and reportservletwithmyhtmlproperties.java.

You can use the method engine.getSql to get the SQL statement in the following two cases:

1. The SQL statement was set with the method engine.setSql
2. the report is designed on a .qry file in that the SQL statement was entered directly.

It is not possible to get the SQL statement of a report that is designed e.g. on a SQL Server database with an native JDBC driver or with ODBC.

First of all, if the ServerName is set incorrectly in your environment, this is probably a bug in your servlet engine. Probably your /etc/localhost has an incorrect entry pointing to localhost instead of the real host name.

Anyhow, if your servlet engine initializes serverName with an incorrect value, you can change it yourself. You can either use the checkHtmlPageProperties or set the correct property in the afterPropertiesStoredHook(). The relevant variables that must be changed are:

• http_server (only available in PHP, ASP and Standalone Listener)
• http_server_port (only available in PHP, ASP and Standalone Listener)

Please set the above property to the apropriate value in the “afterPropertiesStoredHook()” – don't forget to call “super.afterPropertiesStoredHook” after you've run your code:

void afterPropertiesStoredHook (HttpServletRequest req,
				HttpServletResponse res, Properties props)
				throws ServletException, IOException {
	props.put("http_server_port", "http://test:8888");
	super.afterPropertiesStoredHook(…);
}

If you send a report name such as ”/tmp/test.rpt” to the server (for example via http://...&report=/tmp/test.rpt&…), then we will look for it in the servlet context by calling

r=req.getServletPath();
getServletConfig().getServletContext().getResource®

If you're unfamiliar with the servlet/CGI variables, here's an example:

• Example-Path: http://localhost:8080/crystal/foo/ReportServlet?a=1
• ContextPath: /crystal
• PathInfo: null
• QueryString: a=1
• RequestUri: /crystal/foo/ReportServlet
• ServletPath: /foo/ReportServlet

In the above example the test.rpt will be looked up in …:foo/tmp/test.rpt. The servlet engine will typically return an URL which could be used to retrieve the resource without bothering the servlet engine again. For example the tomcat servlet engine will return jndi://...:foo/tmp/test.rpt.

Physically the foo/temp/test.rpt must be located in the servlet engine's webapps folder. For example if the tomcat servlet engine is installed in c:/, then the foo servlet context is located in: “c:/tomcat4/webapps/foo/temp/test.rpt”.

Crystal Reports prompts can only contain constants such as “test”, “1” etc. but i‑net Crystal-Clear prompts can also contain constant formula expressions such as Date(2003,01,01).

This means that String values which were entered in the URL line or in the prompt dialog box must be quoted, for example [red,green,3] must be written as ['red','green','3'].

Since i‑net Crystal-Clear version 5.3, all formulas are evaluated “before reading records”, unless the formula references a dynamic field (such as a database field, or another formula field which is evaluated later than “before reading”), or unless the formula includes the command “whilereadingrecords” or “whileprintingrecords”. To make sure your formula is evaluated at the right time, you can use one of those two commands to cause a formula to be evaluated later. Also, you can use the command “evaluateAfter(f)” to make sure the formula is evaluated directly after a different formula f.

“Before Reading Records” means that the formula is evaluated only once, at the beginning of the execution of the report. During execution of the report, the result value is then given directly (not calculated) to all places where it is used in the report.

Manually setting this evaluation time with the command BeforeReadingRecords is possible, but unnecessary because i‑net Crystal-Clear? will either use this evaluation time anyways, or will give you an error message, because it is not allowed to manually set BeforeReadingRecords if it is not possible (for example you could not specify “BeforeReadingRecords” if your formula contains a database field, since in order to evaluate the formula's result, it would have to read the field's record).

“While Reading Records” means the formula is evaluated once for each record, while the records are being read, but before they are “printed” into the report.

Manually setting WhileReadingRecords is allowed for any formula which does not need to have read all records before being able to be evaluated. Therefore, WhileReadingRecords is not allowed for formulas which summarize all database fields, or which use a special function like TotalPages.

“While Printing Records” means the formula is evaluated once for each record in the report.

Manually setting WhilePrintingRecords is allowed for any formula.

global numbervar x; x:=x + 1;
// this formula is evaluated only once and sets adds 1 to x 
// any time this formula is needed, it will return 1.

whilereadingrecords;
global numbervar x; x:= x+1
// For every record read for the report which calls this formula, x is incremented by 1.
// This will return 1 for the first record, 2 for the second, and so forth.

whileprintingrecords;
global numbervar x; x := x + 1
// For every record printed in the report which calls this formula, x is incremented by 1.
// This will return 1 for the first record, 2 for the second, and so forth - however,
// if a record is not printed into the report, this formula will not be evaluated.

Since version 6.0 it is possible to increase the memory for i‑net Crystal-Clear if running as NT-service. You have to:

• open a command line tool
• go to the installation folder of i‑net Crystal-Clear
• call “ccservice.exe -u” (this will uninstall the service)
• call “ccservice -i -Xmx512M” (where 512M stands for 512MB maximum memory)

For getting information about how to increase the memory for the NT-service of previous version of i‑net Crystal-Clear 6.0 please contact CrystalClear@inetsoftware.de