The change statement reads a record from a table and passively or actively locks the record, allowing changes to be made to the table.
change {next | prev | first | last} table table_name {by key_name | by number expr}{, lock}{, wait}
• next | prev | first | last – Identifies which record to retrieve.
If none of these keywords are included, the record that matches the key value in the table buffer will be retrieved. The next keyword will retrieve the record that follows the key value currently in the table buffer. The prev keyword will retrieve the record preceding the key value in the table buffer. The first keyword will retrieve the first record in the table or range. The last keyword will retrieve the last record in the table or range.
• table table_name – The name of the table containing the record to read.
• by key_name | by number expr – Identifies the key to use to locate the record to be retrieved. 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.
• 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 change 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.
• wait – Indicates that the statement will wait until it can lock the record. The wait keyword can be used only in conjunction with the lock keyword. We recommend caution when using the wait feature. It suspends the user’s computer until the record becomes available.
|
The wait feature is not supported by SQL or Pervasive.SQL. The wait keyword will be ignored by Dexterity applications using these database types. |
• refresh – This keyword only applies when the SQL database type is used. It indicates that the cursor and client-side buffer will be refreshed, so that they’ll contain current data from the table before the change occurs. Even if the change 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 values of the key fields should be set in the table buffer before the change statement is issued. You don’t need to set any fields in the table buffer to retrieve the first or the last record in a table.
The change statement fills only the table buffer. To transfer information to the window so the information can be displayed, use a copy from table statement. To transfer a single field of information from the table buffer to the window, use the set statement.
If the specified table isn’t open, the change statement will open it.
The err() function or the check error statement can be used after the change statement to ascertain whether the operation was successful or to handle errors that may have occurred.