Switch to: V9V8V7V6V5

Creating Valentina Databases

Now when you know how to start and stop Valentina, you can programatically tell Valentina to create and open new databases.

After initializing Valentina, you can start creating databases. There are several ways to create Valentina databases – you could create a database first in a visual application like Valentina Studio and then have Valentina manage that database for your application. You can also programatically create Valentina databases.

There are good reasons explaining why programmatic creation is the way to go:

  • SIMPLIFICATION. Valentina Studio is a great program for creating, browsing, querying and administering Valentina databases - but it may not be a necessary addition to the process.
  • MINIMIZE SURPRISES. If you do it all programatically, you know exactly what kind and format of data is in the database.
  • REDUCE TEDIUM WITH AUTOMATION. Let`s say you want to create a database with twenty tables. It is simply tedious to do this manually in Valentina Studio when a short piece of code can do it for you, again and again.

What You Will Learn

When you started Valentina, you used one Valentina handler, Valentina_Init ( ). Creating a new database programatically and then opening it, you will learn four more:

  • VDatabase_Constructor()
  • VDataBase_Open()
  • VDatabase_ErrNumber()
  • VDatabase_Create()

Note: Don't feel intimidated by VDatabase_Create! Any time you see a pare of [] it means what is inside isn’t a requirement – its an optional parameter.

Example: Creating a New Database Programmatically

Here is an example taken from Lesson 1 - Creating an Employee Database. In this example, the DatabaseCreate handler creates a new database called Database1, places the path to the new database into dbPath, and then opens the database.

on DatabaseCreate

   put VDatabase_Constructor() into mDatabase

    -- Build db full path near to stack:
   get the effective filename of this stack
   set the itemDel to slash
   put the (item 1 to -2 of it) & slash & "Database1" into dbPath

   get VDatabase_Create( mDatabase, dbPath, "kDscDatBlbInd" )

end DatabaseCreate

In Detail: VDatabase_Constructor()

VDatabase_Constructor() is a constructor. A constructor is a method for creating an object. It's pretty clear for every beginning there is an end – where there is a constructor there is also usually some form of destructor.

In Detail: VDataBase_Open()

VDataBase_Open(dbRef, path) takes two parameters – dbRef is an integer that refers to the database that you want to open, and path is the directory path to the database. If dbRef is baffling you, reread What is a Reference. You already have access to dbRef and the path.

In Detail: VDatabase_ErrNumber()

VDatabase_ErrNumber() returns an integer number. If it returns zero (“0”) then everything is okay – no error. On the other hand, a positive or negative number means trouble. A positive number is specific to Valentina. Valentina is telling you something is wrong with its operations. If the number is negative, Valentina is passing you an operating system error. Operating system errors are different in Windows and MacOS X.

In Detail: VDatabase_Create()

VDatabase_Create() is just as it sounds – you are creating a database files on disk – which requires two parameters and can take up to five parameters.

Don't forget we are creating a database document. Just like any other document, a database has to be filled with content.

The three parameters you should worry about now are dbRef, dbPath and inEnumMode. The first two you already known as the name and location of where you want your new database. The parameter inEnumMode refers to the file configuration – “kDscDatBlbInd” in this example means only one file is created.

Note: inEnumMode can have up to eight different configurations. This will let you highly optimize how Valentina works as you need it to work.