| Chapter 6. The Superbase Micro Engine (SBME) Component | ||
|---|---|---|
 | Part II. C-Language Components |  |
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]](images/note.png) | 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 filenameactionerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| filename | None | string | 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 | .nul | integer |
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
| Property | Type | Description |
|---|---|---|
| _ | 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. |
| cachesize | integer | 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. |
| committype | string |
Contains either "auto" or "", where
"auto" commits after every operation that writes
and "" requires an explicit call to the
commit() method.
|
| filename | string | Contains the name of the file. |
| locktype | string |
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.
|
| type | type | 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
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| error | .nul | integer |
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 tablenameerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| tablename | None | string | The name of the table to be deleted. |
| error | .nul | integer |
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 tablenameerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| tablename | None | string | The name of the table for which the sbme1newtable object is to be retrieved. |
| error | .nul | integer |
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 tablenamespatternerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| tablenames | None | array | 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 | .nul | integer |
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 locktypeerror
Parameters
| Parameter | Default value | Type name | Description | |||
|---|---|---|---|---|---|---|
| locktype | None | string |
Contains the type of lock to be acquired on the associated resource.
This must be either
| |||
| error | .nul | integer |
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.
|
![[Important]](images/important.png)
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
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| tablename | None | string | 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 tablenamerecordidfieldnameerror
Parameters
| Parameter | Default value | Type name | Description | |||
|---|---|---|---|---|---|---|
| tablename | None | string | 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 | .nul | string |
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
| |||
| error | .nul | integer |
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.
|
![[Warning]](images/warning.png)
renamefield()
Description
Renames a field in a named database table to a new name.
Prototype
sbme1var.renamefield (
string tablenamefieldnamenewfieldnameerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| tablename | None | string | The name of the data table that contains the field to be renamed. |
| fieldname | None | string | The name of the field that is to be renamed. |
| newfieldname | None | string | The new name of the field. |
| error | .nul | integer |
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 tablenamenewtablenameerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| tablename | None | string | The name of the data table to be renamed. |
| newtablename | None | string | The new name of the data table. |
| error | .nul | integer |
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
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| error | .nul | integer |
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
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| cachesize | None | integer | 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
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| committype | None | string |
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 tablenamedefinitionerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| tablename | None | string | The name of the table for which the file definition is being set. |
| definition | .nul | sbme1newtable |
The sbme1newtable object that was retrieved to modify the table
definition using the
gettabledefinition() method.
|
| error | .nul | integer |
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
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| error | .nul | integer |
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.
|