Stores the current context of a data file: current record, filter, pointers. This allows you to temporarily suspend the current process in order for the data file to be used somewhere else (to perform checks for example). The context saved can be restored by
HRestorePosition. Then, the main process can continue.
HSavePosition is used to save:
- 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. You will have to use the hRPFilter constant in HRestorePosition to restore the stored filter.
// 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, LASTNAME)
END
Syntax
<Result> = HSavePosition([<Data file> [, <Item>]] [, <Options>])
<Result>: Integer
- Number of the position that was saved,
- -1 if an error occurred.
<Data file>: Optional character string (with or without quotes)
Name of data file, view or query used. If this name is not specified, HSavePosition handles the last data file used by the last function for HFSQL management (starting with the letter H).
<Item>: Optional character string (with or without quotes)
Name of item used. If this parameter is not specified, HSavePosition saves the positions of all items for which a browse is in progress.
<Options>: Optional integer constant
Used to configure the backup:
| | |
| hSaveItems | Saves the values of items in memory when using HSavePosition. These values will be restored during the call to HRestorePosition. Versions 24 and later New in version 24 | |
Remarks
Example for managing the positions in a data file
HSavePosition and
HRestorePosition can be used in the following cases for example:
- browsing a data file according to a key (form by form), calling another window in order to view in a table. The management of positions allows you to easily go back to the proper record in the form-by-form browse.
- viewing a data file in a Table control, selecting a record for a form-by-form access. The position management allows you to display the Table control again while being properly positioned on the data file.
Reinitializing positions
Caution: all the functions that open or close a data file reinitialize the context numbers (
HCreation,
HClose, etc.).
Various
- The number of calls to HSavePosition is not limited.
- You have the ability to nest HSavePosition and HRestorePosition for the same data file.
- If the record pointed during the call to HSavePosition is deleted, HRestorePosition cannot be called anymore.