HCreationIfNotFound (Function)

ONLINE HELP
FOR WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Help

WLanguage

Management of databases

Characteristics of created data file

The different created files

Managing passwords

Managing fatal errors when creating a data file

Managing non-Latin character sets

Replication: Range of identifiers

Priority for defining the location of log files

Creating or opening an existing table

Managing indexes

Creating the data file from its description

See also

HCreationIfNotFound (Function)

In french: HCréationSiInexistant

Not available with this kind of connection

Performs the following operations:

If the data file does not exist, creates an empty data file (".FIC" extension) with the index file and the memo file if necessary.
The function is equivalent to HCreation.
If the data file exists, opens the data file.
In this case, the function is equivalent to HOpen.
To optimize the call to HCreationIfNotFound, the file opening can also be performed during the first access to the data file (by using the hDelayedOpening constant).

Note: The automatic creation of non-existing data files can be enabled during the project description ("Files" tab of project description, "Automatically create the data files if not found at opening" option). HCreationIfNotFound is automatically used if the data file does not exist when it is handled for the first time.

If the data file is logged, you have the ability to specify the location of log files.

If integrity constraints have been defined and if they are supported, the links are updated by the server when creating the data file.

Versions 15 and later

This function is now available for Android applications.

New in version 15

This function is now available for Android applications.

Versions 17 and later

This function is now available for iPhone/iPad applications.

New in version 17

This function is now available for iPhone/iPad applications.

Versions 18 and later

This function is now available in Android Widget mode.

This function is now available in Windows Store apps mode.

New in version 18

This function is now available in Android Widget mode.

This function is now available in Windows Store apps mode.

This function is now available in Android Widget mode.

This function is now available in Windows Store apps mode.

Versions 21 and later

This function is now available in Universal Windows 10 App mode.

New in version 21

This function is now available in Universal Windows 10 App mode.

Note: From version 19, HFSQL is the new name of HyperFileSQL.

Example

See additional examples

// Create all the data files described in the analysis
// with the "PSW" password
HCreationIfNotFound("*", "PSW")

// Create the Orders file (described in the analysis)
HCreationIfNotFound(Orders)

Syntax

<Result> = HCreationIfNotFound([<File name> [, <Password> [, <Path of JNL file> [, <Path of JournalOperation file>]]] [, <Option>]])

<Result>: Boolean

True if the data file was created or opened,
False if a problem occurred. HError is used to identify the error. If a fatal error occurs, a specific process is required to continue the program and to check whether the data file was created (see the Notes).

<File name>: Optional character string (with or without quotes)

Name of data file to use.
If this name is not specified, HCreationIfNotFound handles the last data file used by the last function for HFSQL management (starting with the letter H).
If this parameter is equal to "*", all the data files found in the current analysis will be created or opened. If a password is specified, this password is used for all the data files.
This parameter can also correspond to the name of a group of files (or custom-folder) defined in the analysis. If a password is specified, this password is used for all the data files of the group.
Caution: this parameter cannot correspond to a File Description variable.
Versions 17 and later
The maximum number of files that can be simultaneously opened by an iPhone/iPad application cannot exceed 256. Therefore, up to 80 HFSQL files can be opened simultaneously (one ".fic" file, one ".ndx" file and one ".mmo" file for each HFSQL data file).
New in version 17
The maximum number of files that can be simultaneously opened by an iPhone/iPad application cannot exceed 256. Therefore, up to 80 HFSQL files can be opened simultaneously (one ".fic" file, one ".ndx" file and one ".mmo" file for each HFSQL data file).
The maximum number of files that can be simultaneously opened by an iPhone/iPad application cannot exceed 256. Therefore, up to 80 HFSQL files can be opened simultaneously (one ".fic" file, one ".ndx" file and one ".mmo" file for each HFSQL data file).

<Password>: Optional character string (with quotes)

Password associated with the data file.
Empty string ("") if no password is used.

<Path of JNL file>: Optional character string (with quotes)

Access path to JNL file associated with the logged data file. This parameter is taken into account if the data file is logged. In this case, <File name>JNL.fic will be created at the specified location.
This parameter must not be specified. Indeed, the log process is not supported by HFSQL Mobile. This limit is caused by the optimized size of applications for Pocket PC.
This parameter must not be specified. In HFSQL Client/Server, the path of JNL file is defined and it cannot be modified.
This parameter is ignored.
Access by JDBC: This parameter is ignored.

<Path of JournalOperation file>: Optional character string (with quotes)

Access path to the JournalOperation file and to the JournalIdentification file associated with the logged data file. The JournalOperation file contains all the operations performed on the logged data file. This parameter is taken into account if the data file is logged.
This parameter must not be specified. Indeed, the log process is not supported by HFSQL Mobile. This limit is caused by the optimized size of applications for Pocket PC.
This parameter must not be specified. In HFSQL Client/Server, the path of operation file is defined and it cannot be modified.
This parameter is ignored.
Access by JDBC: This parameter is ignored.

<Option>: Optional constant

Optimize the opening of existing data files.
hChangeCharset The character set defined by ChangeCharset will be taken into account in the new data file. The sorts, the searches, ... on string keys (strings, characters, date and time) will be performed according to this character set.
hDelayedOpening If the data file already exists, it will be opened during the first access to the data file. If the data file does not exist, it is created and opened.
hNoLink Management of integrity: The links are not updated on the server (creation, modification or deletion).
Reminder: By default, the links are updated on the server when creating a data file.
This constant is available in HFSQL Client/Server mode only.
This parameter is ignored.
Access by JDBC: This parameter is ignored.
Versions 15 and later
This parameter is ignored.
New in version 15
This parameter is ignored.
This parameter is ignored.

Remarks

Characteristics of created data file

The characteristics of created data file are as follows:

Name of the data file:
Physical name defined during the file description in the data model editor. This name can be modified by HChangeName before creating the data file.
Directory of data file:
Directory defined during the file description in the data model editor. This directory can be modified by HChangeDir and HSubstDir before creating the data file.
Note: If the UAC is enabled (Windows Vista and later), the data localization is specific: the data will not be localized in the directory of the application but in a specific directory of Windows. In this case, the data directory of application will have to be created (the path can be returned by fDataDirUser).
The order of items created in the physical file is the physical order of items created in the analysis (and not the logical order).
Content of the data file:
The created data file is empty, which does not mean that its size is null (the file contains a header describing its structure).

Note: If the data file already existed (same name, same directory), this data file is opened. If the hDelayedOpening constant is specified, the data file will be opened during the first access (used to optimize the speed of HCreationIfNotFound).

The different created files

When creating a data file, the following files can be created in addition to the data file:

An index file (".NDX" extension) if one or more keys have been defined in the file description.
A memo file (".MMO" extension) if one or more memo items have been defined in the file description.
A log file (".JNL" extension). This file is created only if the corresponding option was selected during the file description (see next paragraph).
This file is not created.
A <ProjectName>.REP file. This file contains the list of data files handled by the application. This file is created (or filled) if the management of .REP is enabled (HSetREP). If the hDelayedOpening constant is specified, the .REP file will be updated during the automatic file opening performed during the first access to the data file. See .REP file for more details.
HCreationIfNotFound creates a physical data file if it does not exist. This function fills the list of data files if the update of this list is enabled and if the hDelayedOpening constant is not used.
If the hDelayedOpening constant is used, the list of data files will be updated during the automatic file opening performed during the first access to the data file. See List of data files handled by an application for more details.
This file is not created.

Managing passwords

The password can be defined:

when the data file is created or opened by HCreationIfNotFound.
before the data file is created by HPass.

Caution: The password is independent of data encryption. The data encryption must be configured during the file description in the data model editor ("Details" tab).

The password is not associated with a data file but with a database. This password must be specified during the connection (HConnect).

Managing fatal errors when creating a data file

If a fatal error occurs when creating a data file, it may be interesting to continue the program while checking whether the data file was created or not. To do so, we recommend that you perform the following exception process:

WHEN EXCEPTION IN
HCreationIfNotFound(PARENT)
DO
Error("HFSQL error: " + HError())
ELSE
Trace("The file is created")
END

Managing non-Latin character sets

If the hChangeCharset constant is specified, the character set used in the data file will be the one specified by ChangeCharset. The sorts, the searches, ... on string keys (strings, characters, date and time) will be performed according to this character set.

The character set used can be modified by HIndex.

Note: the size of string items specified in the analysis is expressed in bytes and not in characters. Depending on the character set used, you may have to increase the item size (if the characters used are coded on 2 bytes for example).

See Managing specific character sets in the data files for more details.

Replication: Range of identifiers

The automatic identifiers for the files of subscriber replicas are using a range of identifiers that differs from the one used by the file of master replica and by the other files of subscriber replicas.

This range of automatic identifiers is written in the header of each data file (".FIC" extension).
This range is initialized:

when creating a data file (HCreation, HCreationIfNotFound).
via WDReplic ("Tools.. WDReplic" in the editor menu).via WDReplic (on the "Tools" pane, in the "Database" group, expand "Replication" and select "WDReplic - Replication manager").via WDReplic.
when using HInitSubscriber.

See consequences of implementing the replication for more details.

Priority for defining the location of log files

The location of log files is defined according to the following priority order:

Location specified when creating the logged data file (HCreationIfNotFound).
Location specified by HChangeLogDir.
Location specified in the analysis.
Location of logged data file.

If another application is using HDeclareExternal on a logged data file, the modifications performed by this application are saved in the log files specified in the header of the logged HFSQL data file.

The location of Log files is fixed and it cannot be modified. See Log files in Client/Server mode for more details.

Creating or opening an existing table

If the table already exists, the table is opened.

If the table does not already exist, the table is created. When creating a table, WINDEV and WEBDEV try to create the items in the OLE DB type corresponding to the HFSQL type. If this type is not supported, the HFSQL engine successively tries all the "compatible" OLEDB types until it finds a type that is supported by the OLEDB database.

Managing indexes

If an index failed to be added, no error message is returned by HCreationIfNotFound. The table is created without the index that is causing the problem. In this case, duplicates may be found in an item defined as unique key by WINDEV or WEBDEV if the external database does not support the unique keys.

Creating the data file from its description

The data file can be directly created from its description in the data model editor. To do so, select "Create the data file" from the popup menu of the data file (in the analysis graph) and select the directory in which the data file must be created.

Component : wd240hf.dll