ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WLanguage / Managing databases / HFSQL
  • Overview
  • Principle of assisted management
  • Principle
  • Remarks
  • Standard operating mode
  • Duplicate error
  • Integrity error
  • Password error
  • Error of modification conflict and error of modification status conflict
  • Lock error
  • Required input (database accessed via OLE DB)
  • Reindexing in progress
  • Automatic reconnection to HFSQL server
  • Customization
  • The different solutions
  • Implementation
  • Examples of windows or pages that can be easily included in your applications
  • Constants used to customize the errors
  • Disabling the assisted management
  • Overview
  • Implementation
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Others
Stored procedures
Assisted HFSQL error handling
ODBCNot available with this kind of connection
Overview
WINDEV and WEBDEV include a module for assisted management of HFSQL errors. A specific window or page is automatically displayed for the following types of errors:
The different error cases that may occur must be checked after each HFSQL function that handles a data file. If this check is not performed, a WLanguage error is generated and the application stops.
HOnError is used to customize the assisted management of errors or to disable this management. For each type of error, you can:
  • Manage this error via a specific window/page or via a procedure (for more details, see Managing an HFSQL error via a procedure).
  • Disable the assisted management and manage the error through programming (like in WINDEV 5.5).
WEBDEV - Server code In WEBDEV, the assisted management of errors is not available for the static pages, the semi-dynamic pages, the PHP pages, the Active WEBDEV Pages and the Ajax pages.
iPhone/iPad In the iPhone or iPad applications, you only have the ability to customize the management of errors with HOnError. No window for error management is displayed by default: the error must be processed in any case.
AndroidAndroid Widget Java In the Java, Android or Android widget applications, you only have the ability to customize the error for automatic reconnection to the HFSQL server with HOnError. Only the window for automatic reconnection to the HFSQL server is displayed by default. For all the other errors, you must process the error.
Related Examples:
WD Detecting HFSQL Errors Training (WINDEV): WD Detecting HFSQL Errors
[ + ] This educational example, powered by WINDEV, presents the module for assisted management of HFSQL errors:
Duplicate, Integrity, Lock, Password, Modification conflict.
This example presents:
- the default operating mode,
- the different methods for customizing this assisted management.
WD Managing HFSQL Errors Training (WINDEV): WD Managing HFSQL Errors
[ + ] The "WD Managing HFSQL Errors" example presents the management of HFSQL errors (duplicate, integrity).
This example explains how to customize the process when an error occurs.
Principle of assisted management

Principle

To simplify data file management programming, the most common types of errors are automatically managed by the HFSQL engine.
This automatic management helps the user process the error. In most cases, the error is caused by a problem involving the data entered.
This automatic management is proposed by default and it can be customized or disabled.

Remarks

The assisted management of errors is available for data files in Hyper File Classic and Hyper File 5.5 format, for data files used via a Native Connector (also called Native Access) and for data files used via an OLE DB provider.
If your data files are handled via an OLE DB provider, only the following elements are managed:
  • The duplicate errors
    Caution: Some duplicate errors may not be recognized as such by the OLE DB access. These errors will not be managed as duplicates errors but they will be considered as being fatal errors. Example: the WINDEV analysis and the description of the external database are out-of-synch and the description of the data file in the analysis does not contain all the unique keys defined in the database.
  • Required input errors
    Caution: the required input error message appears only if the OLE DB provider indicates that the item is associated with the "NULL forbidden" property. Otherwise, the error will be processed like a fatal error.
If your data files are handled via a Native Connector, the management of mandatory passwords is not available.
Standard operating mode

Duplicate error

  • Error cause
    The user adds a record for which the value of a unique key already exists.
    For example, the zip code and the name of the state are defined as unique keys in the Cedex file. A duplicate error occurs when adding a state whose number is already found.
  • Default assisted management available in WINDEV, WINDEV Mobile and WEBDEV
    If a duplicate error is detected, a window or a page is displayed, asking the user to modify the value of the record that caused the error.
  • Processing the error
    Check the result of HErrorDuplicates after each call to an HFSQL function that may trigger a duplicate error (HAdd or HModify for example). The error details are returned by HErrorInfo.

Integrity error

  • Error cause
    The user tries to add a record without respecting the integrity constraints defined between the files in the analysis.
    For example, the files named CEDEX, STATE and REGION are linked between themselves. These links comply with the relational integrity constraints. An integrity error occurs when adding a state without creating the corresponding region.
  • Default assisted management available in WINDEV, WINDEV Mobile and WEBDEV
    When an integrity error occurs, a window or a page is displayed, asking the user to cancel the operation or to modify the data entered.
  • Processing the error
    Check the result of HErrorIntegrity after each call to an HFSQL function that may trigger a duplicate error (HAdd or HModify for example). The error details are returned by HErrorInfo.

Password error

  • Error cause
    The program tries to handle a password-protected file (opening, first read operation, ...). The password was not specified through programming: a password error occurs.
  • Default assisted management available in WINDEV, WINDEV Mobile and WEBDEV
    When a password error occurs, a window or a page is displayed, allowing the user to type the file password.
  • Processing the error
    Check the result of HErrorPassword after each call to an HFSQL function that may trigger a password error (HOpen for example or from the first HFSQL function that uses the file). The error details are returned by HErrorInfo.

Error of modification conflict and error of modification status conflict

  • Error cause
    When using an application in network, conflicts may occur because of conflicting data entered by the different users.
    For example:
    1. The user X edits the form of "California".
    2. The user Y edits the form of "California".
    3. The user X renames the state to "California_01".
    4. The user Y modifies the name of the state ("California_02") and saves. A modification conflict occurs during this backup.
      A modification conflict occurs.
      A conflict of modification status occurs when the form is deleted by the user X for example.
      The different cases are presented in the table below:
      CrossedModification status conflictModification conflictModification conflict
      DeletedModification status conflictModification status conflictXXXX
      EnabledModification conflictModification conflictModification conflict
      Record on disk
      Record readEnabledCrossedDeleted
  • Default assisted management available in WINDEV, WINDEV Mobile and WEBDEV
    • If a conflict occurs when a record is modified, a window is displayed, proposing the possible values for the record:
      • the value read in the file (before modification).
      • the value modified by another user.
      • the value entered by the current user.
        Then, the user can choose the value of the item that will be saved.
    • If a conflict occurs when modifying a record, a window is displayed, allowing the user to:
      • re-enable the deleted data.
      • keep the data in its current status.
        Then, the user can choose the value of the item that will be saved.
  • Processing the error
    • For modification conflict errors, check the result of HErrorModification after each call to an HFSQL function that may trigger this error (HModify for example). The error details are returned by HErrorInfo.
    • For modification status conflict errors, check the result of HErrorStatusModification after each call to an HFSQL function that may trigger this error (HModify for example). The error details are returned by HErrorInfo.

Lock error

  • Error cause
    In a network application, you have the ability to lock a record or a file in order to perform specific operations for example.
    A lock error occurs when a network computer tries to access a locked record.
  • Default assisted management available in WINDEV, WINDEV Mobile and WEBDEV
    When a lock error occurs, the management of locks (checking whether the file is locked, processing the lock) is automatically performed by the HFSQL engine.
    A window or a page is displayed, indicating that the record or file is locked and allowing the user to retry or cancel the operation. In case of cancellation, the application continues to run as usual.
  • Processing the error
    Check the result of HErrorLock after each call to an HFSQL function that may trigger a lock error.

Required input (database accessed via OLE DB)

  • Error cause
    Some file items necessarily expect a value. If no value was entered, a required input error message appears.
  • Default assisted management available in WINDEV, WINDEV Mobile and WEBDEV
    If no value was entered, the HFSQL engine automatically opens a window to enter the required value.
    A window is displayed, indicating that the item must be filled and allowing the user to type the item value.
  • Processing the error
    The error number associated with this problem is 70710: Mandatory item value.
    These error numbers are returned by HError.

Reindexing in progress

  • Error cause
    The file used is currently reindexed. The file cannot be used (read, write) during this reindex operation.
  • Default assisted management available in WINDEV, WINDEV Mobile and WEBDEV
    A window is displayed, indicating that the file is currently reindexed (also called reorganization). This window is displayed during the entire reindex operation and it cannot be closed. A progress bar indicates the status of re-index operation.

    WINDEV Remark: To avoid the blinking effects, the reindex windows (automatic window or maintenance by another computer) are displayed only if the reindex operation may exceed 2 seconds. In this case, the reindex windows are displayed after 0.7 seconds. This mechanism is not applied to the windows used by HOnError. To include this mechanism in your custom windows, see the code of the "Reindex.wdw" window available in the "\HyperFileSQL - Automatic Help Windows" directory.
  • Processing the error
    The error number associated with this problem is 70720: A reindex operation is currently performed on the file
    These error numbers are returned by HError.

Automatic reconnection to HFSQL server

The automatic reconnection feature is very useful because it deals with the disconnection of the current connection.
Typically, this problem arises with devices with unstable connections to the server (mobile devices in particular, Wi-Fi, 3G, etc.). With a Wi-Fi connection for example, the link between the remote device and the server can be interrupted for a short duration. This type of break may also happen on the standard wired networks.
Once the application is "connected" again, it is useful to resume the application where the communication was interrupted. The buffers must be properly specified. With the automatic resuming of the connection, all the buffers are stored and reassigned. The application can resume without any error, as if the connection was never interrupted.
  • Error cause
    The application hast lost one or more connections with one or more HFSQL servers. The possible reasons can be:
    • loss of GPRS link,
    • intervention on the network,
    • update of the server,
    • crash of the server,
    • standby of the client computer.
  • Default assisted management available in WINDEV, WINDEV Mobile and WEBDEV
    When the client application does not have access to the server anymore, a window or a page is automatically displayed, indicating that the connection with the server is no longer available. This window tries to reconnect on a regular basis. When the server is available again, the reconnection is automatically performed and the window disappears. The user can continue to use the application.
    To implement the automatic reconnection, you must:
    • recompile the client application (version greater than 15).
    • install the HFSQL Client/Server server (version greater than 15).
  • Processing the error
    This error is a fatal error.
Caution: The automatic reconnection cannot be performed in the following cases:
  • The application includes a transaction in progress.
  • The application has locked a file (in read/write).
  • The application has locked a file in read/write mode and another application has modified a record of this file when the application was not connected.
  • The lock was performed by one of the following functions: HFirst, HNext, HPrevious or HLast.
Customization

The different solutions

WINDEV, WEBDEV and WINDEV Mobile give you the ability to customize the management of HFSQL errors.
You can:
  • use the custom procedures.
    A specific procedure of your application is automatically run as soon as an HFSQL error occurs.
    Remark: A procedure can be defined for each file and for each type of error.
  • use custom windows or pages: the standard windows and pages of the HFSQL engine are replaced with the windows or pages of your application.
    Remark: A window or a page can be defined for each file and for each type of error.
WINDEVWEBDEV - Server codeWindowsiPhone/iPadHFSQL ClassicHFSQL Client/ServerHyper File 5.5OLE DBNative Connectors (Native Accesses)

Implementation

To implement the assisted custom management of HFSQL errors, you must:
  1. For each type of error, create the procedure, the window or the page used to customize the error. The same window, page or procedure can manage several types of errors. This window, page or procedure must return a specific constant according to the process to perform (see the paragraph below).
  2. Define the customization of errors with HOnError.
WINDEVWEBDEV - Server codeWindowsHFSQL ClassicHFSQL Client/ServerHyper File 5.5OLE DBNative Connectors (Native Accesses)

Examples of windows or pages that can be easily included in your applications

The error windows and pages used by default and presented in the previous paragraphs are supplied (with their WLanguage code) for information.
WINDEV For WINDEV, these windows are available in the "\Programs\Data\Preset Windows\HyperFileSQL - Automatic Help Windows" directory.
WEBDEV - Server code For WEBDEV, these pages are available in the "\Programs\Data\Preset pages\HyperFileSQL - Automatic Help Pages" directory.
Type of errorWINDEV windowWEBDEV page
Duplicate errorDuplicate.wdwDuplicate_WB.wwh
Integrity errorIntegrity.wdwIntegrity_WB.wwh
Password errorPassword.wdwPassword_WB.wwh
Error of modification conflict and error of modification status conflictModif.wdw
ModifStatus.wdw
Modif_WD.wwh
ModifStatus_WB.wwh
Lock errorLock.WDWLock_WB.wwh
Required inputMandatoryInput.WDW
Reindex in progressReindexing.WDWReindexing_WB.wwh
Automatic reconnectionReconnection.WDWReconnection_WB.wwh

These windows or pages can be included in your projects, they can be customized, translated and passed as parameter to HOnError.
To include these windows/pages in your projects: on the "Project" tab, in the "Project" group, expand "Import" and select "WINDEV/WEBDEV/WINDEV Mobile elements and their dependencies".
WINDEVWEBDEV - Server codeWindowsiPhone/iPadHFSQL ClassicHFSQL Client/ServerHyper File 5.5OLE DBNative Connectors (Native Accesses)

Constants used to customize the errors

The procedure, the window or the page used to customize the error must return one of the constants found in the table below.
The corresponding process will be run according to the constant returned.
opCancelThe function that triggered the error returns an error as if the assisted management was disabled.
Remark: For the errors of loss of connection, the error is fatal.
opEndProcessThe function that triggered the error returns an error and the current process stops. Equivalent to the following line of code:

IF NOT <HFSQL function> THEN SetFocusAndReturnToUserInput()
AndroidAndroid Widget Java This constant is not available.
opEndProgramThe function that triggered the error returns an error and the program stops. Equivalent to the following line of code:

IF NOT <HFSQL function> THEN EndProgram()
opRelaunchProgramEnds the application and automatically restarts the application.
iPhone/iPad This constant is not available.
opRetryThe function that triggered the error is re-run.
iPhone/iPad This constant is not available.

Remarks:
  • Customizing the modification errors: If the procedure, the window or the page called during the modification conflict returns the opRetry constant without doing nothing anything else, the values will be written into the file without triggering a new modification conflict.
  • To differentiate between a modification conflict and a status conflict, use HErrorStatusModification.
Disabling the assisted management

Overview

WINDEV, WEBDEV and WINDEV Mobile allow you to entirely disable the system for automatic management of errors. In this case, the different error cases that may occur must be checked in the application. If this check is not performed, a WLanguage error is generated and the application stops.

Implementation

To entirely disable the automatic management of errors, simply use HOnError and specify an empty string for the name of the window, page or procedure.
In this case, after each HFSQL function that can cause an error, it is necessary to check the result of one or more of the following functions:
HErrorDuplicatesChecks if a duplicate error has occurred.
HErrorIntegrityChecks if an integrity error has occurred.
HErrorLockChecks if a lock error has occurred.
HErrorPasswordChecks if an error has occurred due to a wrong password.
HErrorStatusModificationReturns the status of a record during a modification conflict.

The error details are returned by HErrorInfo.
The assisted management can be re-enabled by HOnError
Remark: For other errors (modification, required input, re-indexing in progress), no check is needed. The error numbers associated with these problems are:
  • 70700: Modification conflict
  • 70710: Mandatory item value
  • 70720: A re-index operation is currently performed on the file
These error numbers are returned by HError.
Related Examples:
WD Who is locking Training (WINDEV): WD Who is locking
[ + ] This example explains how to notify to the users of a HFSQL database in network "who" is locking an inaccessible record.

The following topics are presented in this example:
1/ management of concurrent accesses
2/ automatic refresh by timer
3/ management of a "system" file to store information about the locks.

Summary of the example supplied with WINDEV:
This example, powered by WINDEV, includes 2 projects:
- WD Who is locking: test application that manages a "client" file in network
- WD Supervisor of locks: management tool used to view the existing locks and to force the unlocking if necessary.
An edit form may have been left opened by a user for quite a long time ; this may interfere with the other users.
The 'Free' button sends a message to the relevant user and asks him to free the record.
The 'Unlock!' button is used to force the unlocking of the record.
Caution: This operation will send a message forcing the closing of the application that performed the lock.
WD Managing HFSQL Errors Training (WINDEV): WD Managing HFSQL Errors
[ + ] The "WD Managing HFSQL Errors" example presents the management of HFSQL errors (duplicate, integrity).
This example explains how to customize the process when an error occurs.
Minimum version required
  • Version 9
This page is also available for…
Comments
Click [Add] to post a comment

Last update: 09/07/2023

Send a report | Local help