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;


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:




Method Description

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


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:

The SQL Type of the objOIDkey column, defaults to VARCHAR.
The SQL Type of the restoreFlag column, defaults to INT.
The SQL Type of the objData column, defaults to VARCHAR.
A Boolean flag that indicates if an attempt to create the table should always be performed; defaults to 0.
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".
The Distinguished System Name parameter for an ODBC connection; defaults to "PersistentObjectDatabase".
The User ID to be provided in an ODBC connection; defaults to "vista".
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.


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.


PersistentDatabaseViaSQL:saveObject(string oidKey, string objData)

Method Description

Saves the object record in the database.

Return Value

Returns 0 on success.


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.


PersistentDatabaseViaSQL:removeObject(string oidKey)

Method Description

Deletes an object's state data from the database.



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:
the object Id
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.



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.