Designing reports that use the native XML driver
Native XML driver overview
Note: At this time, the native XML driver is supported only in English, French, German, and Japanese. Please check for information about other languages on the Developer Zone at http://www.businessobjects.com/ipl/default.asp?destination=devzone&language=EN
The native XML driver for Crystal products reads an XML stream and parses its contents based on the corresponding schema (XSD) to derive a hierarchical table representation of the data. Crystal Reports then uses this hierarchical table representation when you create a report.
Note: When Crystal Reports consumes the XML itself, the hierarchical table representation is mapped directly back to the XML based on an internal query definition. The XML is never deconstructed into a relational table model.
You must specify a schema or Document Type Definition (DTD) for the XML driver to use while parsing the XML stream. The driver uses this schema or DTD to determine how XML data types will be converted to Crystal data types. For more information about schemas and how data types are converted, see Schema.
For more information about the native XML driver, visit the Developer Zone at:
http://www.businessobjects.com/ipl/default.asp?destination=devzone&language=EN
You'll find samples and other information at this site. For a general overview of XML, see the Crystal Reports User's Guide.
Getting started
Before you can use the native XML driver in Crystal Reports, you need to configure the CRDB_JavaServer.ini
file. See CRDB_JavaServer.ini parameter reference for a complete list of parameters and their descriptions. The main parameters that you must configure are Path, Classpath, and IORFileLocation.
Note:
- This task may include setting an environment variable for your Java directory if you do not want to include the path information in the
CRDB_JavaServer.ini
file. In this case, create a JAVA_HOME environment variable that points to the location of your JDK. - For an installation in any language, you must verify the path information in the
CRDB_JavaServer.ini
file. The path information must correctly match the actual location of the files CRDBXMLExternal.jar
and CRDBJavaServer.jar
. The sample file uses English folder names in the path and may need to be modified to match the localized folder names used on your machine.
XML data source access types
When you create a new connection in Crystal Reports by selecting the XML driver, you can choose from several possible data source types. This section describes each type. For the steps you need to complete when connecting, see Connecting to an XML data source.
Local data source
A local data source is an XML file that you have on a local machine or a network drive that you can connect to by entering a path and file name. The XML driver lets you type a full path and file name, or you can select a file by searching for it in the Open dialog box. If you have a schema (XSD) for your XML file, you can specify it. For more information about schemas and how they are used, see Schema.
HTTP(S) data source
An HTTP(S) data source is an XML file or XML stream that you can access from a Servlet, an ASP page, a JSP page, or another type of dynamically created web page. The URL you provide to such a data source can be either HTTP or HTTPS. When using HTTPS, user IDs and passwords that you enter in Crystal Reports or Crystal Enterprise are used to authenticate against the underlying HTTP provider.
The XML driver lets you type a URL and later add authentication credentials. If you have a schema (XSD) for your XML file or stream, you can specify it and its authentication credentials. For more information about schemas and how they are used, see Schema.
HTTP(S) data sources also support HTTP Parameters. For more information, see HTTP Parameters.
Web Service data source
A Web Service data source can be a service that you have on a local machine or a network drive that you can connect to by entering a path and file name, or it can be a service that you access from a Servlet or a dynamically created web page. The URL you provide to such a source can be either HTTP or HTTPS. The schema for the response XML file is derived through the Web Services framework rather than being specified manually.
Web Service data sources are accessed through WSDL (Web Services Description Language), which is the standard format for describing a web service. After you specify a WSDL, the driver lets you select which Service, Port, and Method you want to use.
Schema
When you use the XML driver, you can specify a schema (XSD) or Document Type Definition (DTD) of your choice, or you can use schema information embedded in the XML document. The schema is used to determine how to present the XML data within Crystal Reports.
Note: When you specify a schema to use with your XML file, the specified schema is used instead of schema information embedded in or referenced by the XML file itself.
The following table shows how the native XML driver maps XML data types to Crystal data types.
XML type | Crystal type |
---|
string | String |
Boolean | Boolean |
Decimal | Number |
float | Number |
Double | Number |
duration | String (Duration:duration) |
dateTime | DateTime |
time | time |
date | Date |
gYearMonth | Date (First day of month) |
gYear | Date (First day of year) |
gMonthDay | Date (Within current year) |
gDay | Date (Within current month/year) |
gMonth | Date (Within current yearfirst day) |
hexBinary | BLOB |
base64Binary | BLOB |
anyURI | String |
QName | String |
NOTATION | String (Notation:notation) |
normalizedString | String |
token | String |
language | String |
NMTOKEN | String |
NMTOKENS | String |
Name | String |
NCName | String |
ID | String |
IDREF | String |
IDREFS | String |
ENTITY | String |
ENTITIES | String |
Integer | Number |
nonPositiveInteger | Number |
negativeInteger | Number |
long | Number |
int | Number |
short | Number |
byte | Number |
nonNegativeInteger | Number |
unsignedLong | Number |
unsignedInt | Number |
unsignedShort | Number |
unsignedByte | Number |
positiveInteger | Number |
anySimpleType | String |
Note: Names are case sensitive.
The XML driver deals with XML attributes, namespaces, specific data types, and tags as described in the following table.
XML | Resolved by the driver |
---|
Attributes | Attributes are included in the column name prefixed by the @ symbol (for example, tag <a attrib= "valueofattrib "> becomes field A@attrib ). |
Namespaces | Namespaces are included in the column name (for example, tag <abc:name> becomes field abc:name ). |
Complex data types | Complex type elements resolve into tables within Crystal Reports, whether or not they have repeating elements. An exception is where a complex type contains only a single simple type element; in this case, the element is returned as a long string containing a <CR>-separated list of the values of the elements. |
List data types | List data types always resolved as String types. The string will contain the list. |
Union data types | Union data types return a String containing the contents of the Union. |
Mixed data types | Data types that are defined as Mixed are returned as an XML fragment that contains the entire contents of the tag (including the element's own tag) as a MEMO field. |
Types defined with processContents= "skip " attribute | Types that are defined with the attribute processContents= "skip " are returned as an XML fragment that contains the entire contents of the tag (including the element's own tag) as a MEMO field. |
Types defined with processContents="lax" attribute | Types that are defined with the attribute processContents="lax" are resolved through the schema; if resolution is not possible, the data is returned as an XML fragment that contains the entire contents of the tag (including the element's own tag) as a MEMO field. |
Choice tags | Where Choice tags are used, the union of all combinations is offered along with an enumerated choice field that indicates the path chosen. |
Tags containing no actual value | When a tag is a simple type and contains no actual value, a NULL value is returned. NULL is accepted for all data types. |
Where it is not possible to determine the outermost (root) element of the schema from the XSD or DTD, all possible roots are displayed and you must select the root as part of your data connection.
HTTP Parameters
When you select an HTTP(S) data source, you can also define HTTP Parameters to pass to the underlying servlet or dynamically created web page. These parameters provide the servlet or web page with information for returning the correct XML stream. Parameters are passed to the underlying connection as Form variables. The Form variable name corresponds to the Crystal parameter name (for example, the Crystal {?REGION} parameter equals the Form variable 'REGION').
All parameters that are passed with multiple values selected submit multiple Form variables with the same name. For example, consider the following example:
<p>What flavor has the largest sales?
<input type=checkbox name=flavor value=vanilla>Vanilla<br>
<input type=checkbox name=flavor value=strawberry>Strawberry<br>
<input type=checkbox name=flavor value=chocolate checked>Chocolate<br>
If you select both Chocolate and Vanilla, two form variables named flavor are submitted, each with a value of Vanilla and Chocolate respectively, as in "http://server/servlet?flavor=Vanilla&flavor=Chocolate"
in GET format. Respectively, {?flavor}
with both Vanilla and Chocolate selected through Crystal Reports will create the same URL request.
Creating HTTP Parameters in the XML driver
- On the HTTP Parameters screen, click Add Property.
- On the Edit Property Value screen, enter a name for your parameter in the Property field.
- Enter a parameter formula in the form of a @Prompt function in the Value field.
Parameter formulas
Parameter formulas are created by using the @Prompt function. This function is useful when you want to force a restriction in the XML stream but you do not want to preset the value of the condition.
The syntax of the function is as follows:
@Prompt('message','type',[lov],[MONO|MULTI],[FREE|CONSTRAINED])
Syntax | Description |
---|
'message' | This parameter is the text of the prompting message. The text must be enclosed between single quotation marks; for example, 'Choose a Region', 'Pick a time period', or 'Choose a showroom'. The text appears in the prompt box when the connection is completed. |
'type' | This parameter describes the data type returned by the function. It can be one of the following: - 'A' for alphanumeric
- 'N' for number
- 'D' for date
The specified data type must be enclosed in single quotation marks. |
lov | This parameter provides a list of values (lov). The list is hard-coded; that is, you create it by entering the separate values. Each value is enclosed in single quotation marks and is separated by a comma. The whole list is enclosed in brace brackets. For example, {'Australia', 'France', 'Japan', 'United Kingdom', 'USA'} . This parameter is optional. |
MONO | Users can select only one value from the list of values. MONO is the default of the MONO|MULTI pair. This parameter is optional. |
MULTI | Users can select multiple values from the list of values. MONO is the default of the MONO|MULTI pair. This parameter is optional. |
FREE | Users can enter a value of their choice, or they can select a value from the list of values. FREE is the default of the FREE|CONSTRAINED pair. This parameter is optional. |
CONSTRAINED | Users must select a value from the list of values. FREE is the default of the FREE|CONSTRAINED pair. This parameter is optional. |
Note: For each of the optional parameters, if you omit an argument, you must still enter the commas as separators.
Connecting to an XML data source
To choose XML as your data source
- In Crystal Reports, on the File menu, click New.
- Click Using the Report Wizard.
- In the Choose a Wizard list, click Standard; then click OK.
- On the Report Creation Wizard's Data screen, double-click Create New Connection.
- Double-click XML.
The XML dialog box appears.
- Choose an XML data source access type:
- Local data source
For more information about this type of data source access, see Local data source.
- HTTP(S) data source
For more information about this type of data source access, see HTTP(S) data source.
- Web Service data source
For more information about this type of data source access, see Web Service data source.
- Identify the XML file you want to connect to by following the steps in one of these sections:
To connect to a local data source
- If you choose Use Local Data Source, enter the full path and name of your XML file, or use the button adjacent to the field to search for your file.
- Choose Specify Schema File if you want to apply a schema to the XML file you selected.
You must select this option and specify a schema unless the XML file contains embedded schema information.
Note: Defining the location and name of you schema is done on the next screen.
- Click Next.
Depending on your selection in the previous step, you will see either a screen for specifying your schema, or you can click the Finish button.
- To specify a schema file, choose either Use Local Schema or Use HTTP(S) Schema and complete the adjoining field.
- For Use Local Schema, enter the full path and name of your schema file (XSD), or use the button adjacent to the field to search for it.
- For Use HTTP(S) Schema, enter the URL that points to your schema file (XSD).
- Click Next, and then click Finish.
To connect to an HTTP(S) data source
- If you choose Use HTTP(S) Data Source, enter the URL that points to your XML file.
You can use HTTP or HTTPS to define your URL.
- Choose Specify Schema File if you want to apply a schema to the XML file you selected.
You must select this option and specify a schema unless the XML file contains embedded schema information.
Note: Defining the location and name of your schema is done on a subsequent screen.
- Click Next.
- Enter authentication information if it is needed, and then click Next again.
Depending on your selection in step 2, you will see either a screen for specifying your schema, or a screen for defining HTTP Parameters. If you see the HTTP Parameters screen, skip to step 6.
- To specify a schema file, choose either Use Local Schema or Use HTTP(S) Schema and complete the adjoining field.
- For Use Local Schema, enter the full path and name of your schema file (XSD), or use the button adjacent to the field to search for it.
- For Use HTTP(S) Schema, enter the URL that points to your schema file (XSD).
- On the HTTP Parameters screen, create parameters that can be added to your URL to limit the results that are returned in your XML file.
- Click Add Property to define a new value. The Edit Property Value dialog box appears. Use this dialog box to define a parameter name and a formula. For more information about defining parameters, see Creating HTTP Parameters in the XML driver.
- Click Edit Value to change an existing parameter. Select the parameter you want to edit before you click this button.
- Click Remove Property to delete an existing parameter. Select the parameter you want to remove before you click this button.
- Click Finish when you are done with the HTTP Parameters screen.
To connect to a Web Service data source
- If you choose Use Web Service Data Source, click Next to continue.
- To specify a web services file location, choose either Use Local WSDL or Use HTTP(S) WSDL and complete the adjoining field.
- For Use Local WSDL, enter the full path and name of your web services file, or use the button adjacent to the field to search for it.
- For Use HTTP(S) WSDL, enter the URL that points to your web services file.
- Click Next.
Depending on your selection in the previous step, you will see either a screen for specifying your web service, ports, and methods, or a screen for defining authentication for your web service URL. If you see the web service, ports, and methods screen, skip to step 5.
- Enter authentication information if it is needed, and then click Next.
- On the Web Service, Port and Method screen, choose a service, a port, and a method from the lists.
- Click Finish.
Once you can see the table created from your XML data source, you can use it to create a Crystal report in the same way you'd use any other data source. For more information about creating Crystal reports, see the Crystal Reports User's Guide.
CRDB_JavaServer.ini parameter reference
The parameters that appear in CRDB_JavaServer.ini
depend on the drivers you install. For example, if you do not install the native XML driver, the [CRDB_XML]
parameters do not appear. Optimally, the CRDB_JavaServer.ini
file contains these parameters:
Parameter Name | Description |
---|
Path | The Path parameter value contains the directory of your Java executable. If you have multiple versions of the Java Runtime Environment installed, this parameter points to the version that you want to use; for example: PATH=C:\apps\j2sdk1.4.2\bin
Alternatively, the path information may be configured as a user or system environment variable. In this case, if JAVA_HOME is defined as a variable, you can use ${JAVA_HOME} as in this example: PATH=${JAVA_HOME}\bin
|
Classpath | The Classpath parameter value contains a list of the classpaths to the following .jar files: Alternatively, the classpath information may be configured as a user or system environment variable. If this variable is not defined, it is equivalent to CLASSPATH=${CLASSPATH} . Environment variables can also be included in a mixed path, as shown in this example: classpath=c:\java\lib\xerces.jar;${CommonProgramFiles}"/Crystal Decisions/2.5/bin/CRDBJavaServer.jar";${CLASSPATH} Note: When using classpaths with long folder and/or file names that contain spaces, ensure that they are enclosed within quotation marks. For example, "C:\Program Files\Common Files\Crystal Decisions\2.5\bin\CRDBJavaServer.jar" . |
IORFileLocation | The IORFileLocation parameter value provides a temporary directory for use by the JDBC driver. This location must exist and be accessible by the system; otherwise, the driver will fail to work. |
JavaServerTimeout | The JavaServerTimeout parameter specifies the maximum amount of time your Java server will continue processing your request until it shuts itself down. The default value is 1800 seconds (30 minutes). |
JVMMaxHeap | The JVMMaxHeap parameter specifies the maximum amount of heap space that the JVM can allocate for running the Java server. This parameter is set to 64 MB of heap by default. Change this number to a higher value if you need to process a large amount of data. |
JVMMinHeap | The JVMMinHeap parameter specifies the minimum amount of heap space that the JVM can allocate for running the Java server. This parameter is set to 32 MB of heap by default. |
CacheRowSetSize | The CacheRowSetSize parameter specifies the number of rows to cache in memory. This parameter is set to 100 rows by default. |
JDBCURL | The JDBCURL parameter value is the default JDBC connection URL that will be displayed in Crystal Reports when you create a new JDBC data connection. The exact format of the connection URL is specific to the database driver and is provided by the database driver vendor. For example, the connection URL for the Oracle JDBC driver is: jdbc:oracle:thin:@<hostname>:<port>:<sid>
Where: <hostname> is the TCP/IP address or TCP/IP host name of the server to which you are connecting.<port> is the number of the TCP/IP port.<sid> is the Oracle database ID.
|
JNDIURL | The JNDIURL parameter value is the default JNDI connection URL that will be displayed in Crystal Reports when you create a new JNDI data connection. The exact format of the connection URL is specific to the database driver and is provided by the database driver vendor. |
JDBCUserName | The JDBCUserName is the default user ID that will be displayed in Crystal Reports when creating a new JDBC data connection. The JDBC driver uses the user ID to connect to the database. |
JDBCDriverName | The JDBCDriverName is the default full classname of the JDBC driver that will be displayed in Crystal Reports when creating a new JDBC data connection. For example, the full classname of the Oracle JDBC driver is: oracle.jdbc.driver.OracleDriver
|
JNDIUserName | The JNDIUserName is the default user ID that will be displayed in Crystal Reports when creating a new JNDI data connection. The JDBC driver uses the user ID to connect to the database. |
JNDIConnectionFactory | The JNDIConnectionFactory parameter is the name of the connection factory of the JNDI server. For WebLogic, it is weblogic.jndi.WLInitialContextFactory . For WebSphere, it is com.ibm.websphere.naming.WsnInitialContextFactory . |
JNDIInitContext | The JNDIInitContext parameter is the starting point for where to look for JNDI context on the JNDI server. For example, you can set JNDIInitContext=/ for WebLogic. The parameter starts to search from the top of the tree. You can set this parameter to cell/nodes/localhost/servers/server1/jdbc for WebSphere if you created the connection in this node. |
GenericJDBCDriverBehavior | If you are using a generic JDBC driver instead of a specific driver, the GenericJDBCDriverBehavior parameter specifies the driver whose behavior you want to emulate. Emulating the behavior of the DB2 JDBC driver is set by default. Retaining this setting means that you want to expose DB2 JDBC driver-like functionality to the end user. Valid values are DB2 , SQLServer , and Oracle . |
PREREADNBYTE | The PREREADNBYTE parameter determines the number of bytes to read from the XML doc for each logical read. This parameter is used to improve efficiency and to avoid reading one byte at a time; it is equivalent to block read size. The size should not be too small (at least 4096). Setting the value too high affects memory usage. This parameter is set to 5000 by default. |
XMLLOCALURL | The XMLLOCALURL parameter value is the default connection URL for a local XML file. This default will be displayed in Crystal Reports when you create a new XML data connection. |
SCHEMALOCALURL | The SCHEMALOCALURL parameter value is the default connection URL for a local schema file. This default will be displayed in Crystal Reports when you create a new XML data connection. |
XMLHTTPURL | The XMLHTTPURL parameter value is the default connection URL for an HTTP XML file. This default will be displayed in Crystal Reports when you create a new XML data connection using HTTP(S). |
SCHEMAHTTPURL | The SCHEMAHTTPURL parameter value is the default connection URL for an HTTP schema file. This default will be displayed in Crystal Reports when you create a new XML data connection using HTTP(S). |