ppcstype1index

ppcstype1index
	Chapter 5. The Peer-to-Peer Client/Server (PPCS) Component

Description

Objects of type ppcstype1index represent an index for a database file on a PPCS server, and provide information that may be needed about the index.

Type Tags

db1index

Object Value

Objects of type ppcstype1index 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.
field	ppcstype1field	Contains a reference to the ppcstype1field object upon which this index is based. For a ppcstype1file all indexes are on exactly one field.
file	ppcstype1file	Contains a reference to the ppcstype1file object for the file that contains this index. This is the same as the table property.
next	ppcstype1index	Contains a reference to the next `ppcstype1index` object for the table. The ppcstype1index objects for a file form a closed loop that is linked by this property.
table	ppcstype1file	Contains a reference to the ppcstype1file object for the file that contains this index. This is the same as the file property.
type	type	Specifies the ppcstype1index type object.
unique	boolean	If `.true` then the index contains only unique key values, otherwise duplicate values are allowed and the property value is `.false`.

Methods

select()

Description

Selects either the first or the last record in a PPCS database file according to this index. The selection does not depend 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

ppcstype1indexvar.select ( boolean lastrecord, boolean lock, integer error, string errortext, integer retry, integer timeout )

Parameters

Parameter	Default value	Type name	Description
lastrecord	`.false`	boolean	If `.false` then the first record in the index order is selected. If `.true` then the last record in the index 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.

selectkey()

Description

Selects a record according to the location of a specified value in the index. The selection does not depend 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 object provided. If an exact match is not found, but the found parameter and the error or errortext parameters are provided, then no error will be generated, the found parameter will be set to .false and the next closest matching record in the index will be returned. Providing the lock parameter will allow the record to be selected with a lock.

Prototype

ppcstype1indexvar.selectkey ( string | integer | number value, boolean lock, integer error, string errortext, integer retry, integer timeout, boolean found )

Parameters

Parameter Default value Type name Description

value

.nul

string | integer | number

If .nul then a search will be made for the first record in the index order where the value is empty. If the index is a string then a value passed of this type will be sought for in the index. If the index is of type integer, date, or time then an integer value passed in this parameter will be sought in the index. If the index is of type number then a numeric value passed in this parameter will be sought in the index.

	Warning
	It is important to be aware that tables with numeric indices may not always resolve reliably when accessed from different machines on different operating systems or hardware because of the differences in the way that floating point values may be calculated. For this reason it would be wise to migrate this type of index to string or integer.

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.

found .nul boolean This must be a boolean object that will be set to .true if an exact match is found and if an exact match is not found, then it will be set to .false.