The edit table statement reads or reserves a record and passively or actively locks it.
|
If possible, use the get or change statements to retrieve information from a table. They’re much easier to use. |
edit table table_name {by key_name | by number expr}(, lock}(, refresh}
• table_name – The name of the table containing the record you wish to edit.
• by key_name | by number expr – Identifies the key to use to search the table. If one of these parameters isn’t included, the first key will be used.
You can identify the key by its name or by the key number. In the by key_name parameter, key_name is the key’s technical name. In the by number expr parameter, expr is an integer containing the number of the key, determined by its position in the table definition. For instance, the third key created can be identified by the number 3, and so on.
|
The key used by edit table must have a unique index (if a SQL database type is used) or not allow duplicates (if a Pervasive.SQL or c-tree Plus database type is used). Otherwise, you won’t be able to retrieve records from the table using the edit table statement. |
• lock – Indicates that the record will be actively locked, and no other users will be allowed to change or delete the record. If this option isn’t included, the record will be passively locked.
|
The lock option shouldn’t be used unless the Allow Active Locking option has been marked for the specified table in the Table Definition window. If the Allow Active Locking option hasn’t been marked for a given table, any edit table statements specifying that table and including the lock option will not compile. |
If your application will use the SQL database type, we recommend that you rely on passive locking instead of active locking. Using active locking with the SQL database type can cause performance degradation.
• refresh – This keyword only applies when a SQL database type is used. It indicates that the cursor and client-based buffer will be refreshed, so that they’ll contain the most current data from the table before the edit takes place. Even if the edit attempt fails, the refresh will occur.
|
If the Pervasive.SQL or c-tree Plus database types are used, the refresh keyword will be ignored. It will not affect your application in any way. |
The following sections describe how to use the edit table statement.
The values of the key fields must be in the table buffer before the edit table statement is issued. Use the clear table statement to clear the other fields in the table buffer if they contain information from a previous transaction.
When the Pervasive.SQL and c-tree Plus database types are used, you must set up all non-modifiable key segments and set values for them before you issue an edit table statement. This must be done because the edit table statement saves all key values to the table; once these key values are saved, non-modifiable key segments cannot be changed. You can avoid this requirement by making only the primary key non-modifiable and making the rest of the keys modifiable when you define the table.
When a SQL database type is used, the key used by edit table statement must have a unique index created for it. Otherwise, you won’t be able to retrieve records from the table using the edit table statement. Unique indexes are defined using the Keys window.
The edit table statement will attempt to write the record into the table using the key values in the table buffer.
If a record with those key values doesn’t exist in the table, a new record will be added to the table, storing the key fields and any other fields that are set in the buffer. This is called reserving a record. This process creates the record so a record with the same key values can’t be added or reserved by another user.
Once data has been placed in the other fields in the table buffer, use the save table statement to save the record. If a field has a default value established for it, and that field isn’t set in the table buffer, the default value will be saved in the table. If the edit process is stopped – for instance, if the user decided to cancel the current entry – use the release table statement to remove the record from the table and release the lock.
If a record exists with those key values, the edit table statement will read the record and passively lock it. The editexisting() function will return true, indicating the record existed before the edit table statement was run. To test for an error during the retrieval, use the err() function.
You can use the copy from table statement to automatically transfer the information from the table buffer to windows in the form. This can be done only for the auto-copy fields. Use the set statement to transfer a single field of information from the table buffer to the window, or to transfer data from fields that aren’t designated as auto-copy.