This is a technical overview of Valentina Reports components within Paradigma Software products. You can also learn several common uses and tasks developers use with Valentina Reports.

Valentina Reports consists of two major logical parts:

• Valentina Report Editor – the part of Valentina Studio Pro for designing reports (See Valentina Report Editor)
• Valentina Report Engine – the 'vcomponents/vreport.dll' component for displaying reports within Paradigma Software products

The Valentina Report Engine (i.e. VREPORT.DLL) is included in following Valentina products:

• Valentina Studio, including the Valentina Studio Pro Reports Editor and Valentina Reports Viewer
• Valentina Server, which uses it to generate reports using templates designed in Valentina Studio Pro
• Valentina ADKs the optional DLL component that generates reports at runtime inside of your application

The VReport component architecture serves multiple purposes.

• VREPORT.DLL is tightly linked to VKERNEL.DLL, as it uses many classes and algorithms within the Valentina Kernel. These include formatting from ICU or SQL Expressions.

• VREPORT.DLL contains DB drivers (mySQL client, PostgreSQL client, SQLite - the whole engine) and is linked to VKERNEL.DLL, VCLIENT.DLL and ODBC libraries can communicate with all supported databases.

• VREPORT.DLL sends READ-ONLY SQL queries to databases and does not modify databases.

For additional details, check Valentina Reports FAQs.

The Valentina Reports system can be embedded into applications for a variety of purposes for generating, displaying and exporting reports. If you are a software developer and you want to embed Valentina Report engine into your application, consider the following steps.

Download and install on your developer computer:

• Valentina Studio Pro - Valentina Studio Pro is necessary for visual creation of Valentina Report layouts and report scripting. You candownload the macOS, Windows and Linux versions from our site or for the macOS version from the Mac App Store .
• Valentina ADK - Valentina ADK for the target platform in order to use the Valentina API classes and methods in your application. DOWNLOAD the correct target platform.

Valentina Reports can be developed and run from directly within Valentina Studio Pro.

You need to have:

• Valentina Studio PRO serial. Enter the serial number in the menu “Help → Register Product” of the Valentina Studio application to activate it with Pro features.
• Valentina Report ADK serial(s) - one per each OS, where you going to deploy your application. You will use it in the Valentina.InitReports() call in your application code.

If your licenses of Valentina Studio Pro and Valentina Reports ADK were purchased separately, make sure the version of Valentina Studio Pro you have supports the database version of Valentina Reports ADK.

1. Design report(s) in Valentina Studio

First of all you need to design one or few reports using Report Editor of Valentina Studio Pro. These reports are stored in the Valentina Project file (*.vsp). This file in fact is a Valentina database with few system tables, where reports are stored in the XML form in a TEXT/BLOB field.

When you design a report in the Report Editor you will be asked to point a datasource. It can be any supported database: Valentina database, SQLite, mySQL, PostgreSQL and ODBC. This datasource should have some set of records, which you will use to test your report during iterations design ↔ preview.

In addition to data, provided by the datasource, it is possible to pass additional information into report during run-time, using the mechanism of Valentina Reports Parameters. These parameters can be used both in the source query and expression fields. Valentina Studio provides dialogs to manage parameters at the design and preview stages.

You should check these resources about how to design reports:

• Report Editor Help
• VIDEO LESSONS about Report Editor

2. Generate report(s) from Application code

When you have finished to design report(s) you can use them in your application, thanks to embedded Valentina Report Engine.

You should put prepared .vsp file of your Valentina Project near to your application, because you will need deploy this file together with application. For Windows/Linux applications, the best place is the application folder, for MAC OS X this can be place inside of application package. Important is that your application should be able locate and open this file after installation on a user computer.

Note, that you can mark .vsp file as READ ONLY in your deployment, this will prevent from changes by a user mistake. Also this will prevent creation of Valentina DB journal, what can be helpful for sandboxing of your OS X application.

Note, that from your application code you cannot change a .vsp file. To make any changes in a report, should be used Valentina Studio Pro.

To start work with Valentina Reports you need first of all add into your application code initialization of vreport.dll in App.Open() or in similar place:

App.Open()
    Valentina.InitReports( )
end

Also you need add paired call to finish work with report.dll in App.Close() or in similar place:

App.Close()
    Valentina.ShutdownReports()
end

Between these calls you can work with Valentina Reports. For this you can use two classes of a Valentina ADK: VProject and VReport.

dim my_project as VProject = new VProject
my_project.open( path )
 
' now we LOAD a report template and query from the project:
dim rep1 as VReport = my_project.MakeNewReport( "report_name",  "sqlite://path_to_db" )
 
' let the query was defined like "SELECT * FROM T1 WHERE fldBalance > $P(pBalance)",
' now we can set its parameter value:
rep1.SetParameterValue( "pBalance", 1000 ) 
 
' now we can generate report using some datasource:
rep1.PrintToDisk( path_for_report, EVReportPrintType.kToPDF, 1, 10 )  // generate first 10 pages.

You can check “Examples/VReport” in your ADK installation for details.

You may want to use Valentina Server as a REPORT SERVER. This allows to work in the client/server mode, but with reports instead of databases.

In this mode Valentina Project (.vsp) file is located on a computer where a Valentina Server is installed, and is managed by this VServer. Valentina Studio and your Application(s) can connect to Valentina Server by TCP/IP and ask it generate report as, for example, PDF or HTML. Then client application get back this generated report.

NOTE: It is important to understand that in this case works VREPORT.DLL, which is inside of Valentina Server. So your application can contains only VCLIENT.DLL (+vshared.dll of course) to be able talk with VServer. This can be a good idea for e.g. mobile devices applications.

Of course the most obvious advantage to keep a Valentina Project under Valentina Server is multi-user collective work with it. It is enough to change some report inside of vproject file and all users immediately will get updated version of report.

TIP: Besides, usage of VSERVER can be helpful for even a single developer during development. Because during development we often interrupt debugger at any place. Working with database (.vdb) or with Valentina project file (.vsp) that are under a Valentina Server, we do not insult these files by such unexpected breaks. Your application is stopped, but Valentina Server is still running and still keeps that files open. This also speedups time of your next application start when it opens Valentina database or project, because they in fact are opened.

1) You can create vsp file by Valentina Studio right on your Valentina Server.

2) But usually we need to put existing “*.vsp” file under control of some VServer. For this you need to copy this “.vsp” file into “vserver/projects” folder. Then you need register project to VServer using either GUI of Valentina Studio or SQL command “REGISTER PROJECT”.

If you want totally remove project file from VServer control you need unregister project. For this you can use SQL command “UNREGISTER PROJECT” or GUI of Valentina Studio. Now vsp file is closed and Vserver have forget about it. You can move it out from folder “vserver/projects” to any other location.

To enable your application work with a Valentina Server, you need init Valentina Client:

Valentina.InitClient( 10 * 1024 * 1024 )

After InitClient() you can work actually with both databases and reports managed by a Valentina Server. Please note that this method do not requires any serials, because any Valentina Client is totally FREE.

InitClient() should be paired with ShutdownClient(), which should be the last call to Valentina Client component to shut down it.

Now you need open connection to VServer and them open VProject in the scope of that connection:

dim pc as VConnection = new VConnection( "localhost", sa, sa )
dim myProject as VProject 
 
try
{
    pc.Open()
 
    myProject = new VProject( pc )
    myProject.Open( "project_name_as_registered_to_vserver" ) 
 
    ... some work here ...
 
    myProject.Close()
    myProject = nil
 
    pc.Close()
    pc = nil
}
catch(...)
{
    ...
}