Writing a record back to a keyed file¶
write[kl] |
Write a record back to a keyed file |
SYNTAX
Writes back the currently selected record in the buffer record_id to the file with which the buffer is associated, and updates all secondary indexes. This command is normally performed after changes have been made to the data in the record buffer, since a record must be written back if amendments to its key or data fields are to be permanently recorded.
The write command unlocks the record after writing it back. The writekl command keeps the record locked. The two commands are otherwise identical. On some SQL databases, using writekl instead of write can substantially improve performance. See Use of writekl with ODBC .
If key data has been altered since the record was read, a new record is inserted and the old record is deleted. In this case, the file pointer remains positioned at the old key value for the purposes of next, prev, nextkey and prevkey commands. The current file position of secondary indexes is not changed by write[kl]. The sync_indexes command is available to synchronise secondary index file positions to that of the main index.
record_id |
The buffer containing the record to be written back. The record buffer is frequently, though not necessarily, the default record buffer that is automatically created for each file opened within a program. This default buffer bears the same name as the file’s file_id. However, record_id may also be an additional buffer declared for the file by means of the declaration !record , as follows:
Only one record can be locked from any given file at one time. The write[kl] command always uses the current locked record from the file, regardless of the buffer it was read into, which is not necessarily the buffer named. If a record is read into one record buffer and written back from a different buffer, it is assumed that this is intentional. |
[nrs = label] |
Traps the condition where no record is currently selected. Control passes to the line indicated by label. If this condition is not trapped, the error message No record selected is output and control passes to the active menu, if any. If no menu is active the program exits. In a !report section, an untrapped nrs condition causes the command to be ignored. |
[re = label] |
Traps the condition where a record with this key already exists. If the key data has been changed, then it is possible that a record with the new key value already exists in the file. Control passes to the line indicated by label. The original record is unchanged, and remains in the record buffer, but is no longer locked. If this condition is not trapped, the error message Record Exists is output and control passes to the active menu, if any. If no menu is active the program exits. In a !report section, an untrapped re condition causes the command to be ignored. |
[ue = label] |
Traps the Update error condition. This error can occur only when an ODBC database that does not support record locking is being used. If two ODBC clients read the same record from such a database for update and then attempt to write or delete the record, only the first succeeds. The ue trap allows this situation to be trapped in Sculptor and the second user notified that their update operation has failed. Control is passed to the line indicated by label. If this error is not trapped, either by ue or by the all-purpose trap clause traps, Sculptor displays the default error message: Update refused - record updated by another user See ODBC record locking for more details. |
[traps = label] |
General purpose trap clause that traps any condition not explicitly trapped, passing control to the line indicated by label. It has the lowest priority, and is only invoked if a trappable condition has not been more explicitly trapped. |
NOTES
If the file is closed Sculptor automatically opens it, using the mode in which it was last open (defaulting to the mode in the file declaration).
A record is selected by successfully performing a find, next, match, prev or read on the file, which must be open in update or create mode.
The insert command is used to create a new record.
EXAMPLE
!file ConfigFile "kfconfig.d" read
!record tmpConfig = ConfigFile
!function SaveConfig() {
read ConfigFile traps = SC_ERROR
ConfigFile = tmpConfig
write ConfigFile traps = SC_ERROR
goto SC_RETURN
SC_ERROR:
error "Error saving configuration"
goto SC_RETURN
SC_RETURN:
return
}
RELATED TOPICS |