| ppcstype1file | ||
|---|---|---|
 | Chapter 5. The Peer-to-Peer Client/Server (PPCS) Component |  |
ppcstype1file
Description
Objects of type ppcstype1file represent a database file on a
PPCS server, and provide the necessary interface to access the data in
the database. Objects of this type also do not have a
new() method, since they are created by a call
to the openudpfile() or some other file opening
method of the ppcstype1 object.
Type Tags
db1table
Object Value
Objects of type ppcstype1file 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. |
| codepage | integer | Contains the OEM codepage number that the PPCS server is assumed to be using. |
| filename | string | Contains the name of the table. |
| firstfield | ppcstype1field | Contains a reference to the ppcstype1field object that represents the first field in the file. |
| firstindex | ppcstype1index |
Contains a reference to the ppcstype1index object that represents
the first index in the file. If there are no indexes on the file then
the reference is .nul.
|
| locked | boolean | Contains a boolean indicator showing whether or not all records in the file have been locked using this ppcstype1file object. |
| ppcstype | ppcstype1 | Contains a reference to the ppcstype1 object used to open the table. |
| recordidfieldname | string | Contains the name of the field (if any) that is the internal record ID field. |
| tablename | string | Contains the name of the table. |
| type | type | Specifies the ppcstype1file type object. |
Methods
lock()
Description
Locks all records in a file. If the attempt to lock all records 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
ppcstype1filevar.lock (
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 object
creation 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 object
creation 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. |
newrecord()
Description
Creates a ppcstype1record object to represent a new (as yet not persistently stored) record in the database table.
Prototype
ppcstype1filevar.newrecord ()
Parameters
None
recordcount()
Description
Returns the number of records in a file. If the attempt to get the current
record count is successful then that count 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 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
ppcstype1filevar.recordcount (
boolean geterrorerrortextretrytimeout
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| get | .false | boolean |
If .false then the most recent value that the object
already has is returned. If get is .true then
a PPCS operation is performed to determined the very latest
value for the record count.
|
| 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 object
creation 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 object
creation 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 first or the last record in a PPCS database file. The
selection does not depend on any index or on the position of any
other 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
ppcstype1filevar.select (
boolean lastrecordlockerrorerrortextretrytimeout
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| lastrecord | .false | boolean |
If .false then the first record in the file is selected. If
.true then the last record in the file 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 object
creation 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 object
creation 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. |
serial()
Description
Returns the current serial number for a file. If the attempt to get the serial
number is successful then that count 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
ppcstype1filevar.serial (
boolean incrementerrorerrortextretrytimeout
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| increment | .false | boolean |
If .false then the serial number is returned without being
modified. If increment is .true then the value
is incremented before it is retrieved, thus ensuring that the
number retrieved is not the same as any serial number that has
been retrieved previously.
|
| 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 object
creation 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 object
creation 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 all records in a file after they have been locked using
ppcstype1file.lock(). If the attempt to unlock all
records 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
ppcstype1filevar.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 object
creation 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 object
creation 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. |
ppcstype1file!
Get
The member operator followed by the name of the field will return a reference to the ppcstype1field object. If the name provided is not correct (including case-sensitivity), then an error will occur.
Set
Attempting to assign a reference or a value to a ppcstype1file object using the ! operator is not supported.