Report Manager Web Server

Operations

The web server has predefined commands

The entry point por the web server is the login page:

http://localhost/cgi-bin/repwebserver.dll/login

To test installation you can call version command, with version command you also obtain
the location of configuration files.

http://localhost/cgi-bin/repwebserver.dll/version

After login you can execute configured reports, see Installation instructions about how to
configure the available reports and users.

You can operate the report web server by providing a complete URL with required param
values, that is if you execute a report, you can add it to favorites because all execution
information is stored in the provided URL.

If you need security, run the web server in a secure web server so the URL and all the
informatino will be encoded.

If the web report server is installed in Linux you should execute:

http://localhost/cgi-bin/repwebexe.bin/version

This are a few screenshots of the report web server.

The web report server URL is formed when you advance in login, selection etc, so you
don't need to know them, but for developers here is a list of them:

Parameter
Description
name
User name accessing the report server by default only the user Admin with
blank password is available. You can alter the configuration file to add users
username (execute /version command to know where is located), this user name will be
assigned to a report parameter if exists one named pusername, this is usefull
for executing reports obtaining diferent results depending on the logged user
Password for the selected user, this will travel on the internet so it's
password
recommended to use a secure server
aliasname You can configure several report groups in the configuration file
reportname The report file name
Possible values

0(default) The server returns a pdf file

Returns a native Report Manager Metafile, useful for example to
1
work with WebReportManX web component
Returns a comma separated values file, useful to import from
2
metafile excel for example
Returns a text file, useful to return printable data or plain text
3
data, use it with the textdriver parameter
4 Returns a svg file (Scalable vector graphics)

with 0 (default), with 1 returns a native Report Manager Metafile, useful for
example to work with WebReportManX web component
Assigns this parameter to a parameter inside the report named pusername, if
pusername
exists
Assigns the language index to the report, to show parameter descriptions and
language
result in the selected language.
When metafile parameter exports to text file, if set to 1, the file will be
oemconvert
converted to OEM charset
When metafile parameter exports to text file, sets the output driver, default
textdriver
'PLAIN'
When metafile parameter exports to csv file, sets the separator string, default
separator
','

The login page:

The index page (selection of aliases):

The available reports page:

The report parameters page:
The resulting report:
Dropping fields

After testing datasets and connections you can drop easily fields to report sections.

Select the data page beside the structure page of the report, you will see your dataset and
other variables you can insert in your report, other useful informatino like data types is
also available.

You can drag any field and drop it in the detail section.
You can click the component see and change the properties.
You can now preview the report, and navigate throught pages.

Close the window and drop some labels, to drop a label click the label button in the
palette in the top of the window, then click and extend the label in the detail section.

We wil add a rectangle, drop a rectangle, clic in it, clic To Back Button and position and
size it like this figure:
To adjust detail size click the detail item in the design tree or the surface of the Detail
section, then alter Height property to 2 (cms).

The preview should show something like this:

In the preview window you can click save button to export the result to Report Metafile,
Adobe PDF format, text file etc..
Page Header and page footer

Page header and footer are sections that will print on each page, headers at the top of
page and footer at the bottom of page, you can add more than one page headers or
footers, it will print in the natural order.

You can also assign a print condition to this sections so if you have more than one page
header you can switch between them by placing an exclusive condition for example, note
that print condition of page footer is evaluated at the same time that page header, that is at
page printing begin because the space for the footer must be reserved then.

You click the add button of the tree to add a header or footer section (if you have more
than one subreport you must select the correct subreport first):
In this sample we will place a simple label to the report page header,set the height to 1
cm. and change the size of the font:

Preview the report and you will see the placed label in each page.
Now follow this steps:

• Add a page footer section

• Place a expression in the new section
• Select the new component and go to the expression property in the object
inspector
• Click the button beside the expression property
• Select Functions Category and Page function
• Replace existing expression with the word page

This component will show page number, you can add a label beside it:
Preview the report, you will see page number at the bottom of each page.

Subreport header and summary

The subreport header is a section that the engine prints only once at the beginning.

The summary is printed after all the sections of the subreport, there you place information
about totals etc...

A group is a special section type that is printed at the begining and at the end of the
subreport but also after an expression change, if not change expression is assigned
will be printed at the beginnning of subreport and footer will be printed at the end so we
can use them as headers and summary.

Add a group, name this group as subreport1 for example, set height of header and
footer to 1 cm, place some text there:

Preview the report and see where this new sections are printed.

We will count our customers and print the count in the summary, place an expression in
the summary, and set expression property to 1, Aggregate to Group, Ag.Type to Sum.
Aggregate expressions calculate values based in the number of records of the datset, the
aggregate operation selected will be processed for each record, in this case it will sum the
expression (1) for each record, giving the count of customers, if you want to sum the lines
of a order you must place in expression the line_total dataset field for example.

If you preview the report and go to the last page you will see the count of customers:
Group header and footer

Now we will group the sample customers dataset by the first character of his name.

Note that if you want to group data it must be ordered correctly, we can't group the
customers by city if they are not ordered by city.

We will count also the number of customers for each initial character, the same procedure
you can do for printing order items and order totals.

First add a group with name 'Initial'.

Add a expression at group header created with expression property
Left(CUSTOMER.CUSTOMER,1), select it, click Copy button, select the footer and
Paste it then preview the report, the first letter of customer must be shown at the
beginning and end of the report:
To force group change, we must enter the change expression for the group as
Left(CUSTOMER.CUSTOMER,1),click 'Header-Initial' item in the design tree and then
set the Group Expression, if you preview the report, then the deail sections are enclosed
by group header and footer grouping customers with the same initial customer name
character:
Lets count the customers by initial character, include a expression in the new group
footer, set Expression property to 1, Aggregate to Group, and Ag.Group to 'Initial', also
include a label with the Text 'Total customers with initial:':
Preview the report and you will see the count for each group:
Additional information for correct grouping

In the main dataset use a order by clause that specify each group field:

SELECT .... ORDER BY

MORE_EXTERNAL_GROUP_FIELD,...,MORE_INTERNAL_GROUP_FIELD

For compatibility reasons, the expression of each group must contain other groups fields
that is, for a grouping by custno,orderno and partno:

The select musbe SELECT ... ORDER BY CUSTNO,ORDERNO,PARTNO...

The more external CUSTNO group expression:

FormatStr('0000000000',CUSTNO)

The ORDERNO group expression:

FormatStr('0000000000',CUSTNO)+FormatStr('000000000',ORDERNO)

The PARTNO group expression:

FormatStr('0000000000',CUSTNO)+FormatStr('000000000',ORDERNO)
+FormatStr('000000000',PARTNO)

That is: the change of any field when processing PARTNO group will break the
PARTNO group.

Page setup and print options

To alter report page setup go to page setup option in file menu.

If you left page size Default, the engine will not select any page size before printing, that
is will use the default system page size, you can select a predefined page size or define a
new one (only Windows supports custom page sizes with limitations).

If you left page orientation Default, the enine will not select any page orientation before
printing, that is will use the default system page orientation.

You can configure the report to a specific page size, and also force printer orientation, the
default is use current configured printer page and orientation.
Language property allow you to design the report to print it in multiple languages, the
language property only affect labels, you design the report in english, then switch to
another language, and modify labels, before printing you can switch language from
Report Manager Designer and Report Manager components in Delphi/Kylix/Builder
(language property).

Printer Fonts property allow Microsoft Windows platform the option to use printer
fonts in dot matrix printers so the report will be printed in Native Printer fonts, with the
best precision and speed. To do so you must install the correct driver for the selected
printer, or the printer driver that the physical printer is emulating via Hardware.

Note: To print in Linux in fast test mode you can install the ps2ascii as a filter in your
printer spooler. If you have some sample of doing it, please e-mail me so I can include it
in documentation.

Two Pass Report property allow to know additional information about the report before
printing the first page, if you select this, you can use the pagecount function to obtain the
total number of pager of the report. If this option is set, the report will be calculated
entirely, then printed. It can consume more system resources and the preview is slower
because the entire report is calculated before the engine show the first page.

Duplex and paper source is implemented only for Microsoft Windows, allow the
selection of a paper source (print drawer source) and enable duplex (two side) print on
printers having this feature (usually high volume laser printers).

Page margins are used as the origin for printing sections, bottom margin limits the space
used in the bottom of the page, and right margin limits the space used to the right of the
page that is when printing horizontally (labels for example).

Prefered save format change the way the report is stored to file, you can select plain text
to save the report definition as text and track changes with some version control system,
to obtain a smaller file but not human readable select zlib compressed.

Printer selection

You can force the report to select a specified printer. There are predefined printer
configuration names, and each printer configuration name can be linked to a system
installed printer, it's also useful to determine wich printer will use devicefonts (Windows
only) and to fine adjust the position of the page in the physical page.

By selecting system configuration you force all users use a single configuration (you
must be root in Linux or Administrator in Windows).

Printer selection in Windows has some issues, see known issues and workarounds.
Report grid

Report grid is a very useful tool when designing reports, it allows to easily align
components.

The grid options are stored for each report, you can access them selecting grid option
item in display menu.

If the grid is not enabled, it has no effect, but it can be still visible.
If you select draw lines property, a grid of lines will draw instead points (the default).

You can alter the grid color by clicking the shape.

This is a sample setting grid lines and gray color:

Command line tools

Command line tools are very usefull to provide access to report processing to other
applications, shell scripts... You can also link to the report library.

Command Use
reptotxt This command converts a .rep file to a plain text files
This command converts a plain file to a .rep file, you can process a report or
txttorep
alter it with text processing tools and then save it as a report definition
This command process and print a report definition, you can select a range
printrep
of pages, number of copies and parameters
This command process a report definition saving it to a Adobe pdf format
printreptopdf file or to a native format, Report Metafile, the native format can be viewed
with metaview or Internet explorer plugin, and printed with metaprint
 This command prints a Report Metafile format file, you can select a range of
metaprint
pages and number of copies.
This command generate a executable with a report inside it so it can be
compilerep
distributed independenly (Windows only)

To obtain a description and instructions for use this command line tools write the
command without parameters in a command window.

Report Libraries

Report Manager supports report libraries, you can store reports inside database tables, so
they are centraliced in a single place.

You can configure available libraries at Report Manager designer, go to File Menu,
Libraries and configuration:

It's recommended you create the library from this dialog, after testing the database
connection, a library consists in two tables, the reports table and the groups table. In the
report table the reports and report descriptions are stored, the groups table is needed to
store the tree structure of the library. You can browse the library after the creation.
You can create new folders and new reports.

Use the save to library and open from library options and file menu to manage the reports
inside the library.

Delphi/Bulider/Kylix components support also report libraries from the IDE, you can
even test your reports without compiling your application. Use a TRpAlias to setup
database connections and check report library access, then link your
PDF/CLX/VCLReport to the TRpAlias, select a connection name and a report name.

Report Library with PosgreSQL

You can create report libraries with PosgreSQL, but you need to create a domain BLOB
in your database to identify the binary datatype:

CREATE DOMAIN BLOB AS bytea

Creating the library yourself

Report Manager executes a SQL standard sentences to create report libraries, if you
experience problems you can create the libraries manually.

For example using postgresql:

CREATE TABLE public.repman_reports (
report_name varchar(50) NOT NULL,
report bytea, //not use domain blob
report_group int4,
user_flag int4,
CONSTRAINT repman_reports_pkey PRIMARY KEY (report_name)
) WITH OIDS;

Using report parameters

Parameter features

Report parameters is a powerful feature, here is a list of samples you can do with
parameters

• Allow the user to change words or sentences of the report.

• Set initial values of group sums, etc, place the parameter name in any expression
• Assign them to querys to alter the result set (parametrized or linked querys)
• Replace some text in the query with a provided text (text substitution)
• Print them, or alter them while executing the report, you can use the parameter in
any expression
• Assign parameters using report client application
• Assign parameters using the web report server and any html client
• The parameters can contain expressions evaluated before or after opening report
datasets.
• A search dataset can be defined so the user can search for parameter values inside
a dataset.
• Set a validation rule for the parameter
• Set an error message for the validation rule fail
• Set diferent description, hints and error messages for each report language

You can define the parameters, and also preview how the parameters will show to the
user.

Parameter definition

Parameter definition window allows to add, modify and delete parameters, you can assign
parameters to datasets (parametrized querys). The parameters can be visible or not visible
to the user. You can assign a single parameter to multiple datasets.

This is a sample of report parameters:

The data definition properties for this sample, see that parameters are preceded by the :
symbol.
The user parameters window is called in preview window when user click the parameters
button:

Parameter types

Type Description
String, Integer, Float,
Basic types, they contain fixed values
Date, Time, DateTime
Boolean False or True values
Contains a expression evaluated before any dataset is open, so the
Expres.Bef.Open
result can be assigned to a parametrized query for example
Contains a expression evaluated after opening all datasets, so it can
Expres.Aft.Open
contain dataset fields
You use this parameter type assigning it to at least one dataset, you
must provide a search string, the engine will search in the sql
String Substi. sentence for that string and will replace it with the value of the
parameter. This can be used to pass the entire sql sentence as a
parameter or only the WHERE clause for example.
You provide two list, one for value captions, and other for real
values, the engine will show to the user a combo box to select from
the caption list, and will assign the corresponding value from list of
values.
Value list
A dataset can be specified to fill the value list, when the parameter
window is shown the list is filled with the dataset, first field of the
dataset will be descriptions, and second field on the dataset will be
real values.
It's a merge of String Substi and Value List, the value to be replaced
will be a combination of selected values separated by commas. Very
useful to use with querys like:

WHERE ORDERTYPE IN (:ORDERTYPES)

The user will be able to select more than one value, a checklist box
Multi select
will be provided on parameters window.

The value list can also be loaded from a dataset, like Value List
parameter type.

You can obtain information about a parameter, and multiple

selection using Expression evaluator function: ParamInfo
String sustitution
Same as string sustitition but using multiple selection.
extended
The datatype is detected by evaluating an expression, the value of
the parameter must be a valid expression, for example, to create a
Initial value
paremeter with initial value of today, you select the initial value and
set the value to TODAY.

Special parameters

There are special parameters that can be used to interact with the engine itself, just define
and assign values to them:
Name Purpose
Replaces the connection string with the provided
ADOCONNECTIONSTRING
in this parameter
Replaces the connection string in "ALIAS"
ALIAS_ADOCONNECTIONSTRING
connection with the provided in this parameter
Path to a user defined dbxconnections file, to alter
DBXCONNECTIONS
password, database path at runtime
DBXDRIVERS Path to a user defined DBXDRIVERS file.
Default destination, on preview window, send mail
MAIL_DESTINATION
option
Default subject, on preview window, send mail
MAIL_SUBJECT
option
Default body, on preview window, send mail
MAIL_BODY
option
Optional, force a filename for the attatched file,
MAIL_FILE
you should include file extension
Replaces database connection parameter
PARAMNAME with the value in the parameter.
Useful to provide user name, password, database
path, before executing the report

For DBExpress also DriverName,

DBPARAM_PARAMNAME VendorLib,LibraryName,GetDriverFunc

For InterbaseExpress also DatabaseName is

allowed

For Mybase, Database param indicates the

directory path
Same as DBPARAM_PARAMNAME but applied
ALIAS_DBPARAM_PARAMNAME
only to Connection with alias: "ALIAS"
Filter for Mybase driver in memory datasets, if a
DATASETNAME_FILTER paramter named DATASETNAME_FILTER is
found, it will be used to filter the dataset

Validation

You can set a validation expression for a parameter, the validation of parameters is done
in the moment of showing the parameters to the user, if the validation is not valid, the
error message is shown to the user, this is true also for integrated web server. Note the
validation is not done before running the report, to do validations before running the
report you can use the checkexpression evaluator function.
Lookup help for parameters

Sometines a parameter is specified as a code number (customer code, family code). You
can specify a lookup search so the user can browse a dataset to find the code number.

The simple case is to select a code number from a small dataset. Imagine you have a
parameter FAMILY_CODE, and the user must enter the family code as a number. The
final result will be a button beside the parameter input, when the user click the button all
the available families are shown, the user select it by name and the family code is
assigned to the parameter.

Steps to create a lookup dataset to assist the user on parameters window:

1. Create the parameter FAMILY_CODE as integer. Description family code.

2. Create a new dataset FAMILY_LOOKUP with the sql sentence to show help
information to the user, the first field must be the family code, that is the field that
will be assigned to the parameter: SELECT CODE,DESCRIPTION FROM
FAMILIES ORDER BY DESCRIPTION. Also uncheck the option Open at start,
so the dataset will no be open on report start, but only when needed.
3. Go to parameter definition and select the new dataset, as the Search Dataset for
the parameter FAMILY_CODE.
4. Test the feature going to user parameters window.

Another case is to select a code from a large dataset where the user should search for, like
a customers table.

Steps to create a lookup dataset to assist the user on parameters window, with search
feature, usually to loockup on large datasets:

1. Create the parameter CUSTOMER_CODE as integer. Description family code.

2. Create a new dataset CUSTOMER_LOOKUP with the sql sentence to show help
information to the user, the first field must be the customercode, that is the field
that will be assigned to the parameter, but it will also contain one parameter to
search for only a subset of the dataset: SELECT CODE,DESCRIPTION FROM
CUSTOMERS WHERE UPPER(DESCRIPTION) CONTAINING
:CUST_DESCRIPTION ORDER BY DESCRIPTION. Also uncheck the option
Open at start, so the dataset will no be open on report start, but only when needed.
3. You must create a paramerter called CUST_DESCRIPTION as string and
assigned to CUSTOMER_LOOKUP dataset, you should set the visible property
to false for this parameter.
4. Go to parameter definition and select the new dataset, as the Search Dataset for
the parameter FAMILY_CODE, and assign the CUST_DESCRIPTION parameter
as search parameter.
5. Test the feature going to user parameters window, now the user must write some
text and the after a few seconds, the engine will execute the sql sentence assigning
the parameter CUST_DESCRIPTION.
About parameters and database drivers

When you place a parameter inside a query:

SELECT MYDATA FROM MYTABLE WHERE MYCODE=:CODE

This is called a parametrized query, the query is send throught the database driver, and
translated by the driver to a similar syntax, the parameters must be reconized by the
database driver and the database engine (usually a sql server).Depending on the SQL
server the query will translate by the database driver natively with different syntax:

SELECT MYDATA FROM MYTABLE WHERE MYCODE=?

SELECT MYDATA FROM MYTABLE WHERE MYCODE=@CODE

This query is "compiled" by the database engine, usually this process parse the query,
translating to a native (and fast) format, selects a optimization method (query plan)
including indexes used by the engine, the query can be compiled once (also called
prepare procedure), and execute multiple times, the successive executions will be lot
faster because the database engine can bypass the parse of the query and analizing index
statistics to select the best path to execute the query.

So passing parameters to a database involves the database driver and database server,
some database drivers, does not support large parameters or does not implement some
parameter types (date,time), others are a bit tricky about detecting them, for example:

.. WHERE :CODE=MYCODE can generate a syntax error, but WHERE

MYCODE=:CODE works ok, this is because database driver parse the query to translate
it to database server intermediate format, and the database driver parser can be not
accurately programmed.

Also because the query is compiled by the database server and a optimization plan must
be selected, the parameters can not be placed in any part of the SELECT sentence.

SELECT .... ORDER BY :MYORDER1,:MYORDER2

The above sentence is not valid because a parameter inside the order by clause is usually
not valid, think that changing the order of a query can change the way the query is
optimized by the database server, for example if the where clause and the order by clause
references same field, only one index is needed, if they differ, a diferent query plan
(index path) is needed to execute the query, so a recompilation of the query is needed.

Some database drivers and servers allow parameters inside the select fields part but
others not:

SELECT :MYPARAM,MYFIELD FROM ....

This is also applicable to linked querys, but linked querys takes the parameters from the
master query fields by name.

Note: When you missplace a parameter, the database driver can ignore not returning you
any error.

Workarounds

Using query parameters is efficient and the prefered way, but when database drivers have
some problem, or it's not possible to do it you must find alternative methods. For
example, if the database driver does not accept Date parameter type, you can define the
parameter as string, the syntax of the date will be defined, then by dabase server, for
example '31-JAN-2004' or '01/31/2004'.

So a query can not be compiled/prepared if the order by clause change between

executions, or the where clause syntax changes, to allow the use of parameters in this
querys, there is the String Substitution parameter type, it's not a real parametrized query,
it's a query that will be changed before sending it to the database driver. The use of the
:PARAM syntax is not needed.

For example:

SELECT .... ORDER BY 1,2,3

You can create a string substitution parameter assigned to one or more datasets with
properties:

Property Value
Name ORDERBYCLAUSE
Value ORDER BY 1,2,3
Search For ORDER BY 1,2,3
Description Order by clause

Changing the value of the parameter to:

ORDER BY 2,1,3

Will search for the string ORDER BY 1,2,3 inside the sql sentence, if found, it will be
replaced by ORDER BY 2,1,3 then , the new generated sql sentence is executed.

This is also usefull to change some part of the where clause (or the entire clause) or also
to change the entire sql sentence at runtime.

How to modify parameter values at runtime

Report parameters are added to the evaluator as variables when the report begin, so if you
want to modify the values while the report is executing you must alter the variable value
using a expression like:

paramname:='NewStringValue'

Linked querys

A subreport can have only a main dataset, but you can open as many datasets as you
want, and you can link this datasets to the main dataset or to other dataset linked to the
main dataset. You can also use the child subreport property of a section to merge
subreports.

For example:

• A main dataset with a query to obtain the order lines and order header
• A customers dataset linked to the main datset (customer number) to obtain the
data for the customer
• A ship company dataset linked to the customer dataset by (ship company number)

To link a dataset with another dataset you must select the property Master Dataset. A
linked dataset must have parameters, the name of the parameters must be the same as the
field names of the linked dataset.

Here is a sample:
When you assign a main dataset to a subreport, this subreport, prints the details once for
each record. So while printing a subreport, if the main dataset has a linked query , it will
be updated, for example if the custno field in the main dataset changes and the linked
query is parametrized with this field, the linked query will change, and the new field
values will be available to print.

Child subreports

You usually assign a main dataset to a subreport, and the subreports are printed in order.
But you can change this behaviour by assigning Child Subreport property to a section,
usually you assign this property to a detail section, so the child subreport will be
processed after printing the detail section.

Think about a customers report, the main subreport can contain a detail with the company
name:
And another subreport will print the orders for that customers
You must link the orders dataset to the customers dataset so when a customer is printed,
the orders dataset is updated and the child subreport is processed with the new data.
Child subreports are useful to link and print many to many datasets. See you can calculate
subtotals for each subreport or child subreport.
Printing labels (horz.desplacement/vert.despacement)

To print labels you must first:

• Measure the top-left label distance from physical page

• Measure the label with and height including the space between labels
• Examine printer limitations, that is printable area, if the printer limitations invades
label space then you must consider not use the first row (or column) of labels to
use all the space of the other labels or not use the this space (for each label)

The design of a report that prints labels follows this steps:

• Create a new report, and setup the main dataset, test it placing some labels and
fields
• Set page margins as the top-left label distance of the first label
• Set the with and height of the detail as the with and height of the labels plus the
label distance
• Set detail Horz.Desp. property to true for left to right labels, or Vert.Desp to true
for up to down labels.
 • You can test the adjustment by placing a shape of type rectangle and print it (in
Windows, if the driver is correct, the preview of the printable area should be
exact)
• If the printer has printable area limitations you can omit the first row or column
by adding this space to top-left page margins or not use this space

Here is a snapshot of label1.rep report design, 6,5cm x 3 cm labels

The page setup for that report

And preview using Windows GDI Driver
You can view in this sample diferent labels of diferent employees, usually you need to
print several copies of the same label, to do that you must provide a dataset with X copies
of the same record.

If you want to begin printing labels after 10 labels then you must provide 10 empty
records, so the space of this labels will be skiped.

The building of the dataset can be server side, if you use for example a SQL database
engine you can write a stored procedure with a parameter like number of blank records,
number of copies to print and return the built dataset.

This is a sample using Interbase/Firebird database engine:

CREATE PROCEDURE LABEL_ADRESSES

(
BLANKS INTEGER,
QTY INTEGER,
CLIENTEINI INTEGER,
CLIENTEFIN INTEGER
)
RETURNS
(
ACODE INTEGER,
ANAME VARCHAR(40) CHARACTER SET WIN1252,
AADRESS VARCHAR(50) CHARACTER SET WIN1252,
ACODE_POSTAL VARCHAR(15) CHARACTER SET WIN1252,
ALOCATION VARCHAR(40) CHARACTER SET WIN1252,
PROVINCE VARCHAR(30) CHARACTER SET WIN1252
)
AS
DECLARE VARIABLE I INTEGER;
BEGIN
I=0;
/*BLANKS*/
ACODE=0;
ANAME='';
AADRESS='';
ACODE_POSTAL='';
ALOCATION='';
PROVINCE='';
WHILE (:I<:BLANKS) DO
BEGIN
SUSPEND;
I=I+1;
END
/*QTY*/
I=0;
FOR SELECT
C.ACODE,C.ANAME,C.AADRESS,C.ACODE_POSTAL,C.ALOCATION,C.PROVINCE
FROM CLIENTES C
WHERE C.ACODE BETWEEN :CLIENTEINI AND :CLIENTEFIN
INTO :ACODE,:ANAME,:AADRESS,:ACODE_POSTAL,:ALOCATION,:PROVINCE
DO
BEGIN
I=0;
WHILE (:I<:QTY) DO
BEGIN
SUSPEND;
I=I+1;
END
END
END

To prepare a dataset to be passed to the reporting engine with a number of records you
can use TClientDataset and assign the dataset to the reporting engine:

cdataset:TClientDataset;

...

cdataset.FieldDefs.Assign(itemsdataset.FieldDefs);

cdataset.CreateDataset;

// Repeat for each number of blank records

cdataset.Append;
cdataset.Post;

// Repeat for each number of filled records

cdataset.Append;

for i:=0 to cdataset.FieldCount-1 do

begin

cdataset.Fields[i].AsVariant:=itemsdataset.Fields[i];

end;

cdataset.Post;

// At design time you must assign the clientdataset to the report using
a TRpAlias component

CLXReport1.Execute;

Report files sharing sections

Usually the reports of a project have the same page header or the same report header. For
example if you are designing several reports related to a enterprise, may be interesting to
include the logo and the name of the enterprise. Then you cut and paste this header in
about 100 reports. As a generic application, when you sell it the new customer wants to
change the position of the logo and center the enterprise name, will you change the 100
reports?

The answer to this problem is to store this page header in a external file and especify all
the reports to load the page header from this file, so changing this file you are changing
the 100 reports at once.

Each section in Report Manager have External path property, when the report is loaded,
each section with this property assigned will try to load the section from the specified
file, the external path can be an expression by preceding the string by the @ symbol.

When working with external sections you are responsible for writing and reading them .
The first time you want to include a internal section you assign the External path
property, then right click the External Path property and select save option of the
popup menu.

Next time you open the report it will try to load the section from the file or field. If you
want to use this external section in another report you assign External Path property
and select load option of the popup menu.
External section can be stored in a database table, click in 'External database' property
and Report Designer will show a dialog where you can enter data about where the section
is stored:

• A valid connection available for this report

• A database table inside this database
• A field where the report will be stored (must be of binary type)
• A search field field name to locate the record
• The search value that will be used to locate the record

You can dropdown the combo boxes to see the available tables for the connection, fields
and values, if you enter a new value the designer will ask you if you want to create a new
record in the table to store the section.
Expression evaluator

The expression evaluator is a powerful tool included in Report Manager engine. It allows
to evaluate complex expressions accessing dataset fields, convert field types,
interactuate with the report to know the available free space in the current page, the
current data group...

The Report Manager expression evaluator is like a scripting language but without
iteration operators.

There are lot of report component properties that are expressions: print condition, skip
page condition,...

To design advanced reports you should understand how the evaluator interactuates with
the engine:

• Before the print process, the expression evaluator is initialized, the engine add
useful functions you can use: Page, Free_space, CurrentGroup...
• After the datasets of the report are open (this is done before print anything), the
evaluator can access dataset fields with the syntax: ALIASNAME.FIELD (if the
fields contain spaces use the clausors: [ALIASNAME.CITY NAME])
• Any component with a Identifier property assigned is also added to the
evaluator name space, you can reference them using the syntax M.IDENTIFIER,
or IDENTIFIER, also report parameters are included in the evaluator name
space.
• The engine evaluates expressions in components in a natural way, that is Print
Condition of a section is evaluated before printing this section, if a expression
contains a reference to an Identifier (another report component), it will use the last
value of the component value (last evaluated expression property)
• The exception of the rule are aggregate values, if you assign Aggregate property
of a report component, the expression will be evaluated once for each record of
 the main dataset assigned to the subreport containing the report component, then
the aggregate operation is done (sum, stddev...)

Evaluator syntax

The evaluator syntax is similar to pascal syntax, with a few exceptions:

• To create a variable assign a value to it: (newvariable:=0), but better if you create
the variable adding a report parameter.
• All variables can be of any type, if an operator does not allow the combination of
diferent types it will raise an exception (error), that is like using variant type in
object pascal language or like basic language
• Sentence separator operator (;) has more precedence than assignment operator so
you should use parentesis: (variable1:=2);(variable2:=4);
• Because the evaluator is expression based and not program based, when using the
sentence separator, the result of the expression will be the last evaluated
expression, for the sample above the result will be 4.
• It allows the use of the conditional IIF operator, that is use/evaluate one
expression if the condition is true or other expression if false
• Variables are accessed as M.VARIABLENAME or VARIABLENAME, dataset
fields are accessed as ALIASNAME.FIELDNAME, or also FIELDNAME, but
last syntax is not recommended because can cause confusion with variable names,
it's not recomended to use an ALIAS with name 'M' .

Suported data types

Data type Description Samples

Integer Integer types, up to 64 bits of precision 123 2345 -24345 0
Double Double precision types 12.34 -12.34345 -1.3e-10
Currency types, with a low range but
Currency without lossing precision (four decimals 12.4534
allowed)
String types (ansi), place two ' to 'Sample' 'It''s a sample' 'A sample with a line feed at
String
represent one ' end'+#10
String types of multiple bytes, usually
from fields, but also in expressions, the
expression evaluator can work with
WideStrings, but literals enclosed with '
WideString ADATA.AWIDESTRINGFIELD
sign can not contain WideStrig values, if
you need a widestring literal use the
format: 'this is the infinite
widechar'+#8734
Boolean Boolean data type False True (A AND B)
TDatetime Date and time datatype, this is a double Now-1/24 Date+30
 precision number where each unit is a
day, so 1/24 is an hour, you can operate
as a double so you can sum days,
hours...
Null Null value no value assigned NULL
Althoug there is no operator suport to
binary values, you can evaluate fields to
Binary ADATASET.ABINARYFIELD
pass content to report components, for
example images or large texts

Evaluator operators

This table is ordered by operator precedence

Operator Type Description

Expressions enclosed by parenthesis are always
() Parenthesis evaluated first. Parenethesis are also used to pass
paraeters to functions
This is a special operator, if condition evaluates to
IIF(condition,expr1,expr2) Conditional
true, the evaluates expr1 else evaluates expr2
When this symbols operate to only one operator
- + NOT Unary
(NOT always does this)
*/ Arithmetic Multiply and divide operators
+- Arithmetic Sum and Dif operators
Greater or equal, minor or equal, greater and
>= <= > < Comparison
minor.
The two operators have the same meaning: not
<> >< Comparison
equal
= == Comparison The two operators have the same meaning: equal
Sentence or expression separator, the result will
; Separator
be the last evaluated expression
The AND operator works with two boolean
AND Logical
expressions
The OR operator works with two boolean
OR Logical
expressions
This is the operator to assign values to variables,
:= Assignment
always place the variable in the left side

Evaluator standard functions and constants

Function or constant
True
False
Today
Time
Now
Null
function EvalText (expr:string):variant
function Uppercase (s:string) :string
function Lowercase (s:string) :string
function FloatToDateTime
(n:Double):TDateTime
function Sin (ang:Double):double
function Round (num:double,r:double):double
function Int (num:double):integer
function Str (num:variant):string
function Val (s:string):double
function Trim (s:string):string
function Left (s:string; count:integer):string
function Right (s:string; count:integer) :string Retutns the right part of a string
function Substr(cadena:string; index:integer;
count:integer) :string
function Pos (substr:string,str:string):integer
function Sqrt (num:double):double
function HourMinSec(h:Double; idenH:string; Returns a formated string in format hh:mm:ss but separators
idenM:string; idenS:string) :string
function Mod (d1:integer,d2:integer) :integer Returns the moduleof the integer division
function Monthname (d:datetime) :string
function Month (d:datetime) :integer
function Year (d:datetime) :integer
function Day (d:datetime) :integer
function Formatstr
(format:string,v:variant):string
Description
Boolean constant
Boolean constant
Returns the current date
Returns the current time
Returns the current date and time
Null value constant
Evaluates a expression, you can have expressions inside data
and evaluate them using this useful function
Returns the string in upper case
Returns the string in lower case
Converts a double value to a TDatetime value
Returns the sinus of the angle in radians
Round the num number to r scale, so you can round to 5 cent
0.05 to r parameter
Converts a double to an integer unsing the standard Int functi
the smaller more closer integer value
Converts the parameter to string, the parameter can be any va
be represented by a string (numbers, dates, times...)
Converts a string to a number
Removes leading and trailing spaces from the string
Returns first count characters of the string,
Returns a substring begining at index and copying count char
Search a substrin inside a string and returns the index wher is
if not found
Returns the square of the number
identifiers. Use the most flexible function FormatStr instead
Returns the monthname of a date, you can use FormatStr also
Returns the month number of a given date
Returns the year of a given date
Returns the day of a given date
Powerful formating function, accepts all data types, and form
to the data type, for example for a DateTime value you can u
 string: 'dd/mm/yyyy hh:nn:ss', for a number: '###,###0.00', w
says the use of thousand separator, the 0 are required format p
and # are not required format positions, this function is used i
format property for expressions
Formats a number with a mask, this function is used in displa
property for expressions. The mask is similar to the one used
FormatStr but allow the use of repeatable thousand separator
options:

A hidden decimal separator can be specified (indicates the po

the separation of integer and decimal part) as :, also you can i
pairs of chars indicating:

LX Where X is the character used to fill needed numers on th

default is 0

TX Where X is the character used as thousand separator.

Some samples:

FormatNum(mask:String; number:double) Mask Sample Result D

In
##,##,##,##,##0.00 123123456.789 1,23,23,456.79
fo
C
th
se
se
T'000,000,000,000.00 123123456.789 000123'123'456.79 se
no
w
pa
le
L
w
LI000000000000.00 1231234.789 IIIII1231234.79 ch
(u
bl
Returns the natural language representation of a number, f sa
words required (' una peseta'-'un euro'), for example for 1200
function NumToText
will be 'one thousand and two hundred'. The language is selec
(n:double,f:boolean):string
the active report language. The implementation for this funct
English, Spanish, Catalan.
function ReplaceStr(S,OldPattern,
Search OldPattern inside S replacing it if found with NewPat
NewPattern:Sring):String
function FileExists (s:String):boolean
function ChtToChs (expr:string):String
function ChtToChs (expr:string):String
function IsInteger (avalue:string):boolean
function IsNumeric (avalue:string):boolean
function
IsValidDateTime(avalue:string):boolean
function
CheckExpression(expression,message):boolean
function StringToBin:binary
function Decode64(value:string):string
Return true if the file exists
Translates traditional Chinesse to simplified chinesse (availab
Win32)
Translates simplified chinesse to traditional chinesse (availab
Win32)
Returns true if the string is a valid integer
Returns true if the string is a valid number
Returns true if the string is a valid date/time
If the expression is false raises an exception with the provide
Convers a string to a binary type. An expression returning a b
can be used in the image expression for example.
Decodes a base64 string to the original string representation,
convert the result to binary if the original string represens an
example.

Evaluator functions and variables available while executing a report

Function or constant Description

function GraphicClear (Gr:string):Boolean property of a section for example. The
function GraphicNew (Gr:string; V:Single; parameter is the identifier of the Chart
C:Boolean; Etiq:string; Caption:string)
:Boolean
function GraphicBounds (Gr:string;
autol,autoh:boolean;
low,high:double;log:boolean;
logbase:double;
inverted:boolean):Boolean;
function GraphicSerieColor(Gr:string,
Color:Integer):Boolean;
function GraphicColor(Gr:string,
Color:Integer):Boolean;
Identifer
Clears the values of a Chart report component,
you can place this expression in beforeprint
parameter is the identifier property of the Chart
component
Inserts a new value in the Chart, the first
component. V is the value to insert, C says if
there is a serie change, Etiq is the text of the
value and Caption is the text of the serie
Establish upper and lower bound for a chart,
the axis can be inverted and also a logaritthmic
scale can be used. Set autol (automatic lower
bound) to false and set a value to the low
parameter, idem for autoh (automatic higher
bound)
Set the current chart serie color
Set the color for the last value added to the
chart
Any identifier property assigned to a report
 component usually (TRpExpressions and
TRpCharts) will create a variable in the
expression evaluator, so you can calculate
totals and then use the calculated value in other
report components
Page Returns the physical page number
Returns the logical page number, you can alter
PageNum this variable or initialize it setting
Init.PageNum property in a group section
Returns the available space in the page, in
Free_space , Free_space_inch,
twips (1440 twips = 1 inches), inches or
Free_space_cms
centimeters
Returns true if the alias is at the end of the
function Eof (alias:string):Boolean
recordset
All the report parameters are available in the
Parameters
expression evaluator
Draw functions See draw functions page for details
This is a special expression, can not be
combined or included inside another
expression, when two pass report option is
enabled, the engine will sustitute any
PAGECOUNT expression with the integer
page count value of the report, but you can still
use the display format property to customize
the final output. PAGECOUNT can not be
used inside expressions because:
PAGECOUNT
• Before the report processing is ended,
the engine does not know total number
of pages.

• ANY expression can change section

sizes or any other components
conditioning the length (in pages) of a
report.
FREE_SPACE_TWIPS,
Returns the available free space (vertical) in
FREE_SPACE_INCH,
current page, in the selected unit.
FREE_SPACE_CMS
CURRENTGROUP Returns the actual processing group, it returns
0 if the engine is printing details (so the next
data section will be a detail), it returns a
negative number if the engine is printing group
headers (the number indicates what group
 header is processing) and a positive number
when processing group footers.
Returns true if evaluated inside the first non
repeatable data section printed in the current
FIRSTSECTION page, that is if a page header or a group header
with page repeat is printed they don't count for
the first section printed.
Returns the page witdh and page height in
PAGEHEIGHT, PAGEWIDTH
twips ((1440 twips = 1 inches)
This function uses the sql parameter to execute,
function GetValueFromSQL
and open a sql query using a connection name,
(connectionname:String;
it will return the first column value of the first
sql:String):Variant
row, or NULL if the opened dataset is empty.
Allow the change of the report language at
M.LANGUAGE
runtime
Allow obtaining information about a report
parameter, useful for multiple selection or list
values

Index Meaning
0 Value as string
1 Selected values on multiple selection
2 Selected indexes on multiple selection
PARAMINFO(paramname:string;
3 Selected items on multiple selection
index:integer)
4 Full list of items
5 Full list of values
6 Datasets linked to the parameter
7 Parameter description
8 Parameter hint
9 Parameter error message
10 Parameter validation expression

Building expressions

When you are editing a report, in the expression properties appears a button, clicking this
button a expresion builder helper is shown.

There you can find information about available functions, variables and database fields,
and you can syntax check expressions.
Barcode printing

Barcode limitations

In Linux, the qt library (version 2.3) have only a resolution of 100dpi (dots per inches) so
with some printer drivers the barcodes printed are not readable, that is because the
rectangles of the barcode are slightly bad positioned because this low resolution. If you
export the report to Adobe PDF format and print them using Adobe Acrobat Reader you
will obtain better quality. You can try to use other printer driver or change the module of
the barcode (size of the narrowest rectangle). You can also try to install latest CUPS
drivers, it's reported to work better.

Barcodes supported and comments:

Type
bcCode_2_5_interleaved,
bcCode_2_5_industrial,
bcCode_2_5_matrix,
bcCodeITF14
bcCode39,
bcCode39Extended
Description
2 of 5 code family, supports all properties, this code allow an
unlimited number of digits
Code39 Family, supports all properties, this code allow an
unlimited number of alphanumeric characters, the barcode
with is wider than other that only supports digits, if
 Calc.Checksum is set an additional character checksum is
added, the start and stop characters (*) are automatically
added.
Code 128 family, A and B allow alphanumeric coding, the B
allow also lowercase chars. The C allow only numeric
values but gerenerates the narrowest barcode. The
bcCode128 generates a B and C mixed barcode, full
optimized, so a code like 234534AB generates a 128C
segment and a 128B segment, so the barcode is 50% smaller
than using 128B.
bcCode128A, bcCode128B,
bcCode128C, bcCode128
To generate EAN128 valid codes you must use the
application fields and separator digits, you can use the 102
code or any char with a ascii code greater than 102 to
represent a separator digit, a EAN128 code always begins
with a separator, a sample:

#102+'10896021'+#102+'21456738XABT'
bcCode93,
Code93 family, alphanumeric barcodes
bcCode93Extended
bcCodeMSI MSI barcodes, only digits
bcCodePostNet Postnet barcode, only digits
bcCodeCodabar Codabar barcode, digits, and A..D letters and some simbols
bcCodeEAN8, European EAN barcodes, the last digit is a checksum and
bcCodeEAN13 can be calculated if Calc.Checksum property is set

The Ratio property

Valid ratio values are between 2.0 and 3.0, except for 2_5_matrix between 2.25 and 3.0.
Usually the ratio is 2.0 and it's adjusted to 2.25 on 2_5_matrix. Larger the ratio value
wider the barcode output.

Calc.Checksum property

Only has effect on EAN8,EAN13 and Code39 barcodes.

Modul

The Modul property is used to build the barcode as the size of the narrowest bar.

Rotation property

You can rotate the barcode by a square angle, this property is in degrees.
Composite reports

Composite reports means concatenation of full processed reports, the union is serial but
the free space for the last page of the previous report can be used by the next report.

To compose reports you must set two pass report option in all the reports implied.

Using composite reports with VCL/CLX components

You must have two TRpReport objects available, you can place two TVCLReport
components in a form for example, the TVCLReport.Report property contains the
TRpReport object if you assigned a filename, or used LoadFromStream method of
TVCLReport.

Lets name ReportOne and ReportTwo as the two TVCLReport components, the code to
preview or print the composite report is:

//

uses rpreport,rpgdidriver...

rpgdidriver.CalcReportWithProgress(ReportOne.Report);

ReportTwo.Report.Compose(ReportOne.Report,false,nil);

ReportTwo.Execute;

//

Using composite reports with ActiveX components

You must have at least two ActiveX component, set the filename and calculate the report
before composite. For example, for three reports:

reportman1.filename = "c:\repsamples\sampl2.rep"
reportman1.CalcReport(True)
reportman2.filename = "c:\repsamples\sampl3.rep"
reportman2.Compose(reportman1.Report, False)
reportman2.CalcReport(True)
reportman3.filename = "c:\repsamples\sampl4.rep"
reportman3.Compose(reportman2.Report, False)
reportman3.Preview = True
reportman3.Execute()

Print output and design for dot matrix and pos devices
Page setup

Page size is very important to configure, else you will obtain longer lines and longer
pages and not the correct output.

You can define margins to 0, because the page size will define the practical print out of
the printer, that is the printable area.

For a page width of 80 columns at 10cpi the page width is calculated:

Page Width=80 characters with/ 10 characters per inches = 8 inchess = 8*2.54 cms =
20.32 cms

For a page height of 66 lines:

Page Height=66 lines / 6 lines per inches = 11 inchess = 11*2.54 cms = 27.94 cms

Select user defined paper size and enter the correct values.

For thermal receipt printers usually the font A is 12cpi and font B is 17 cpi, so set a
page with of 42 /12cpi=3,3 inchess=8..6cms. The characters for font B are 3.3*17=56 at
this size. The physical real page width can differ.

For impact receipt printers usually the font A is 10cpi and font B is 12 cpi, so set a page
with of 33/10cpi=3,3 inchess=8..6cms. The characters for font B are 3.3*12=40 at this
size. The physical real page width can differ.

For receipt printers you can establish a page length of 11 inchess=27.94 cms. If you
don't use page headers-footers, or repeatable group headers, will be just like there was not
page breaks, the ticket printer driver does not send form feeds.

Activate text out

To automatically activate a report to print as a text (without driver interaction or filtering)

with escape code secuences you can go to page setup, select that the report will be output
to the character printer (default EPSON driver) or select the output to ticket printer
(default EPSONTMU210 driver).

If you have problems or want to enable better quality escape codes (bold,italic, 12cpi,
20cpi) you can select another driver by clicking at printer setup button. You can select a
printer in the list and the driver it will use. If you don't select a driver, standard output
will be used.

You can also select a printer queue (system printer) so the output will be done to the
selected printer.
At page setup you can force cash drawer open (the engine will send the escape
command to the printer), before or after printing the report.

Microsoft Windows additonal features

With Microsoft Windows and a good quality print driver installed you can still use the
driver to provide fast printing with printer native fonts. You must select the blank text
driver and check the Device fonts option.

With this method, the engine will select the best affordable font for the texts, but the
graphic elements and images will be printed also (usually the graphic elements print slow
on impact printers).

Note this print method does not output lines, but calls Windows API for any graphic and
text operation, and for page size selection, the source of any problem (page displacement,
garbage output) is usually the print driver.

How it works and design recommendations

The graphic elements (drawings and images) are ignored, based on the page size, the
number of lines of the report are determined at a rate of 1/6 lines for inch so for a 11 inch
page size the page will be build with 66 text lines.

The length in characters of each line is determined by the first text element placed in the
line (or 10cpi is selected if no text in this line), the font step (you can specify a Font Step
in the designer) of this text will determine the font size for that line (only one font size is
allowed for each line but multiple font styles can be combined in one line). If the text
element Font Step indicates By Size value, the engine will use the following table:

Font Size Step cpi

<8 20
8 17
9 15
10 12
11,12 10
13-15 6
>15 5

The text elements are placed vertically rounded to 1/6 inch, so the better way to design a
report for text output is set grid height to 1/6 inch that is 0.1666 inch or 0.42333 cms.
Also set the horz.grid size as the most common size of it, for example for a 10cpi report
set horz. grid to 0.1 inch or 0.254 cms. Also resize the section heights to multiples of
1/6 inch, you can do it automatically by selection the option in Edit menu.
Set horizontal page size correctly or at least narrower than the real page size (printer
capability), if you print a 132 column report in a 80 cols printer, the printer will skip two
lines for each report line.

The final output will be a number of lines formatted with the selected driver (escape
codes), or no formatting at all (PLAIN driver). Depending on the selected driver the last
line of each page will finish with a Form Feed instead a Line Feed.

Internal implementation

When the final output is created in memory, the engine send it to the printer in this way:

Microsoft Windows

A new print document is created with the Windows API, to disable the driver, the
document is queued as a RAW type document, so the text go to the printer throught the
selected port in printer configuration without processing in the printer driver. If oem
option is checked then the text is processed first with CharToOem API function.

Linux

The lines are saved to a temporary file, and using unix like interprocess comunication
(pipes) the engine calls lpr command line tool, if oem option is checked then the file is
processed first by the recode command line tool.

The recode command line tool is called with this parameters:

recode ..850/ tempfile

The lpr command line tool is called with this parameters:

lpr -P printerqueue -r -l -J Title

The -P printerqueue parameters are omited if the default printer is used. The -r will force
deletion of the temporary file after processing it, the -l indicates the lpr command to send
the file directly to the device without using any print filter, and the -J gives a job title for
the printer queue.

Drivers overview

Name Description, escape codes

PLAIN No escape codes are introduced , no form feed characters
Init printer, page size, 10cpi, wide escape (5cpi) and condensed
EPSON
escape (17cpi), form feed, underline style
EPSON-MASTER Init printer, page size,form feed, 5-6-10-12-17-20cpi, underline-
 bold-italic, all with ESC ! command
Init printer, page size,form feed, 5-6-10-12-17-20cpi, underline-
EPSON-ESCP
bold-italic, all with ESC/P compatible commands
EPSON-ESCPQ Same as EPSON-ESCP but selecting the better quality (slower)
Init printer, page size,form feed, 5-6-10-12-17-20cpi, underline-
IBMPROPRINTER
bold-italic, with IBM Proprinter escape commands
Init printer, page size,form feed, 6-12-17cpi, underline-bold, all
EPSONTMU210
with ESC ! command, but is capable of printing red color text.
Same as EPSONTMU210 but perform a cut paper command at the
EPSONTMU210CUT
end of the document
Init printer, page size, 6-12-17cpi, underline-bold, all with ESC !
EPSONTM88II
command
Same as EPSONTM88II but a cut paper command at the end of the
EPSONTM88IICUT
document
Init printer, page size,form feed, 5-6-10-12-17-20cpi, underline-
HP-PCL
bold-italic, all with HP-PCL compatible commands
VT-100 Try to emulate VT-100 escape codes
PLAINFULL Same as plain but without blank spaces or blank lines

Form filling and printing

This is a small guide to perform preprinted form filling. Usually you have a form, in
printed format, or pdf and you want to fill values in boxes provided by this form.

1. Obtaining the background image

The background image will be placed in one section of our report so we can place items,
expressions, labels on top of it.

If the form is already printed, you should use a image scanner to obtain the
background image, check the dots per inch property of the scanner, you will place the
same value in dpi property in the section you place the image.

If the form is provided as pdf you should use a tool to convert it to a image file, each
page must be a separate image file, you will get a good result using Adobe Acrobat 6
professional.

Usually the best image format for the background image is a Windows Bitmap format, 8
bit color depth (indexed), if the report have the property prefered save format set to
binary/zlib, the bitmap will be stored in compressed format, make sure to check this
property before adding the background images.
If the images are real life photos the best compression can be acchieved with jpeg format.

2. Place items

After setting the background image property, you can drag & drop fields on top of the
image, the background image can appear also in preview or also printed, checking the
background style. You should set page margins to 0 if you scanned or exported the whole
image.

Here is a sample:

4. Final adjustments

By adjusting margins you can adjust output, if your want to print also the background you
don't need adjustments.
A sample result:

In memory datasets

There is a special database driver, Mybase, that will allow the use of in memory datasets.

The features of this driver are:

• Read the dataset from a file a Mybase binary or XML formatted file (created by
TClientDataset component from Borland tools)
• Read the dataset from a plain text file, with the help of a field definition file, this
files are usually files with one line for each row and fixed size fields. There is a
wizard no create the field definition file.
• Sort the dataset by any field, with the Index Fields property you specify the
fields separated by ; symbol (CUSTNO;ORDERNO for example).
 • Get the records from any other already defined dataset. You use the UNIONS list
to specify which datasets will be used to fill the in memory dataset, if you select
more than one dataset, the numer of fields and field types must be the same.
• Group the union, by selecting union grouping, the in memory dataset will by
grouped by the fields specified in the Index Fields property.
• Stablish master detail relationships, this is a filter based on fields of another
dataset. Use the Master Fields property combined with Index Fields property
to perform field relation equivalences.

Sample

Imagine we are reporting sales by customer but very detailed. We will use a subreport
with a group, customer number, the trick is that at the group header we want to print
total by customer, so expression evaluator sums will not work.

You can solve the problem by using linked querys, but this linked query will be executed
each time a CUSTNO changes in the main dataset, if there are 200 customers, 201 querys
will be executed (once for each custno and the main query).

To enhace performance we will execute 2 querys one for the detail and another for all
totals by customer.

1.Create a database connection.

2.Create a MyBase connection.

DETAIL dataset with database connection with the sql:

SELECT CUSTNO,ARTNO,QTY,PRICE,AMOUNT FROM SALES ORDER BY
CUSTNO

TOTALS dataset with database connectoin with the sql

SELECT CUSTNO,SUM(AMOUNT) AS AMOUNT FROM SALES GROUP BY
CUSTNO

No datasource needed, both querys will be executed only once to enhace performanc and
net bandwith.

Now to show the correct grand total (TOTALS.AMOUNT) for each customer at the
group header:

INMEMTOTAL dataset with MyBase connection, UNION the TOTALS datset.

IndexFields CUSTNO
Datasource DETAIL, MasterFields CUSTNO.

Master fields relates to field names in DETAIL, that will be used with IndexFields to
perform a filter in
INMEMTOTAL dataset. In this case the filter will result in only one row, but it's not
limited in any way.

For example a INMEMORY DATASET can contain lot of rows and the filter can reduce
the result set:
IndexFields: CUSTNO;ORDERNO
MasterFields: CUSTNO

Report components common properties

Name Internal Name Type Description

Width of the component, for sections or
Width Width Twips
component
Height of the component, for sections and
components this size can be modified while the
Height Height Twips
report is executing depending of other properties
(autocontract, wordwrap)
This expression will be evaluated before printing
Print the section or component, if evaluated to true or
PrintCondition Expression
Condition empty the component will print else the component
will not print
This expression will be evaulated before printing
Before the component but after PrintCondition checked.
DoBeforePrint Expression
Print You can use this expression to perform
modifications in variables or evaluate expressions
This expression will be evaulated after printing the
After Print DoAfterPrint Expression component You can use this expression to perform
modifications in variables or evaluate expressions

Properties for components inside sections

Internal
Name Type Description
Name
Horizontal position for the component, this is relative for
Left PosX Twips the parent section position in the page, the left position can
be modified at run time because other properties like Align
Vertical position for the component, this is relative for the
Top PosY Twips parent section position in the page, the left position can be
modified at run time because other properties like Align
Align Align TRpPosAlign The alignment is used to move the component down or
right when the section resizes while the report is
processing
 Name Description
None No align, default
The component will be placed at the right of
Right
the section
The component will be placed at the bottom
Bottom
of the section
Right/B The component will be placed at the right
ottom and the bottom of the section

* Twips are internally stored as an integer representing 1440 points per inchess, when
you are in the designer they are converted to your selected unit in preferences, cms or
inches.

Common properties for text components

This properties applies to components with text properties like TRpLabel,

TRpExpression and TRpChart

Internal
Name Type Description
Name
Horizontal alignment for the text inside
the box defined by the component. The
text can be aligned Left (also None),
H.Alignment Aligment H.TextAlign
Right and Center. Bidi property can alter
the meaning of this property. Internally
stored as an integer.
Vertical alignment for the text inside the
box defined by the component. The text
V.Alignment VAlignment V.TextAlign
can be aligned top (also None), bottom
and center. Internally stored as an integer.
Font name (Type face family name) for
Microsoft Windows operating systems,
this property will be used when the engine
WFont Name WFontName WideString
runs in this operating system and the
driver uses system fonts, usually GDI and
Qt.
Font name (Type face family name) for
Linux operating systems, this property
will be used when the engine runs in this
LFont Name LFontName WideString
operating system and the driver uses
system fonts, usually using Qt printing or
display system.
 Font when the result is a PDF file, the
generation of pdf files does not requires
PDF Font Type1Font TRpType1Font an X Server running in Linux, but can use
only one of the standard PDF fonts in
current implementation.
Font size in standard points unit, that is 72
Font size FontSize Integer
points=1 inchess
Font step for dot matrix output and text
Font step FontStep TRpSelectFontStep output with a printer driver selected, the
engine will select the nearest size
Font color, internally stored as a quad
Font Color FontColor Color
byte 0BGR integer
Combination of a set of possible effects
for the font: bold, italic, underline and
Font Style FontStyle Integer
strikeout, all the styles are compatible.
Internally stored as an Integer.
Left to right reading language support
(bidirectional). The Bidi property is stored
for each language in the report page setup.
Internally stored as a string list containing
the value for each language.

Name Description
Bidi No No Bidi support enabled
Bidi enabled, will print right to
Bidi
Bidi BidiModes BidiMode left text but no change in the
Partial
H.Alignment property is done
Bidi enabled, will print right to
Bidi
left text and will reverse the
Full
H.Alignment property

Bidi support is fully implemented in

Windows but Qt library does not
implement RightToLeft so in Linux is
partially supported, also in PDF export is
only partially supported.
Background color for the printed text, if
Back Color BackColor Color
Transparent property is set to false
If false a background color (Back Color)
Transparent Transparent Boolean
will be used for the text
Cut Text CutText Boolean If true, the text will be clipped to the
defined box, else the text will expand
 outside the box, if word wrap is true, the
widh of the box will be preserved.
Will break the sentences in more lines if
Word wrap Wordwrap Boolean
the lines does not fit in current box width.
Will force printing of text in a single line
Single line SingleLine Boolean
even if it contains line feeds.
Rotation angle in degrees for the text.
F.Rotation FontRotation Angle Rotation in reverse clock wise, internally
stored as an integer in degrees*10 scale.

Subreport properties

A report contains at least one subreport, and a subreport contains at least one detail.

Name Internal Name Type Description

Alias name for the dataset the subreport will
use to iterate (repeat) the detail/s section/s. If
a subreport have this property empty it will
Main print each detail section once. You can use
Alias String
dataset more than one subreport and more than one
main dataset to print more than one dataset
sequentially or in a master detail relationship
(child subreport property of a section)
If this property is true and a Main dataset
P.Only
have been assigned, the subreport will not
Data PrintOnlyIfDataAvailable Boolean
print any of its sections if the dataset is
avail.
empty.

Section properties

Sumary

The sections are contained inside subreports, depending on the section type it will print
after the detail (group header), before the detail (group header), or in special places (page
headers and footers)

Name Internal Name Type Description

Horz.Desp HorzDesp Boolean When horizzontal desplacement is
set to true, after printing the section
the print position will move to the
left, in an amount equivalent to the
section width. But this will happen
only when the next section to print
 has also the horizontal desplacement
set to true, else the horizontal print
position will be restored. Set this
property to true in the detail section
for example to print labels left to
right, adjust the section with so
many details fit in the total page
width. See also labels
documentation.
When vertical desplacement is set to
true, the print is performed as
usually (up to down), after reaching
the bottom of the page, the print
position will place at the top of the
page (or group header) , and the left
print position will move an amount
equivalent to the section with (if fits
in the page), then printing continue.
Vert.Desp. VertDesp Boolean But this will happen only when the
next section to print has also the
vertical desplacement set to true,
else the engine will skip to next
page. Set this property to true in the
detail section for example to print
labels up to down, adjust the section
with so many details fit in the total
page width. See also labels
documentation.
The section will expand vertically to
keep space for any component inside
it. This is useful when you want to
Auto expand AutoExpand Boolean
print some variable text and you
don't know how much page space
you need
The section will contract vertically
to avoid unused space. This is useful
when you want to print some
variable text and you don't know
Auto contract AutoContract Boolean
how much page space you need, of if
some of the components are printed
under certain conditions and you
want to profit space
Available only for groups, initialize
Init.PageNum InitPageNum Boolean the variable PageNum to 1 when the
group changes
 Group name, to be referenced in
Group Name GroupName String
TRpExpressions to aggregate values
This expression is evaluated for each
record of the Main dataset for the
Group
ChangeExpression WideString subreport, it will determine a group
Expression
break with the Bool Expression
property
If true, the engine breaks the group
Bool when the Group Expression is true,
ChangeBool Boolean
Expression else will break the group when the
group expression result changes
If true, the group header will print in
Page repeat PageRepeat Boolean each page where the group is still
active.
This expression is evaluated before
Begin Page BeginPageExpression WideString printing, if result is true the group
will begin a page
If this property is true, after printing
the section a new page will begin
Skip Page SkipPage Boolean
(unless there is nothing more to
print)
If this property is true, the section
will be aligned to the bottom of the
page, and of course next section will
Align Bottom AlignBottom Boolean be printed in the next page, the
alignment is done after resizing (so
it's compatible with Auto expand
and Auto contract properties)
If this property is true, the
displazement for the next printed
Horz.Desp. HorzDesp Boolean section will be horizontal, not
vertical unless the next section have
this property false.
Default=no skip, Before=skip before
print, After=skip after print

Skip Type SkipType TRpSkipType The skip is a repositioning of the

print pointer, you can place print
pointer to another page and/or page
position with properties bellow
If a skip type is assigned then this
Skip to page SkipToPageExpre WideString expression is used to determine the
page to relocate the print pointer
 Determines the horizontal position,
the result of the expression must be
an integer, the unit is in twips
H.Skip Expre SkipExpreH WideString
(1440twips=1 inch), the skip may be
relative or absolute depending on
property bellow
If true the skip is relative to the print
H.Relative
SkipRelativeH Boolean pointer else is relative to the current
Skip
page
Determines the verticalposition, the
result of the expression must be an
integer, the unit is in twips
V.Skip Expre SkipExpreV WideString
(1440twips=1 inch), the skip may be
relative or absolute depending on
property bellow
If true the skip is relative to the print
V.Relative
SkipRelativeV Boolean pointer else is relative to the current
Skip
page
If a child subreport is assigned it will
Child be processed and printed after
ChildSubreport TRpSubReport
subreport printing this section, see also child
subreports reference.
Will load the section from a file so
the report file can share sections.
External Path FExternalFilenam String The external path can be an
expression by preceding the string
by the @ symbol.
External Will load the section from a database
ExternalDat.Tabl.F String
Database so the reports can share sections.
For page header and footers only, if
this property is true, the
Global Scope Global Boolean header/footer will be processed
globally just like if it was outside the
subreport
Only for page footers, means the
page footer must print at the end of
Force Print ForcePrint Boolean
the subreport if no data is still
available
Image Stream TStream Embedded image, stored with the
report structure containing a image
stream, will be drawn bellow the
grid, using the resolution bellow.
When embedding large images you
 should set prefered save format in
page setup to binary/gzip to enhace
performance.
Resolution of the image in pixels per
Resolution inch unit, the size of the bitmap and
dpires Integer
(dpi) the resolution will determine the
final size
The background of the section can
be used for multiple purposes, one is
help in design time to fill a form for
Background example, but no preview or print
BackStyle TBackStyle
Style (preprinted forms). You can also
select to draw the background image
in preview or print the image on the
paper also.
The image can be embedded (Image
propery) or obtained throught this
expression property, the expression
is evaluated, if the expression result
is a binary database field will try to
Back.
Expression WideString read the image from there, see below
Expression
the image formats supported. If the
field is a string field or the result of
evaluation is a string the engine will
try to load the image as a file
reference.
A expression to obtain the value that
Export
ExportExpression WideString will be uses in custom output text
Expression
format
The display format will be used if
Exp. Format ExportDisplayFormat String provided to format the export
expression
The exact line of the text file where
the export result will be placed, if
Exp. Line ExportLine Integer
you set this value to 0, the current
(last) line will be used
Postion inside the line (first position
Exp. Position ExportPosition Integer is 1), where the text will be placed in
custom text output
Size of the output for custom text
Exp. Size ExportSize Integer output, will be right padded with
blank characters
Exp.New Line ExportDoNewLine Boolean If this value is true, a new line will
 be added after exporting this item in
custom text output

Properties for TRpExpression

Name Internal Name Type Description

Expression, the result of evaluating the
Expression Expression WideString expression will be printed (except if it's
an aggregate)
Used for formatting output, if you specify
a data type and the expression value is
Data Type DataType TRpParamType NULL it's replaced with the type
equivalent for formating, this is specially
usefull for numeric values
Formating mask, the value to print will be
formated with this string, depending on
the data type of the value the string have
diferent meanings.

For example for a DateTime value you

can use the format string: 'dd/mm/yyyy
hh:nn:ss', for a number: '###,###0.00',
Display where the , says the use of thousand
DisplayFormat String
Format separator, the 0 are required format
positions and # are not required format
positions.

The engine will use FormatStr function,

see documentation, but if the first
character is a *, the FormatNum function
will be used (only for numbers), using the
mask without the first char.
If true, then the print value (usually a
string) will print in diferent pages if
Multi page MultiPage Boolean needed, usually you set autoexpand and
autocontract to true in the parent section
and word wrap property to true
If true, the numbers with 0 value will not
Print Null PrintNulls Boolean
be printed
Identifier Identifier String If you assign a identifier string, you can
get the effective value of this
TRpExpression from any expression
inside report, so the identifier is included
in the expression evaluator namespace,
 this is useful when working with
aggregate fields and, for example, sum
two aggregate values at a group footer.
Value Meaning
None Default behaviour
For each record the expression
is evaluated and aggregated,
Group
the initialization is done in a
group change
Aggregate Aggregate TRpAggregate For each record the expression
is evaluated and aggregated,
Page
the initialization is done in
page change
For each record the expression
is evaluated and aggregated,
General
the initialization is done in the
begin of the report
For Aggregate=Group indicates wich is
Agg. Group GroupName String the group that initializes the aggregate
value
Value Meaning
Sum Sums the values
Min Get the minimum value
Agg.Type AgType TRpAggregateType Max Get the maximum value
Avg Get the average of all values
Get the statistical standard
Std.Desv
desviation of all values
Expression with the initial value if an
aggregate have been selected, note the
Ag.Ini.V. AgIniValue WideString Sum aggregate type is available to sum
strings so you must place a '' value to sum
the strings
If the value is repeated and the section
have not changed, will print only once,
this is usually useful to group without
P.Only One PrintOnlyOne Boolean
adding group header/footers, that is
ordering the dataset and print only when
the field value changes
Will force printing of text in a single line
Single line SingleLine Boolean
even if it contains line feeds.
 Rotation angle in degrees for the text.
F.Rotation FontRotation Angle Rotation in reverse clock wise, internally
stored as an integer in degrees*10 scale.

Properties for TRpShape

Sumary

Internal
Name Type Description
Name
rectangle, square, rounded rectangle, rounded
Shape Shape TRpShapeType square, ellipse, circle, horizontal line, vertical line,
oblique 1 and oblique 2
solid, dash, dot, dash-dot, dash-dot-dot, clear
Pen
PenStyle TPenStyle
Style
Clear means transparent pen
Pen
PenColor TColor Pen color as a RGB integer
Color
Pen Pen width in twips (0=minimum device width),
PenWidth TRpTwips
Width 1440 twips=1 inch
solid, clear, horizontal pattern, vertical pattern,
Brush
BrushStyle TRpBrushStyle diagonal pattern 1, diagonal pattern 2, cross pattern,
style
diagonal cross pattern, dense 1 to 7 patterns
Brush
BrushColor TColor Pen color as a RGB integer
Color

Properties for TRpImage

Internal
Name Type Description
Name
Draw Style DrawStyle TRpImageDrawStyle Value Meaning
Draws the image using the
Resolution property to determine
Crop
size, then cut the part of the image
outside the component size
Draws the image no using the
Stretch Resolution property but adapting
to the size of the component size
Full Draws the image using the
Resolution property to determine
size, then ignores component size,
 you can use this property with
parent sectoin autoexpand
property to draw different image
sizes optimizing page space
Draws the image repeating it until
the component size is filled, this is
Tile used to obtain for example beatiful
backgrounds from small sized
bitmaps
The image can be embedded (Image
propery) or obtained throught this
expression property, the expression is
evaluated, if the expression result is a
binary database field will try to read the
Expression Expression WideString
image from there, see below the image
formats supported. If the field is a string
field or the result of evaluation is a string
the engine will try to load the image as a
file reference.
Embedded image, stored with the report
structure containing a image stream. When
Image Stream TStream embedding large images you should set
prefered save format in page setup to
binary/gzip to enhace performance.
Resolution of the image in pixels per inch
Resolution unit, the size of the bitmap and the
dpires Integer
(dpi) resolution will determine the final size
depending on the Draw Style property

Aditional details about the implementation

Because Report Manager driver architechture, the image formats supported depends on
the output driver used, the server applications use the PDF driver.

Supported Image file formats

Windows
Image type Windows QT Linux QT HTML PDF
GDI
TCLXReport TCLXReport TVCLReport TPDFReport
Windows Bitmap,
Yes Yes Yes Yes Yes
regular
Windows Bitmap, RLE Yes Yes Yes No No
Windows Bitmap, Yes Yes Yes Yes Yes
Monochrome
JPeg Image (any
Yes Yes Yes Yes Yes
method)
PNG Image Yes Yes No No No
XPM Images Yes Yes No No No
Gif Image No No No No No

Notes:

• The image files supported by the Report Servers (TCP and Web) are the same as
the TPDFReport.
• The text ourput driver does not support any image or drawing
• The TVCLReport and TCLXReport components can extend graphic file formats
by calling from Delphi/Builder/Kylix source code the RegisterGraphicFileFormat
function, this will allow loading of different file image formats like GIF or PNG

Adobe PDF output

Native pdf output is implemented, you may experiment that the pdf output is lighting fast
compared to Acrobat Distiller and other print drivers that output pdf, this is because the
translation is done directly from Report Manager native format to Adobe PDF format.

To enable truetype font embedding in a report, at the designer select Edit->Select all
texts, then at object inspector select Truetype font option in PDF Font property.

But you may take consideration the following issues and limitations:

• Unicode is supported only if the original font supports unicode

• True type font linking and embedding is available from version 2.2, but see
bellow details of the implementation.
• Only Jpeg and Windows Bitmap image formats are supported.
• Compression is available, and used by default, but some pdf viewers does not
read PDF compressed files, the official Adobe PDF reader does not have such
problems.
• Composite fonts and CID Fonts are not supported, that is are supported but PDF
output processed as single fonts.
• The engine is faster and the file is smaller if you use standard Type 1 fonts
(Courier/Times/Helvetica)
• The TrueType font embedding enlarges the file size of the PDF file. Better
optimization is hard to done (remove unused glyphs for example). You can use
TrueType font linking if you know the destination computers have the font
installed.

Linux and Windows, different technologies, different implementation

Microsoft Windows already have a font cache, that is any application can ask information
about installed fonts, including obtaining the entire font file (to be embedded), also the
operating system will search the most appropiate font when the original font is not
available (font matching). Implementation works for TrueType and OpenType fonts, but
some fonts can not be embedded (I didn't found anyone), that is the API does not allow to
get font data for that fonts (maybe distribution license issues?)

Linux does not have a standard font service in the operating system itself, instead of this
it has libraries that provides some services, and of course there is the X library.

The X client library

There are funtions in the X protocol to retrieve sizing infomation about installed fonts (in
the server), but this information is not complete, and there is no way to retrieve full font
data (the font file), some work have been done, there is a project called X print server in
early stages, this requires the installation of a X print server process, and X print client
libraries, but this is not the good way.

There is also a font information library Xft, the good thing is that it can work optionally
with font servers, the bad thing is that does not provide enought information (font file
data). Anyway it depends on a running X server (bad thing for console applications).

Applications like OpenOffice take the font information from the computer executing the
X client program not the X server so the X server protocol probably does not allow to
work with sever side installed fonts.

Another library providing font services Fontconfig, font config provides font
informantion and font matching services, but does not provide enought information (char
sizes and full font data), it's designed as very basic font information system.

But a great library is usually available in Linux systems, freetype library, Report
Manager implementation is done using the version 2.1.8, but it's compatible with 2.X
version, you will find it as freetype2 in your linux distribution , and the shared object
needed is libfreetype.so. Usually is installed by default, probably minimal console Linux
installations does not install it, Report Manager will need it only if you use TrueType font
embedding or linking.

Because freetype allows the access to Type1 fonts information, the Type1 fonts can be
also used in a pdf but only linking is available, because of the requirements of PDF
specification there is additional work to embed Type1 fonts.

Unfortunatelly the freetype library does not implement font maching (and font
information file catching), bug at least it can provide full information about font files,
also extended information and can also render fonts. So simple font matching is done in
code at Report Manager engine.
Report Manager uses /etc/fonts/fonts.conf file to search for font directories, the font
information is cached the first time a TrueType font embedding is required, but to
retrieve this information costs reading all font files and get information about the fonts
(font names, styles...) to perform font maching. This process is done once, but it's
expensive when you execute only one report (printreptopdf command line tool for
example). Note that this overhead will not appear if you don't embbed PDF fonts.
Depending on the number of fonts you have installed it will be not noticeable.

The good thing is that you don't need a X server generate the pdfs with TrueType
embedding.

The font maching algorith inside Report Manager is really simple, search for the same
family name and style, else search for a similiar family name, else get a default font and
apply the style. Note that Fontconfig does not force font maching to his own unique way
like Microsoft Windows do (give few options), but you must provide preferences about
the most important features of the font to match. Maybe a future enhacement to use
FontConfig for font matching but for now it only adds a dependence to enhace a little the
matching algorithm (maybe only font information caching is only the reason to use it).