PostgreSQLDatabase

From Xojo Documentation

Revision as of 18:56, 19 November 2009 by WikiSysop (talk) (1 revision)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!


Description

Used to open a PostgreSQL database.


Super Class

Database

Events

Name Parameters Description
ReceivedNotification Name as String, ID as Integer, Extra as String A notification named Name has been received. The process ID of the sender is passed in the ID parameter. At the current time, the Extra parameter will always be empty although it may be implemented in the future.


Properties

Name Type Description
Port Integer The port of the PostgreSQL database to connect to. PostgreSQL's default port is 5432.


Methods

Name Parameters Return Type Description
CheckForNotifications Checks to see if there are any waiting notifications. You will receive notifications as a ReceivedNotification event. If you would like to receive notifications automatically, create a Timer and use it to call CheckForNotification repeatedly.
CreateLargeObject Integer  Creates a PostgreSQLLargeObject and returns its ID. Legal IDs are positive integers. Therefore, if CreateLargeObject returns 0 or less, then there was an error creating the large object. Use ErrorMessage to determine what the error was.
DeleteLargeObject ID as Integer Deletes the large object denoted by the process ID, ID.
Listen Name as String Listens for notifications named "Name".
Notify Name as String Sends a notification named "Name".
OpenLargeObject ID as Integer,

[ReadOnly as Boolean]

PostgreSQLLargeObject Opens the large object specified by the passed ID. The ReadOnly parameter is optional and defaults to False. If you pass True, then the large object will be opened in read-only mode. If OpenLargeObject is successful, it returns an instance of PostgreSQLLargeObject.
Unlisten Name as String Stops listening for notifications named "Name".


Notes

The PostgreSQLDatabase class requires the PostgreSQL Database plug-in. Place this plug-in in the REALbasic Plugins folder. The PostgreSQL Database plug-in ships with REALbasic and you can find the most current version on REAL Software's web site, http://www.realsoftware.com.

The PostgreSQL plug-in supports MD5 password authentication.

A field specified as type Float is actually implemented by postgreSQL as a double (8 bytes).

The IsPrimary column of the FieldSchema for a postgreSQL database always returns False.

PostgreSQL dates: field types Date, Time, and TimeStamp are now properly supported; use the DateColumn and DateValue methods for a date representation of this data, or use StringValue to get a human-readable date and/or time.


Large Objects

PostgreSQLDatabase implements PostgreSQL's large objects. PostgreSQL requires that all large object operations be performed inside of a transaction. Therefore, you must start a transaction before you perform your first large object operation, like this:

db.SQLExecute "BEGIN TRANSACTION"

After you have performed your last large object operation, you should close the transaction, like this:

db.SQLExecute "END TRANSACTION"

Please see the PostgreSQLLargeObject class for information on how to work with large objects.


Listen and Notify Protocol

The PostgreSQLDatabase class implements the listen and notify protocol of PostgreSQL databases.

To send a notification, call the PostgreSQLDatabase.Notify method with the name of the notification you want to send. For example, if you wanted to send a notification called "Hello World", you would call Notify like this:

Dim db as New PostgreSQLDatabase
//connection code here
db.Notify "Hello World"

To check for notifications, call the PostgreSQLDatabase.CheckForNotifications method. You will receive notifications as a PostgreSQLDatabase.ReceivedNotification event. The ReceivedNotification event is called with three arguments: the name of the notification as a String, the ID of the process sending the notification as an Integer, and an extra argument that the PostgreSQL documentation says is not used at this time. The name parameter is the same name that you used with the Notify method.

If you would like to check for notifications automatically, at some set interval, then use a Timer and call CheckForNotifications in the Timer's Action event.

In order to implement the ReceivedNotification event, you will need to either instantiate a PostgreSQLDatabase object on a Window, or you will need to subclass PostgreSQLDatabase.

Accompanying the PostgreSQL plug-in are two simple projects, Notify and Listen, that demonstrate how to send notifications and how to listen for them. Listen implements ReceivedNotification by instantiating a PostgreSQLDatabase object on Window1.


Examples

This example opens an existing PostgreSQL database.

Dim db as PostgreSQLDatabase
db=New PostgreSQLDatabase
db.host="192.168.1.172"
db.port=5432
db.DatabaseName="myDatabase"
db.Username="Charlie"
db.Password="mashie"
If db.connect then
 //proceed with database operations
else
MsgBox "The connection failed."
end if


See Also

Database, DatabaseRecord, PostgreSQLLargeObject, RecordSet classes.