| sbme1record | ||
|---|---|---|
 | Chapter 6. The Superbase Micro Engine (SBME) Component |  |
sbme1record
Description
Objects of type sbme1record represent a record in a database table in an SBME database file. Using objects of this type a SIMPOL program may interrogate or modify the values in a record, or create or delete records.
Type Tags
db1record
Object Value
Objects of type sbme1record have no value, and it is an error to try to get or set this value.
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. |
| index | sbme1index | Contains a reference to the sbme1index object that was used to locate this record, that is the sbme1index object that was used to select the record, or the sbme1index object associated with the sbme1record object used to select the record. |
| 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.
|
| stored | boolean | This is a read-only property indicating whether or not the record has been read from or stored in the file by, or during the creation of, this record object. It is not foolproof as the record may have been deleted by a different record object or user. |
| table | sbme1table | Contains a reference to the sbme1table object for the table that contains this record. |
| type | type | Specifies the sbme1record type object. |
Methods
delete()
Description
Deletes a record that has previously been selected with a lock. This can only
be done to a record that has been selected with a lock or where all
records in the file are locked. After being deleted a record can be
saved again; this will create a new record in the file. If the
attempt to delete a record 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
sbme1recordvar.delete (
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.
|
get()
Description
Returns the value for the specified field in a record.
Prototype
sbme1recordvar.get (
sbme1field field
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| field | None | sbme1field | The field for which to return the record data. The data is returned as a type that is compatible with the datatype of the field. Fields of the data types date, time, and datetime are all treated as integers. |
put()
Description
Assigns a value to a specified field in a record.
Prototype
sbme1recordvar.put (
sbme1field fieldvalue
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| field | None | sbme1field | The field to which to assign record data. |
| value | .nul | string | integer | number | boolean | blob |
If .nul then an empty value will be assigned to the field
in the record. In the case of the normal value types, they will
be assigned to the field if they are compatible to the data type
of the field.
|
save()
Description
Saves a record that may have been modified or may have been new. If the record
is a modified record then it must have been selected with an
exclusive lock before the modifications were made or all records in
the file must be locked. If the attempt to save a record 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
sbme1recordvar.save (
string locktypeerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| locktype | "" | string |
If "shared" or "exclusive" then the
record is saved with a lock of the associated type. An exclusive
lock is required if the record is to be modified or deleted, and
at least a shared lock is required if modification or deletion by
others is to be prevented. These can also be accomplished by
virtue of holding an exclusive lock on the
sbme1table or the sbme1.
|
| 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 the SBME operation 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.
|
select()
Description
Selects either the next or the previous record in an SBME database table
according to the same index, if any, used to select this record. If
the attempt to select a record is successful then a reference to an
object of type sbme1record 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. Providing the
locktype parameter will allow
the record to be selected with either a shared or exclusive lock.
Prototype
sbme1recordvar.select (
boolean previousrecordlocktypeerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| previousrecord | .false | boolean |
If .false then the next record in the relevant order is
selected. If .true then the previous record in
the relevant order is selected.
|
| locktype | "" | string |
If "shared" or "exclusive" then the
record is selected with a lock of the associated type. An
exclusive lock is required if the record is to be modified or
deleted, and at least a shared lock is required if modification
or deletion by others is to be prevented. These can also be
accomplished by virtue of holding an exclusive lock on the
sbme1table or the sbme1.
|
| 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.
|
selectcurrent()
Description
Reselects a record in an SBME database table and optionally allows the new
record object to be based on a different index. If the attempt to
select a record is successful then a reference to an object of type
sbme1record 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. Providing the locktype parameter will allow the record
to be selected with either a shared or exclusive lock.
Prototype
sbme1recordvar.selectcurrent (
sbme1index indexlocktypeerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| index | .nul | sbme1index |
If .nul then the new record will be considered to have been
positioned sequentially in the file, that is, without an index,
otherwise, the record will be considered to have been positioned
using the index provided.
|
| locktype | "" | string |
If "shared" or "exclusive" then the
record is selected with a lock of the associated type. An
exclusive lock is required if the record is to be modified or
deleted, and at least a shared lock is required if modification
or deletion by others is to be prevented. These can also be
accomplished by virtue of holding an exclusive lock on the
sbme1table or the sbme1.
|
| 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.
|
unlock()
Description
Unlocks a record that has previously been selected with either a shared or
exclusive lock. This can only be done to a record that has been
selected with a lock. Any modifications in the record will not be
able to be saved after it has been unlocked. If the attempt to unlock
a record 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
sbme1recordvar.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.
|
sbme1record!
Get
The member operator followed by the name of the field will return the value of the field content in the record object. If the name provided is not correct (including case-sensitivity), then an error will occur.
Set
If the member operator followed by the name of the field is on the left side of an assignment (=), then the value of the right side of the statement will be assigned to the field in the record that is referenced by the field name. If the name provided is not correct (including case-sensitivity), then an error will occur.