Switch to: V11V10V9V8V7V6V5

Opening and Closing Existing Databases

Opening and closing existing databases is very similar to creating a new database.

What You Should Already Know

You should read and be familiar with the concepts in Creating New Databases.

What You Will Learn

You will have a conceptual understanding of:

  • how to safely open an existing database with VDatabase_Open()
  • how to safely close existing databases with VDatabase_Close()
  • testing to see if a database is open or not with VDatabase_IsOpen()

Opening Existing Databases

Opening existing databases is very similar to opening one after you create it.

Example: Opening an Existing Database

This is a code taken from the API Way Database OpenAny example. In this example, the script opens a dialog to select an existing Valentina database. If the database is encrypted, then the key is passed. If there is a match, then the database is opened.

Valentina databases can be encrypted. If a database is encrypted, you should pass the database an encryption key.

function DoOpen
  answer file "Select DB:"
  put it into path
  if path is empty then 
    return empty
  end if 
  put VDatabase_Constructor() into mDBRef
  get VDatabase_Open( mDBRef, path )
  -- if database is encrypted trying again with key
  if VDatabase_ErrNumber(mDBRef) = 398594 then
    put text of field EncryptionText into key
  -- text of field Encryption Text indicates the supplied key is invalid
    get VDatabase_UseEncryptionKey( mDBRef, key )
    get VDatabase_Open( mDBRef, path )
  end if
end DoOpen

In Detail: VDatabase_IsOpen()

VDataBase_Open( dbRef, inStrPath ) takes a dbRef and path and returns a Boolean TRUE if the database is already open.

Closing Existing Databases

Closing an existing database is very simple and does not even require a path.

Example: Closing an Existing Database

This function shows how you would close the database you opened in the previous example.

function DoClose
  get VDatabase_Close( mDBRef)
end DoClose

In Detail: VDatabase_Close()

VDataBase_Close ( dbRef ) takes dbRef and closes the database but does not shut down Valentina.

What if I try to close a multi-user database that is in use?

The database server uses a counter to determine who was out the last. Each connection to the server must be shut down. The last one standing that uses a close function will actually close the database.

Example: Testing if a Database is Open

This function shows how to tell if a database is currently open.

function IsOpen
  get VDatabase_Open ( mDBRef, path )
end IsOpen