HRestorePosition (Function)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Help / WLanguage / Managing databases / HFSQL / HFSQL functions

Reinitializing positions
Miscellaneous
Repositioning principle for Native Connectors (also called Native Access)

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

HRestorePosition (Function)

In french: HRetourPosition

Not available with this kind of connection

Restores the previously saved context of a data file (HSavePosition): current record, filter, pointers.

HRestorePosition is used to restore:

the number of the record used,
the different pointers in the index (the position in the index is saved for each key),
the current filter (only if the hRPFilter constant is specified).

This function can be used with the data files, HFSQL views or queries.

Example

// Find a record
HReadSeekFirst(Customer, Name, Name)
WHILE HFound(Customer) = True
// Saves the current context
nPos = HSavePosition(Customer, Name)
// Check a customer with another name
HReadSeek(Customer, Name, Name2)
IF HFound() = True THEN Counter = Counter + 1
// Restores the context
HRestorePosition(nPos)
HReadNext(Customer, Name)
END

Syntax

Restoring the specified position Hide the details

<Result> = HRestorePosition(<Position> [, <Option>])

<Result>: Boolean

True if the specified position was restored,
False otherwise. HError returns more details about the problem.

<Position>: Integer

Position to restore. Value returned by HSavePosition.

<Option>: Optional constant (or combination of constants)

Used to configure the restore operation:
hRPDefault
(default value) The position is freed. The stored position is restored.
hRPFilter Restores the filter implemented during the call to HSavePosition.
hRPHF5 If the stored position was deleted or modified, this position is still restored.
If the hRPHF5 constant is not specified and if the backup was performed on several items, the positioning is performed according to the current record number during the call to HSavePosition.
This constant is not supported.

Access by JDBC: This constant is not supported.
hRPKeep The position is not freed (other calls to HRestorePosition can be performed on this position).
This parameter is ignored: the position will be saved for all items being looped through.

Restoring a data file Hide the details

<Result> = HRestorePosition([<Data file>])

<Result>: Boolean

True if the context has been restored,
False otherwise. HError returns more details about the problem.

<Data file>: Optional character string

Name of the data file whose context is to be restored. If this name is not specified, HRestorePosition will use the last data file used by the last HFSQL function (function starting with "H").

Remarks

Reinitializing positions

Caution: all the functions that open or close a data file reinitialize the context numbers (HCreation, HClose, etc.).

If the record saved by HSavePosition was deleted, HRestorePosition keeps the current context but it will position on the record following the deleted record.

When reinitializing a browse, the positions saved on this browse are destroyed. The HFSQL engine uses the value of best item to attempt a new positioning. The best item is selected in the following preference order:

Automatic identifier
Unique key
First key
First item

The following functions reinitialize the iteration:

Miscellaneous

The number of calls to HSavePosition is not limited.
You can nest HSavePosition and HRestorePosition for the same data file.

Repositioning principle for Native Connectors (also called Native Access)

The record is restored from the internal cache of the Native Connector.

Caution: during the restore operation, no check is performed regarding the existence of record in the database (the record may have been deleted).

You have the ability to "force" the reading on the database by using HRead after HRestorePosition. In this case:

the record values will be read again in the database.
if the record has been deleted, the Native Connector will return error 13: The current record cannot be found. It was modified or deleted from the data source.

Special cases: Native MySQL, DB2 and Informix Connectors: After the call to HRestorePosition, HReadNext and HReadPrevious generate a query to find the record following or preceding the restored record.

Business / UI classification: Business Logic

Component: wd300hf.dll