Switch to: V11V10V9V8V7V6V5

Starting and Stopping Valentina

Valentina can operate as an embedded database engine inside your application or as a separate server service. To use Valentina, you should initialize it. In this section you will learn how to start and shut down Valentina safely.

What You Should Already Know

This lesson is designed for the users of Runtime Revolution who already understand the basic structure of Revolution projects, functions, handlers, and using interface tools. It does not require the use of RevDB.

This lesson is designed for the users of Runtime Revolution who already understand the basic structure of Revolution projects, functions, handlers, and using interface tools. You should already know the following key concepts:

  • how to install Valentina
  • how references and paths work in Valentina

If you skipped the chapter May I See Your References?, then you may want to go back and reread that section if you are not familiar with objects and references.

What You Will Learn

You will have a conceptual understanding of:

  • how and why to initialize Valentina with Valentina_Init( )
  • how and why to shut down Valentina with Valentina_ShutDown

Initializing Valentina

Valentina is an embedded database engine that runs in the background inside of your application, waiting for your application to tell it what to do.

Because of this, your application has to be certain that Valentina is running - your application has to initialize Valentina. You can initialize Valentina at almost any time, so long as you initialize Valentina before you want Valentina to execute any operations.

Example: Initialize Valentina

Here is a simple example of initializing Valentina in an OpenCard handler:

on OpenCard
    get Valentina_Init( 10 * 1024 * 1024  )
end OpenCard

In Detail: Valentina_Init ()

Valentina_Init() is the method used to initialize Valentina. Let's look exactly at what that means. Valentina_Init() actually takes three parameters, seen here:

Valentina_Init( inCacheSize, [inMacSN = ""] , [inWinSN = ""] )

inCacheSize is the memory allocated to the Valentina cache. A simple default is shown in the example in bytes, but you can modify this in order to maximize Valentina performance. It is good idea not to allocate more than half of the memory available on a system.

[inMacSN = “”] is your developer serial code for the MacOS X runtime.

[inWinSN = “”] is your developer serial code for the Windows runtime.

If you initialize Valentina without providing a serial number, Valentina will operate normally for 10 minutes, return an error code and won`t accept new commands until restarted.

Note: A good place to store your developer serial codes is in Revolution custom properties.

Shutting Down Valentina

Once you initialize Valentina, you can let Valentina run forever. Valentina can run silently in the background and unnoticed by many.

In fact, this is a normal state for Valentina Server (either the Embedded Server or the Office Server) - the assumption is that there are many users out there who may want to access the server at any time.

On the other hand, if your solution is a standalone solution - an application running on your customer's desktop - you should properly shut down Valentina when you customer exits the application.

Example: Shut Down Valentina

Here is a simple example of shutting down Valentina in a CloseCard handler:

on VCloseCard
    get Valentina_ShutDown
end VCloseCard

In Detail: Valentina_ShutDown ( )

Valentina_ShutDown() doesn’t require any parameters – and it is extremely tidy! When you shut down Valentina using Valentina_ShutDown(), Valentina will do the following:

  1. Automatically saves on disk anything that is in the cache and destroys any existing cursors.
  2. Automatically closes any open databases.
  3. Shuts down the actual Valentina library.

Important! A database cache contains data. The shutdown process is highly secure so that you don’t leave data behind.