Chapter 6. Adding DataMatrix to Crystal Reports

Adding DataMatrix barcodes to Crystal Reports is quite simple. The software includes a report file authored in Crystal Reports 9.

Note: the functions in this release are not backward compatible with old version DataMatrix Fontware 3. You need to change the functions in order to use the new version API.

Warning

Due to the length constraint imposed by Crystal Reports, the approach outlined in this chapter requires Crystal Reports version 9 and above. If you need to work with a lower version, write to to request a trial of version 3.

6.1. UFL Functions

A Crystal Reports extension DLL is included in the software (cruflDataMatrix5.dll), which provides data matrix encoding functions. By default, this file can be found under the installation directory. This is a COM DLL - so you must register it if you move the file to another computer. This is typically done by running regsvr32 cruflDataMatrix5.dll command in a administrator console. In this release, both 32-bit and 64-bit versions are supplied. The 32-bit version is required to work with Crystal designer. The 64-bit is needed to work with 64-bit Crystal runtime. On 64-bit Windows, both DLLs are installed. [1]

This DLL exports two functions:

Table 6.1. List of Crystal Reports UFL Functions ( cruflDataMatrix5.dll)

Function NameComment
Number DataMatrixEncodeSet (String, Number)Returns the number of chunks required for the data encoded. The second parameter specifies the size ID.
Number DataMatrixEncodeSetRAS (String, Number)If you are using RAS print engine, use this encoder function instead of DataMatrixEncodeSet to work around a bug in RAS. See KB10052 for details.
String DataMatrixEncodeGet(Number)Returns a chunk. Each chunk consists of no more than 254 characters (the maximum number allowed by Crystal Reports).

Function DataMatrixEncodeGet takes one argument which is the ordinal number of the chunk. Function DataMatrixEncodeSet has two parameters. The first parameter is data encoded, followed by the size ID. For the meaning of size ID parameter, refer to Section 2.1, “What is Data Matrix?”. This function returns a number, which indicates the number of subsequent calls to DataMatrixEncodeGet. Each call of DataMatrixEncodeGet retrieves a chunk of encoder results.

The following script demonstrates the basic flow to get it work in Crystal Reports:

  //Mroovia example formula to display Datamatrix barcodes
  StringVar CompleteBarcodeString:="";
  StringVar DataToEncode:= {Your Field Here};
  NumberVar i:=0;
  NumberVar Segments:=
  DataMatrixEncodeSet(DataToEncode, -1);
  For i:=0 to Segments Do
  (
     CompleteBarcodeString := CompleteBarcodeString +
               DataMatrixEncodeGet(i);
  );
  CompleteBarcodeString 

Because of the length restraint that UFL imposes on the string, it is not possible to complete in one UFL call. Instead, you prepare all parameters and call DataMatrixEncodeSet. This function calls encoder at the back end, and returns the number of chunks required. After that the program enters a loop that calls DataMatrixEncodeGet repeatedly until all result are retrieved and stored in BarcodeString.

6.2. Tutorial: Step by Step

The screen shots in the following tutorial were taken in Crystal Reports 9. Interfaces in other versions may appear slightly differently.

Assume that you have a database table with several fields. You already put them into the report, and want to add a column to hold DataMatrix barcode for ID field.

  1. First switch to design mode. Choose ReportFormula Workshop.

  2. Right click on Formula Fields and choose New.

  3. Give your formula field a name, in this example we will name it Morovia_DataMatrix. In versions 9 and above, you will be prompted to use the editor or the expert, choose Use Editor.

  4. In the Formula Editor, choose FunctionsAdditional FunctionsVisual Basic UFLs (u2lcom.dll). You should see DataMatrixEncodeSet appears under. If not, the DLL is not installed properly.

  5. In the edit box below, copy and paste entire script in Table 6.1, “List of Crystal Reports UFL Functions ( cruflDataMatrix5.dll)”. Make necessary changes. For example, you are likely to change the value of DataToEncode variable to one of your database field. Version, Error Correction Level can be changed in the code accordingly.

  6. Choose SaveClose to close Formula Workshop.

  7. From the Field Explorer, drag the Morovia_DataMatrix formula field to the report.

  8. Choose FilePrint Preview. You should see a series of meaningless lower case letters and digits in the box. This is normal as the barcode string is completely difference from the data encoded in case of DatatMatrix.

  9. Switch back to design mode. Right click on the field and choose Format Field. Click on the Font tab, and choose the MRV DataMatrix5 font. Set the font size to 6 points or to the size appropriate for your environment.

  10. Drag the cursor to make the formula field big enough to contain the entire barcode. You may need to adjust both horizontally and vertically. Be sure to leave some spaces for quiet zone requirement.

  11. Run the Print Preview again. The barcode should come up. Print a page and scan the barcode to make sure that the font size is appropriate and the bounding rectangle is big enough to hold the whole barcode.

Note

If you add barcodes to report using the trial version and subsequently upgrade to the full version, you need to refresh the report once. Otherwise the barcode will continue to be scrambled.

6.3. Distributing UFL, Fonts with your report application

Once you finish the report design, you can distribute your report application with Crystal run time files, barcode fonts and the UFL library.

Note

Developer License is required to distribute font files and encoder UFL DLL outside your organization.

Two run time files need to be included in your distribution package:

  1. Morovia DataMatrix Font. The font file is located C:\windows\fonts\mrvdatamatrix5.ttf, and should be copied to the target computer's fonts folder.

  2. DataMatrix Encoder UFL. This DLL is installed at C:\Program Files\Morovia DataMatrix Fonts & Encoder 5 by default. In the production computer, you can place this DLL anywhere. However, this is a COM DLL and requires registration. If you are deploying to a 64-bit Crystal Reports runtime, you need the 64-bit version of the DLL.



[1] The 64-bit DLL is installed under C:\Program Files\Morovia DataMatrix Fonts & Encoder 5 directory, while the 32-bit DLL can be found under C:\Program Files (x86)\Morovia DataMatrix Fonts & Encoder 5.