Help / WLanguage / Managing databases / HFSQL
  • Overview
  • Defining an unalterable data file
  • Operations that can be performed (or not) on an unalterable data file
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WindowsLinuxPHPWEBDEV - Browser code
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Stored procedures
Unalterable data files
HFSQL ClassicHFSQL Client/ServerAvailable only with these kinds of connection
This feature is used to signal that a data file cannot be modified after writing. Once a record is added, this record cannot be modified or deleted.
This type of data file is useful in the fields that require a strong traceability. HFSQL automatically signs each record as well as the data file itself.
Making files unalterable:
  • avoids programming errors by preventing modification or deletion (via HModify/HDelete, or via a query).
  • adds a hash of the record content to each record. This hash is an HMAC-SHA256 hash, whose key is derived from the file encryption password.
Remark: To reinforce the security, we advise you to implement a password on the unalterable data file. In this case, the file cannot be created without knowing its password. It will not be possible to delete and re-create the data file without knowing this password.
Defining an unalterable data file
You have the ability to define an unalterable HFSQL data file:
  • in the data model editor:
    1. Open the data file description window (for example, "Description of data file" option in the context menu.
    2. In the "Options" tab, check "Unalterable file (automatically enables enhanced security)".
      Unalterable file
    3. Validate the description of data file. In the data model editor, the unalterable data file is represented with a lock.
  • through programming, by defining a data file dynamically:
    1. Create a variable of type File description.
    2. Use the Unalterable property to define the file unalterability.
    3. Use HDescribeFile to create the file description.
  • If the data file is defined as being unalterable with password, the reinforced security is automatically implemented.
    Reminder: the option "Enable the reinforced security" is used to encrypt the data without storing the encryption key in the data file. With this option and without the file password, the file content cannot be retrieved.
  • If the "Unalterable file" option is implemented on an existing data file, an automatic update of data files will be performed. The existing data file will be compressed (deletion of crossed and deleted records) during this update.
    Caution: As soon as a data file is defined as being unalterable, no automatic data modification can be performed on this file.
  • This option is available from version 23. For the HFSQL Client/Server data files, an HFSQL C/S engine in version 23 (or later) must be used.
Operations that can be performed (or not) on an unalterable data file
The only operations that can be performed on an unalterable data file are the creation and the addition of records.
The authorized functions and features are as follows:
  • HCreation and HCreationIfNotFound.
  • HAdd (outside transaction).
  • HWrite with a record number only if the record number is the one that follows the last record (in this case, an addition is performed).
  • HModify with a record number only if the record number is the one that follows the last record (in this case, an addition is performed).
  • HSave preceded by HReset (in this case, an addition is performed).
  • INSERT queries.
The forbidden functions and features are as follows:
  • HModify, HCross, HWrite, HSave, HDelete, HDeleteAll.
    Indeed, these functions modify the content of data files.
  • UPDATE and DELETE queries.
    Indeed, these queries modify the content of data files.
  • Any modification made to the file content (regardless of the method used).
  • The reindex operation with compression or deletion of damaged records.
    Indeed, this type of reindex operation deletes all inactive or damaged records. Therefore, the data file can be modified.
  • The addition in a transaction.
    Indeed, canceling a transaction triggers the modification of data file.
  • The automatic modification of data files.
    Indeed, modifying the structure of a data file (item addition or deletion for example) can modify the data found in the data file.
    For example, adding an item with a default value will modify all records by adding this new item to them. Similarly, deleting an existing item deletes information from the saved data. The data integrity is guaranteed anymore.
A runtime error occurs if one of these functions or features is used.
Remark: HCheckUnaltered is used to check whether one or all records found in an unalterable data file have not been modified (with a hexadecimal editor for example). Caution: An altered record can be read (if the header is not altered).
How to manage an automatic data modification?
The automatic data file modification is not allowed. When a new application version contain an evolution of structure of records found in an unalterable HFSQL data files, this application version will have to:
  • manage the archiving of data file in its earlier format,
  • create a new data file with the new structure.
Reminder: An application can see the data from an HFSQL data file in an earlier structure by using HCheckStructure in hCompatible mode. If the change of structure makes the file incompatible, you will have the ability to use the archived file in its earlier format with the new application after the call to HDeclareExternal.
Minimum version required
  • Version 23
This page is also available for…
Click [Add] to post a comment

Last update: 06/13/2023

Send a report | Local help