| ppcstype1record | ||
|---|---|---|
 | Chapter 5. The Peer-to-Peer Client/Server (PPCS) Component |  |
ppcstype1record
Description
Objects of type ppcstype1record represent a record in a database file on a PPCS 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 ppcstype1record 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. |
| file | ppcstype1file | Contains a reference to the ppcstype1file object for the database file that contains this record. This is the same as the table property. |
| index | ppcstype1index | Contains a reference to the ppcstype1index object that was used to locate this record, that is the ppcstype1index object that was used to select the record, or the ppcstype1index object associated with the ppcstype1record object used to select the record. |
| locked | boolean | This is a read-only property indicating whether or not the record has been locked by, or during the creation of, this record object. This is not a foolproof way of determining whether or not the record in the file is locked, since any other record object for the same record may have it locked. |
| 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 | ppcstype1file | Contains a reference to the ppcstype1file object for the database file that contains this record. This is the same as the file property. |
| type | type | Specifies the ppcstype1record 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 neither the
error nor the errortext parameter is provided then an
error is raised. If the attempt is not successful and the error or the errortext parameter is provided then
.nul is returned and error information is output
in the error object provided.
Prototype
ppcstype1recordvar.delete (
integer errorerrortextretrytimeout
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 and errortext is not specified or is
.nul then any error that occurs during the
PPCS operation 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.
|
| errortext | .nul | string |
Specifies an object that is used to output any error text generated during the
execution of the method. This parameter must be an object, not a
string value. If error is
not specified or is .nul and errortext is not specified or is
.nul then any error that occurs during PPCS
operation 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.
|
| retry | 1000000 | integer | The number of microseconds between retries, if the operation is not successful immediately. |
| timeout | 5000000 | integer | The number of microseconds allowed for the operation to complete before it is assumed that it will fail. |
get()
Description
Returns the value for the specified field in a record.
Prototype
ppcstype1recordvar.get (
ppcstype1field field
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| field | None | ppcstype1field | 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 and time are treated as integers. |
put()
Description
Assigns a value to a specified field in a record.
Prototype
ppcstype1recordvar.put (
ppcstype1field fieldvalue
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| field | None | ppcstype1field | The field to which to assign record data. |
| value | .nul | string | integer | number |
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 a 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 neither the error nor the
errortext parameter is
provided then an error is raised. If the attempt is not successful
and the error or the
errortext parameter is
provided then .nul is returned and error
information is output in the error object
provided.
Prototype
ppcstype1recordvar.save (
boolean lockerrorerrortextretrytimeout
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| lock | .false | boolean |
If .true then the record remains locked after being saved.
If .false then the record will not be locked
after being saved.
|
| 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 the
PPCS operation 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.
|
| errortext | .nul | string |
Specifies an object that is used to output any error text generated during the
execution of the method. This parameter must be an object, not a
string value. If error is
not specified or is .nul and errortext is not specified or is
.nul then any error that occurs during PPCS
operation 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.
|
| retry | 1000000 | integer | The number of microseconds between retries, if the operation is not successful immediately. |
| timeout | 5000000 | integer | The number of microseconds allowed for the operation to complete before it is assumed that it will fail. |
select()
Description
Selects either the next or the previous record in a PPCS database file
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 ppcstype1record is returned. If the
attempt is not successful and neither the error nor the errortext parameter is provided then an
error is raised. If the attempt is not successful and the error or the errortext parameter is provided then
.nul is returned and error information is output
in the error and/or errortext
object(s) provided. Providing the lock parameter will allow the record to
be selected with a lock.
Prototype
ppcstype1recordvar.select (
boolean previousrecordlockerrorerrortextretrytimeout
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.
|
| lock | .false | boolean |
If .true then the record is selected with a lock, which is
necessary if the record is to be modified or deleted, or if
modification or deletion by others is to be prevented.
|
| 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 the
PPCS operation 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.
|
| errortext | .nul | string |
Specifies an object that is used to output any error text generated during the
execution of the method. This parameter must be an object, not a
string value. If error is
not specified or is .nul and errortext is not specified or is
.nul then any error that occurs during PPCS
operation 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.
|
| retry | 1000000 | integer | The number of microseconds between retries, if the operation is not successful immediately. |
| timeout | 5000000 | integer | The number of microseconds allowed for the operation to complete before it is assumed that it will fail. |
selectcurrent()
Description
Reselects a record in a PPCS database file 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
ppcstype1record is returned. If the attempt is not
successful and neither the error nor the errortext parameter is provided then an
error is raised. If the attempt is not successful and the error or the errortext parameter is provided then
.nul is returned and error information is output
in the error and/or errortext
object(s) provided. Providing the lock parameter will allow the record to
be selected with a lock.
Prototype
ppcstype1recordvar.selectcurrent (
ppcstype1index indexlockerrorerrortextretrytimeout
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| index | .nul | ppcstype1index |
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.
|
| lock | .false | boolean |
If .true then the record is selected with a lock, which is
necessary if the record is to be modified or deleted, or if
modification or deletion by others is to be prevented.
|
| 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 the
PPCS operation 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.
|
| errortext | .nul | string |
Specifies an object that is used to output any error text generated during the
execution of the method. This parameter must be an object, not a
string value. If error is
not specified or is .nul and errortext is not specified or is
.nul then any error that occurs during PPCS
operation 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.
|
| retry | 1000000 | integer | The number of microseconds between retries, if the operation is not successful immediately. |
| timeout | 5000000 | integer | The number of microseconds allowed for the operation to complete before it is assumed that it will fail. |
unlock()
Description
Unlocks 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. 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 neither the error nor the
errortext parameter is
provided then an error is raised. If the attempt is not successful
and the error or the
errortext parameter is
provided then .nul is returned and error
information is output in the error and/or
errortext object(s) provided.
Prototype
ppcstype1recordvar.unlock (
integer errorerrortextretrytimeout
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 and errortext is not specified or is
.nul then any error that occurs during the
PPCS operation 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.
|
| errortext | .nul | string |
Specifies an object that is used to output any error text generated during the
execution of the method. This parameter must be an object, not a
string value. If error is
not specified or is .nul and errortext is not specified or is
.nul then any error that occurs during PPCS
operation 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.
|
| retry | 1000000 | integer | The number of microseconds between retries, if the operation is not successful immediately. |
| timeout | 5000000 | integer | The number of microseconds allowed for the operation to complete before it is assumed that it will fail. |
ppcstype1record!
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.