Table of Contents

OIL2 Class Experimental.PersistentDatabaseViaSQL


class Experimental . PersistentDatabaseViaSQL {
        string  dataColType;
        string  flagColType;
        string  keyColType;
        string  pagerServiceName;
        string  persistentDBtableName;
        oid     sqlODBC;
        string  thisServiceName;
} inherits from Object;

DESCRIPTION

The class PersistentDatabaseViaSQL implements storage of persistent objects using SQL commands on behalf of the PersistenceService. The interface to the database is maintained by an SQLviaODBC object. Only two methods are used, connectToDSN and performSQLcommand, which provides the opportunity for the PersistentDatabaseViaSQL gateway to be used with other relational database interfaces.

The persistent object data is stored in a table (whose name defaults to "PersistentObjects") comprised of 3 columns:

Ideally, the binary data would be stored as-is; unfortunately, expecting generic binary large object support is still just wishful thinking in the year 2002. By default, the binary information is transformed to plain text by converting it to a base64 representation, which yields a 3-to-4 expansion (which is much better than the 1-to-2 expansion which would result with a simple conversion to hexadecimal characters).

Problems discovered:

METHODS


Experimental.PersistentDatabaseViaSQL:create

PersistentDatabaseViaSQL:create()

Method Description

See initialize and initializeFromFile. If a single argument is passed, initializeFromFile is used; if multiple arguments are provided, then initialize is called.


Experimental.PersistentDatabaseViaSQL:initializeFromFile

PersistentDatabaseViaSQL:initializeFromFile(any paramFileArg)

Method Description

The initializeFromFile method permits externalization of parameters using a ParseParameterFile object. The argument paramFileArg is passed as-is as the first argument to the create method.

The following attributes are extracted from the default section:

keyColType
The SQL Type of the objOIDkey column, defaults to VARCHAR.
flagColType
The SQL Type of the restoreFlag column, defaults to INT.
dataColType
The SQL Type of the objData column, defaults to VARCHAR.
alwaysCreate
A Boolean flag that indicates if an attempt to create the table should always be performed; defaults to 0.
serviceName
The name by which the persistent object database should be registered. It must be identical to the argument provided when a corresponding PersistenceService object is created. It defaults to "persistentSQL".
DSN
The Distinguished System Name parameter for an ODBC connection; defaults to "PersistentObjectDatabase".
UID
The User ID to be provided in an ODBC connection; defaults to "vista".
PWD
The password to be provided in an ODBC connection; defaults to "inSecure".

See connectToDSN for details on the 3 ODBC-related parameters. For Oracle, dataColType should be "LONG RAW" (VARCHAR is limited to 4000 characters).

The initialize method is invoked with appropriate arguments after the various configuration parameters have been retrieved from the ParseParameterFile object.

Return Value

A value of 0 is returned on success; -1 indicate an error.


Experimental.PersistentDatabaseViaSQL:initialize

PersistentDatabaseViaSQL:initialize(string serviceName, string DSNname, string userName, string password, optional int32 createDB)

Method Description

The serviceName argument determines the name by which the service will be registered and will need to correspond to an argument provided when a PersistenceService object is created.

The DSNname, userName and password arguments correspond to the critical three required to establish an ODBC-based connection to a database. A SQLviaODBC object is created to interface with the database and these three arguments are sent as the arguments for a connectToDSN method invocation.

If createDB is passed as 1, the necessary database table will be created before the initialization is complete. While not optimal, it is safe to always have this set because the attempt to re-create an existing table will be denied by the database and tolerated by this method.

Return Value

A value of 0 is returned on success; -1 indicate an error.


Experimental.PersistentDatabaseViaSQL:saveObject

PersistentDatabaseViaSQL:saveObject(string oidKey, string objData)

Method Description

Saves the object record in the database.

Return Value

Returns 0 on success.


Experimental.PersistentDatabaseViaSQL:restoreObject

PersistentDatabaseViaSQL:restoreObject(string oidKey)

Method Description

Retrieves an object's state from the database.

Return Value

If the request object does not exist, nil is returned; otherwise, the object's instance data is returned as a string suitable for use by importObject.


Experimental.PersistentDatabaseViaSQL:removeObject

PersistentDatabaseViaSQL:removeObject(string oidKey)

Method Description

Deletes an object's state data from the database.


Experimental.PersistentDatabaseViaSQL:listObjects

PersistentDatabaseViaSQL:listObjects()

Method Description

Returns a list of all objects maintained by the database. Any temporary objects are automatically deleted from the database before the list is generated.

Return Value

The array of objects records will be filled in starting at subscript 0. If no objects are current in the database, the array will be empty. Each individual record is provided as a two element array:
0
the object Id
1
object restore flag (0=always restore; 1=restore on demand, 2=temporary)
Because temporary objects are always deleted before the list is generated, no returned record will every have a restore flag set to 2.


Experimental.PersistentDatabaseViaSQL:stopService

PersistentDatabaseViaSQL:stopService()

Method Description

The stopService method requests termination and deletion of the storage service. It is normally used to request external processes to gracefully terminate and is provided here for compatibility.

Return Value

A value of 1 is returned to indicate the request has been received and processed. The PersistentDatabaseViaSQL object will unregister itself as needed, clean up and delete itself.


Generated: Tue, 23 Aug 2011 00:47:36 EDT
Support Information