Error getting tags :
error 404Error getting tags :
error 404 revOpenDatabase | revDocs | RunRev
Welcome Guest (Log in)
Product Edition
Expander triangle

revOpenDatabase(databaseType,host[:port], databaseName, [userName],[password] [, databaseSpecificOption |valentinaCacheSize,valentinaMacSerial,valentinaWindowsSerial])

Desktop, Web and Server
Platform Support
MacOS,Mac OS X,Windows,Linux
Connects to a MySQL, Oracle, ODBC, PostgreSQL, or Valentina database.

get revOpenDatabase("mysql", "", "RatesDB", myUsr, myPass)
get revOpenDatabase("odbc", "BizFile", , "jenkins" ,the dbPassword of me, "emulated static")
get revOpenDatabase("valentina", "", "::Project:MyVal.vdb", , , , the serialNumber of this card, "")
get revOpenDatabase("valentina", "", "G:\data\expense.vdb", , , , , field "Valentina serial")
get revOpenDatabase("mysql", "", "RatesDB", myUsr, myPass, 0)
get revOpenDatabase("sqlite", "C:/testdbsqlite.db", , , , )

Additional Comments
Expander triangle

Use the revOpenDatabase function to start working with a database.


The databaseType is one of "mysql","oracle" (Revolution Enterprise only), "odbc", "postgresql", "valentina" or "sqlite".

The host is the IP address or domain name of the system hosting the database. For Valentina databases, which reside on the local system, the host should be empty. If no host is specified, the local system is used. For SQLite databases, the host should be the full path to the database file.

The port is the port number you want to connect to, and is used only for MySQL and PostgreSQL databases. If no port is specified, MySQL database connections use port 3306 and PostgreSQL database connections use port 5432.

The databaseName is the name of the database to connect to. For Valentina databases, this is the path to the file that contains the database. For SQLite databases, the database name should be left empty.

Important! When connecting to a Valentina database on Mac OS, the databaseName must be a Mac-style file path. (To convert from a Revolution file path to the Mac style, use the revMacFromUnixPath function.) When connecting to a Valentina database on a Windows system, the databaseName must be a Windows-style file path. On Unix and OS X systems, you use a standard Revolution file path.

The userName is your authorized user name for the database. (Some databases do not require a user name.)

The password is the authentication password for userName. (Some databases do not require a password.)

The databaseSpecificOption is currently used by MySQL and ODBC databases only, on other databases this parameter has no effect. When connecting to MySQL databases the databaseSpecificOption specifies whether to use SSL for the connection or not, the default is false. When connecting to ODBC databases, the databaseSpecificOption specifies which type of database cursor to use. The possible options are described below under the title "ODBC Cursor Types".

determines whether a connection to a MySQL database uses SSL for the connection. If useSSL is not specified, the connection uses SSL. If the databaseType is not "MySQL", this parameter has no effect.

The valentinaCacheSize is the size in bytes of the database cache used for Valentina databases. The minimum cache size is 524288 (512K). If the valentinaCacheSize is not specified, the database cache is 3 megabytes. If the databaseType is not "Valentina", the valentinaCacheSize has no effect.

The valentinaMacSerial or valentinaWindowsSerial is the serial number that unlocks the Valentina VXCMD. (On Mac OS and OS X systems, specify a valentinaMacSerial and leave the valentinaWindowsSerial parameter empty. On Windows systems, specify a valentinaWindowsSerial and leave the valentinaMacSerial empty.) If no valentinaMacSerial or valentinaWindowsSerial is specified, the database closes automatically after ten minutes.


The revOpenDatabase function returns a database ID which can be used to refer to the database in other Database library commands and functions. The database ID is always an integer.


To use a DSN to identify an ODBC database, use the DSN as the host, and leave the databaseName parameter empty.

When using a Valentina database, specify the valentinaCacheSize for greatest efficiency based on the size of your database. The Valentina cache is an area of memory that the Valentina engine sets aside for database operations. The minimum valentinaCacheSize is 512K, or 524288 bytes. For best efficiency, start with the default cache size of 3 megabytes (3145728 bytes), and add about a megabyte for each 100,000-150,000 records in your database.

When connecting to a Valentina database, the valentinaMacSerial and valentinaWindowsSerial parameters take effect for the entire session. If you specify a different serial number for subsequent connections, it is ignored until the next time you quit and restart the application.

If the database is not successfully opened, the revOpenDatabase function returns an error message. The error message is never an integer, so you can check whether the connection was successful by checking whether the return value is an integer or not.

ODBC Cursor Types

When connecting to an ODBC database, it is possible to specify which type of cursor Revolution should use. This is done by passing the desired cursor type to the revOpenDatabase function in the databaseSpecificOption paramete. The possible options are explained below.

"static" - This is a scrollable static cursor. Using this cursor it is possible to navigate backwards as well as forwards through record sets, and to move straight to the first or last record. Static cursors operate on an "offline" copy of the data, meaning that any changes to the data will not be detected by the cursor. Not all ODBC drivers support static cursors, for example FileMaker 6 does not.

"emulated static" - This cursor has the same behavior as a static cursor, except it allows ODBC to emulate the cursor's behavior if the driver does not support it. ODBC can typically emulate static cursor behavior on Windows systems only.

"forward only" - This is a cursor that can be scrolled forwards only. All ODBC drivers must support this type of cursor. Forward only cursors are usually faster than scrollable static cursors, but using revMoveToPreviousRecord, revMoveToFirstRecord or revMoveToLastRecord will fail. Forward only is the default cursor type, and is what was used in Revolution 2.8.1 and earlier.

If the specified cursor type is not supported by the driver the an error string will be returned.

Important! This function's capabilities depend on your edition of Revolution:

* Revolution Enterprise: (and applications created with Revolution Enterprise): Full access to all database types.

* Other editions: Other editions cannot be used for direct access to Oracle databases.

Important! The revOpenDatabase function is part of the Database library. To ensure that the function works in a standalone application, you must include this custom library when you create your standalone. In the Inclusions section of the General screen of the Standalone Application Settings window, make sure the "Database Support" checkbox is checked and the database drivers you are using are selected in the list of database drivers.

Changes to Revolution:

The ability to specify different cursor types for ODBC connections was added in version 2.9

The ability to connect to SQLite databases was added in version 2.8.1

The ability to specify whether SSL is used for MySQL database connections was added in version 2.1. In version 2.0 and later, SSL was used automatically. In versions before 2.0, SSL was not used.

The revOpenDatabase synonym was added in version 2.0.

The ability to connect to PostgreSQL databases was added in version 2.0.

The ability to connect to Valentina databases was added in version 1.1.1.

User Comments
Expander triangle
User thumbnail
Oliver Kenyon
Dec 11, 2009
revOpenDatabase, like all the revDB commands and functions is implemented in a separate library called an External, rather than in the Revolution core engine.
The database library is loaded by adding a hidden group to your stack when deploying it. This hidden group then loads up the library by creating a wrapper stack for the external and inserting it into the message path. It does this on receipt of its first preOpenBackground message.
The consequence of this is that attempting to connect to the database before this preOpenBackground message has initialized the external will fail. For example, don't connect to the database on preOpenStack. Instead use openStack or openCard.
User thumbnail
Apr 22, 2010
Note that (at least in the case of local databases with sqlLite) calling revOpenDatabases on a database file which does not exist will result in the creation of a new, blank database file. Be careful - this file will have not schema / content - always check to ensure the file exists BEFORE calling otherwise you'll get into the confusing situation where the database file exists (and if you check, you'll be inclined to think excellent - database file present - things should be fine) only if you check the size/contents of the file, you'll find it's blank...
There may be a good reason why it works this way, but personally , I think it's a bug...
User thumbnail
Feddo Wouters
Jan 30, 2011
There is a mistake in the documentation (version 4.5.3). The second and third parameter are switched.
To connect to an oracle database, the correct syntax is:

revdb_connect ("oracle", databaseName, host[:port], [userName],[password])