SIMPOL Documentation

Chapter 6. The Superbase Micro Engine (SBME) Component

Provides single-user access to and the ability to create database files in the Superbase Micro Engine database format.

sbme1

Description

Creates a new sbme1 object and either opens or creates a *.SBM file. The action parameter must be provided.

[Note]Note

Since creating this object opens the database file exclusively, it is not possible to create multiple sbme1 objects in a single program that concurrently open the same database file. Instead, store the reference to the opened database file in a utility type and have each portion of the program use the same sbme1 object.

Type Tags

db1base

Object Value

Objects of type sbme1 have no value, and it is an error to try to get or set this value.

sbme1.new()

Description

Creates a new sbme1 object and either opens or creates a .SBM file. The action parameter must be provided.

Prototype

sbme1.new ( string filename, string action, integer error )

Parameters

ParameterDefault valueType nameDescription
filenameNonestring The path, if required, plus the name of the SBME file including the SBM extension that is to be opened or created.
action"O"string The action to take on the filename which must be one of the following characters or combinations of characters: O, R, OC, RC, C. The characters can be upper or lower case. The default value is O. The characters represent the following actions: O=open, R=replace, C=create, OC=open if exists otherwise create, RC=replace if exists otherwise create.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during object creation will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object and the method returns .nul.

Properties

PropertyTypeDescription
_type(*) This property is provided for use by the user to attach any object of any type to the type in which this property is provided.
__type(*) This property is provided for use by the user to attach any object of any type to the type in which this property is provided. It has the additional feature of being marked with the resolve keyword, so that object resolution can continue down this property.
cachesizeinteger Contains the size in bytes of the cache for caching read-only portions of the database. Items that have been modified or created (including indexes, files, fields, and records) are not included in this value until they have been committed since it would be inappropriate to commit them if the cache size were to be exceeded until the program calls the commit function explicitly.
committypestring Contains either "auto" or "", where "auto" commits after every operation that writes and "" requires an explicit call to the commit() method.
filenamestring Contains the name of the file.
locktypestring Contains the type of lock currently held on the associated resource. This can be one of three values: "" (no lock), "shared", or "exclusive". More than one object can hold a shared lock on a lockable entity, but only one object can hold an exclusive lock on a lockable entity.
typetype Specifies the sbme1 type object.

Methods

commit()

Description

This method is used to commit any values written to the database since the last time the commit() method was called, assuming that the database committype is set to "". If instead the committype is set to "auto" then this method has no effect.

Prototype

sbme1var.commit ( integer error )

Parameters
ParameterDefault valueType nameDescription
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during object creation will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object and the method returns .nul.

deletetable()

Description

Deletes a database table from the sbme1 file. This may not be particularly fast depending on the record count, since each record must be deleted individually. The deletion is committed at the end so there must also be sufficient room in memory to hold the changes. This will change at a later date. In any event, if you expect to be deleting and rebuilding large data tables on a regular basis, it may be smarter to use a separate sbme1 file for those tables. That way the file can simply be deleted and the table recreated.

Prototype

sbme1var.deletetable ( string tablename, integer error )

Parameters
ParameterDefault valueType nameDescription
tablenameNonestring The name of the table to be deleted.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

gettabledefinition()

Description

Retrieves a database definition in the form of an sbme1newtable object. Using this the table definition can be modified. See the sbme1new* items for more information.

Prototype

sbme1var.gettabledefinition ( string tablename, integer error )

Parameters
ParameterDefault valueType nameDescription
tablenameNonestring The name of the table for which the sbme1newtable object is to be retrieved.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

gettablenames()

Description

Gets the names of the SBME tables which are available in a specified SBME file. If the attempt to get the table names is successful then .nul is returned. If the attempt is not successful and neither the error nor errortext parameters are provided then an error is raised. If the attempt is not successful and at least one of the error or errortext parameters are provided then .nul is returned and error information is output in the error or errortext objects provided.

Prototype

sbme1var.gettablenames ( array tablenames, string pattern, integer error )

Parameters
ParameterDefault valueType nameDescription
tablenamesNonearray Specifies an object of type array which is used to output the names of the files which are available in the specified SBME file and which match the specified pattern, if any. The first table name, if any, is placed in the array in the position '[1]', the second in position '[2]', and so on. The number of table names retrieved in placed in position '[]'.
pattern""string A pattern used to restrict the table names which will be retrieved. Only names which match the pattern will be output. The matching of a name to a pattern follows the rules for the intrinsic function .like1.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul and errortext is not specified or is .nul then any error that occurs during name retrieval will halt the program. If an error object or errortext object is specified and an error occurs during execution then the error code or text is output into that object and the method returns .nul.

lock()

Description

The lock() method is used to acquire a lock on the sbme1 object. The type of lock can be either shared or exclusive. It is necessary to hold a shared lock on the sbme1 object if a new table is to be created. To prevent the creation of a table, an exclusive lock must be held. To release a lock, call the unlock() method.

Prototype

sbme1var.lock ( string locktype, integer error )

Parameters
ParameterDefault valueType nameDescription
locktypeNonestring

Contains the type of lock to be acquired on the associated resource. This must be either "shared" or "exclusive". It is an error to not specify the locktype parameter.

[Important]Important

This method acquires a lock, it does not change an existing locktype. Therefore it is imperative that the object not be locked before calling this method. It is currently not possible to atomically change a lock between the shared type and the exclusive type; one lock must be released and the next one acquired.

error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during object creation will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object and the method returns .nul.

newtable()

Description

Creates a new database table owned by the database file associated with the sbme1 object for which the method is called. The return value of this call must be assigned to a variable of type sbme1newtable (using the =@ operator). The resulting table is not written back into the database file, that is done by calling the create() method of the sbme1newtable object.

Prototype

sbme1var.newtable ( string tablename )

Parameters
ParameterDefault valueType nameDescription
tablenameNonestring The name of the table to be created. This is not the name of the SBME file, but of the data table within.

opentable()

Description

Opens a database table in the database file associated with the sbme1 object for which the method is called. If the attempt to open the table is successful then a reference to an object of type sbme1table is returned. If the attempt is not successful and the error parameter is not provided then an error is raised. If the attempt is not successful and the error parameter was provided then .nul is returned and error information is output in the error object provided.

Prototype

sbme1var.opentable ( string tablename, string recordidfieldname, integer error )

Parameters
ParameterDefault valueType nameDescription
tablenameNonestring The name of the table to be opened. This is not necessarily the name of the SBME file, but of the data table within.
recordidfieldname.nulstring

The name to use for the exposed internal unique record ID. If this is supplied then the internal record ID will be shown as an indexed unique field where the index is using the algorithm "recordid". The internal record id is read-only and guaranteed for the life of the record in the table. If the table is reorganized, the record ID is likely to change.

[Warning]Warning

Do not store the record ID for future use! The record ID will certainly change if the table is reorganized so it should not be used for any long term purpose. Within the same session and assuming the same database table it can be used for safely reselecting the same record, which makes it an excellent candidate for routines that search for duplicate records and such.

error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during object creation will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object and the method returns .nul.

renamefield()

Description

Renames a field in a named database table to a new name.

Prototype

sbme1var.renamefield ( string tablename, string fieldname, string newfieldname, integer error )

Parameters
ParameterDefault valueType nameDescription
tablenameNonestring The name of the data table that contains the field to be renamed.
fieldnameNonestring The name of the field that is to be renamed.
newfieldnameNonestring The new name of the field.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

renametable()

Description

Renames a database table to a new name.

Prototype

sbme1var.renametable ( string tablename, string newtablename, integer error )

Parameters
ParameterDefault valueType nameDescription
tablenameNonestring The name of the data table to be renamed.
newtablenameNonestring The new name of the data table.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

rollback()

Description

This method is used to rollback any previously written values to the database that have not yet been committed using the commit() method assuming that the database committype is set to "". If instead the committype is set to "auto" then this method has no effect.

Prototype

sbme1var.rollback ( integer error )

Parameters
ParameterDefault valueType nameDescription
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during object creation will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object and the method returns .nul.

setcachesize()

Description

This method is used to set the value of the cachesize property. The value must be supplied. This determines the amount of memory that is used for caching portions of the SBM file.

Prototype

sbme1var.setcachesize ( integer cachesize )

Parameters
ParameterDefault valueType nameDescription
cachesizeNoneinteger The cache size desired. This should not be too small or too large and should only override the default value if truly required. This is limited to a non-negative integer that is less than the total amount of addressable memory for the operating system. On Windows and Linux this is 4GB (Win64 and other 64-bit operating systems will allow considerably higher values but this still should not exceed a reasonable percentage of physical memory).

setcommittype()

Description

This method is used to assign the value of the committype property. The value must be supplied, even if it is the empty string.

Prototype

sbme1var.setcommittype ( string committype )

Parameters
ParameterDefault valueType nameDescription
committypeNonestring The commit method desired. The permitted values are "auto" and "" and one of these values must be supplied to the method.

settabledefinition()

Description

Sets the definition of the named table to be that represented by the definition parameter. Note that fields are matched by name, so if the old table definition has a field called "myfield", and the new definition also has a field called "myfield" then they are assumed to be the same field, so the data in the field will be retained. Any fields not found in the new definition are considered deleted and are lost forever. Any fields in the definition which weren't there before are new fields, which start with no data.

Prototype

sbme1var.settabledefinition ( string tablename, sbme1newtable definition, integer error )

Parameters
ParameterDefault valueType nameDescription
tablenameNonestring The name of the table for which the file definition is being set.
definition.nulsbme1newtable The sbme1newtable object that was retrieved to modify the table definition using the gettabledefinition() method.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

unlock()

Description

Unlocks the sbme1 object that has previously been locked with either a shared or exclusive lock using the lock() method. If the attempt to unlock the database file is successful then .nul is returned. If the attempt is not successful and the error parameter is not provided then an error is raised. If the attempt is not successful and the error parameter is provided then .nul is returned and error information is output in the error object provided.

Prototype

sbme1var.unlock ( integer error )

Parameters
ParameterDefault valueType nameDescription
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during object creation will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object and the method returns .nul.