<Source>.Modify (Function)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Help / WLanguage / Managing databases / HFSQL / HFSQL functions

Managing automatic identifiers
Modifying the deleted or crossed records
Modification conflict or deletion conflict
Managing duplicates and integrity
Version of the data file after a modification
Managing binary memos
Modifying a record selected in a query
Modifying and looping through a record
xBase

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

<Source>.Modify (Function)

In french: <Source>.Modifie

Not available with this kind of connection

Modifies the specified record or the record found in memory in the data file (query or view). The indexes corresponding to all the keys used in the data file are automatically updated. The memos are added (if necessary) if the management of memos is enabled (<Source>.SetMemo.

After the call to <Source>.Modify:

it is recommended to configure the management of errors:
If the management of duplicates is enabled and if the data file contains a unique key, HErrorDuplicates returns True if the value of modified key is not unique. The record is not modified.
if a lock problem occurs (attempt to modify a locked record), HErrorLock returns True and the record is not modified.
the number of the current record is not modified. By default, the current iteration is not affected.

Note: This function can be used on a data file, an HFSQL view or a query.

Example

// Recherche l'enregistrement
Client.LitRecherchePremier(Nom, "Moulin")

IF Client.Trouve() = True THEN
	// Modification d'un enregistrement dans un fichier de données
	// (enregistrement décrit par programmation)
	Client.Prenom = "François"
	Client.Ville = "Montpellier"
	Client.CodeP = "34000"
	Client.Pays = "France"
	Client.Modifie()
END

// Modify current record of "Customer"
// displayed in a window
Customer.ToFile() 
Customer.Modify()

Syntax

<Result> = <Source>.Modify([<Record number> [, <Options>]])

<Result>: Boolean

True if the record was modified,
False in the event of a problem (integrity error, duplicates, etc.): the record is not modified. HError is used to identify the error.

<Source>: Type corresponding to the specified source

Name of data file, HFSQL view or query used.

<Record number>: Optional integer

Number of the record to modify. The record loaded in memory is re-written on the specified record.
If this number is greater than the total number of records in the data file, intermediate deleted records will be created in order for the sequential reading of the data file (<Source>.Read) to be consistent.

If this parameter is not specified (equal to 0 or to the hCurrentRecNum constant), <Source>.Modify will modify the current record in the data file.

CAUTION: Do not confuse the Record number with the automation identifier associated with the Record.. In most cases, these two numbers are not identical. The record number is returned by <Source>.RecNum.

To use the <Options> parameter, <Record number> must necessarily be specified.

This parameter must correspond to the current record number (hCurrentRecNum constant).

<Options>: Optional constant

Configures:
the effect of modification on the current iteration,
the mode for calculating the automatic identifier,
the lock mode applied to the modified record. If no lock constant is specified, the modified record is unlocked.

the management of duplicates,
the management of integrity.
Note: To use this parameter, it is necessary to specify the <Record Number> parameter.
hAffectBrowse Influence of modification on route: Modification assigns route.
For example, <Source>.ReadNext used after <Source>.Modify positions on the record found after the modified record (while taking its new values into account).
CAUTION: In all cases (constant hAffectCourse used or not): if function <Source>.Modify is used in a browse and the browse item value is modified, the current Record can be replayed in the rest of the path.. Indeed, modifying the browse item updates the index key of the data file. This modification is taken into account when reading the next records.

The hAffectBrowse constant has priority over the hWriteDefault constant.
hCheckDuplicates Duplicate management mode: Controls duplicates for this operation, even if duplicate control is switched off (function <Source>.SetDuplicates)..
A WLanguage error occurs if the hIgnoreDuplicates and hCheckDuplicates constants are used at the same time.

hCheckIntegrity Integrity management mode: Controls operation integrity even if automatic integrity control is disconnected (function <Connection variable>.SetIntegrity).
A WLanguage error occurs if the hIgnoreIntegrity and hCheckIntegrity constants are used at the same time.

hFalsifyTimestamp Timestamp field management By default, a timestamp field contains the date and time of record creation/modification, calculated automatically.
This constant prevents the timestamp field from being updated: the last value in the record will be retained.
hForceIDAuto Automatic identifier calculation mode: The automatic identifier is not calculated when the automation is added.. The identifier corresponds to:
the value assigned to the item through programming (CUSTOMERID = 7 for example)
the default identifier value specified in the data model editor (if the data file was just opened, with no record read)
the identifier value found in memory (identifier value for the last record read in the data file).
Once the record is added, the next automatic identifier calculated by the HFSQL engine will be calculated while ignoring the value added by hForceIDAuto.
A WLanguage error occurs if the hSetIDAuto and hForceIDAuto constants are used at the same time.
hIgnoreDuplicates Duplicate management mode: Ignores duplicate control for this operation, even if automatic duplicate control is connected (function <Source>.SetDuplicates)..
A WLanguage error occurs if the hIgnoreDuplicates and hCheckDuplicates constants are used at the same time.

hIgnoreIntegrity Integrity management mode: Ignores the integrity check on this add operation, even if the automatic integrity check is connected (function <Connection variable>.SetIntegrity)..
A WLanguage error occurs if the hIgnoreIntegrity and hCheckIntegrity constants are used at the same time.

hLockNo
(default value) Lock mode for modified Record No blocking: the modified record will not be blocked.

hLockReadWrite Lock mode for modified record Lock in read/write mode: the modified record will be locked in read and write mode. This record cannot be read or modified by another application. Only the current application can modify it, read it or unlock it.

hLockWrite Lock mode for modified record Lock in write mode: the modified record will be locked in write mode. This record can be read by another application but it cannot be modified by another application. Only the current application can modify it or unlock it.

hRecalculateIDAuto Automatic ID calculation mode The automatic identifier of the Record will be re-calculated when writing. This constant has priority over hForceIDAuto and hSetIDAuto.
hSetIDAuto Automatic ID calculation mode The automatic identifier is not calculated at the time of addition: the identifier value will be that memorized at the time of addition.
The next identifier value calculated by the HFSQL engine will correspond to the largest identifier value in the data file +1.
A WLanguage error occurs if the hSetIDAuto and hForceIDAuto constants are used at the same time.
hWriteDefault
(default value) Influence of modification on route: Modification does not assign current route.
For example, <Source>.ReadNext used after <Source>.Modify positions on the record found after the current record before the modification.

WARNING: If the <Source>.Modify function is used in a browse and the browse item value is modified, the current Record may be replayed at the end of the route.. Indeed, modifying the browse item updates the index key of the data file. This modification is taken into account when reading the next records.

The hAffectBrowse constant has priority over the hWriteDefault constant.

Remarks

Managing automatic identifiers

By default (without using the constants for modifying the automation identifier), the function <Source>.Modify function used on an active or scratched record does not modify the automatic identifier (even if the automatic identifier has been assigned in the language): the automatic identifier present in the data file is re-used.

The hForceIDAuto and hSetIDAuto constants are used to modify the default behavior of the automatic identifier.

For more details, see Managing the automatic identifier during a modification.

If the database generates an automatic identifier, the HFSQL engine keeps this value. If the hForceIDAuto or hSetIDAuto constant is specified, the HFSQL engine replaces the generated value by the desired value.
Note The constant hForceIDAuto is equivalent to hFixeIDAuto: the automation identifier calculated by HFSQL the next time a file is added will be unique in the data file.
If no automatic identifier is generated by the database, the HFSQL engine generates the value and assigns it to the automatic identifier.

Modifying the deleted or crossed records

Modifying a crossed record or a deleted record re-enables the record.

Modification conflict or deletion conflict

Modification or deletion conflict errors appear only if <Source>.Modify is used on the current record. If a record number is specified, there can be no conflict, since the record was not read before the modification.

For more details, see HFSQL error handling help.

Managing duplicates and integrity

The integrity and duplicate checks are performed on the keys for which:

a check is enabled,

and
the value of the item is modified in relation to the record found in the data file.

Example:

...
Client.Nom = "TREMOULET"
Client.Prénom = "Milo"
Client.Ajoute() 	// contrôles intégrité et doublon effectués sur 
				// Nom et sur Prénom si gestions actives
Client.Prénom = "Martin"
Client.Modifie() 	// contrôles intégrité et doublon effectués sur 
				// Prénom uniquement si gestions actives
...

Version of the data file after a modification

If the record was modified (no duplicate error and no integrity error), the version number of the data file is modified. To get the version number, use <Source>.Version.

Managing binary memos

When a record is modified, the memos are modified if necessary (if the management of memos is enabled by <Source>.SetMemo).
Reminder: to initialize a binary memo field, use function <Source>.LinkMemo.

Modifying a record selected in a query

The modification of a record in a query can be performed:

in the query result
in the data files handled by the query (hModifyFile constant used in <Source>.ExecuteQuery or <Source>.ExecuteSQLQuery). In this case, the hWithFilter constant is automatically selected.

We must distinguish between two cases, depending on the runtime mode of the query (with or without the hWithFilter constant).


Running the query with the hWithFilter constant	Only the modification of the current record is allowed. If the function is run to modify a query based on several data files, the modification is applied to the linked data files. A WLanguage error occurs when the content of a calculated item is modified. The content of these items is automatically calculated when modifying the record.
Running the query without the hWithFilter constant	If the function is run to modify a query based on several data files, the modification is applied to the linked data files. If the modified record does no longer correspond to the query selection, the record will still be found in the result of the query A WLanguage error occurs when the content of a calculated item is modified. The content of these items is automatically calculated when modifying the record.

Caution:

No modification is allowed in a query that uses groups or aggregates.
Integrity and duplicates are not managed by operations on multi-file queries: it is advisable to use transactions to avoid any problems.

Modifying and looping through a record

If the modification is performed during an iteration, the modified record will be visible in the current iteration only. If other iterations have been defined on this database, the modified record will be visible once these iterations have been reinitialized.

Using the hAffectBrowse constant slows down the modification because the table or the query is refreshed.

WARNING: If the <Source>.Modify function is used in a browse and the browse item value is modified, the current Record may be replayed at the end of the route.. Indeed, modifying the browse item updates the index key of the data file. This modification is taken into account when reading the next records.

xBase

<Source>.Delete and <Source>.Cross have the same effect: the record is crossed but not deleted. Therefore, the record can be re-enabled using <Source>.Modify. In this case, <Source>.State returns the hStateCrossed constant for a deleted record (instead of hStateDel).

Business / UI classification: Business Logic

Component: wd300hf.dll