Inserting a new record into a file¶

insert

Insert a new record into a file

SYNTAX

insert record_id [key = expr_list] [re = label] [riu = label] [traps = label]

Inserts a new record from the record buffer record_id into the file with which it is associated. The file must be open in update mode. The index of the file is immediately reorganised so that the record appears in its correct location in the file index.

Records are also inserted into any secondary indexes that exist for the file. Note, however, that the current file position of secondary indexes is not changed. The sync_indexes command is available to synchronise secondary index file positions to that of the main index.

record_id	The record buffer containing the data for the record to be inserted. This 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: !record record_id = file_id
[key = expr_list]	Normally, the key values for the new record are set by directly assigning the values to the key fields. The key = clause provides the facility to specify the key values by means of an expression list. The key = clause has the syntax: key = expression [,expression]… Each expression evaluates to a key field value. The first is assigned to the first key field of the record, the second to the second key field, and so on. Standard rules of assignment are used. If the number of key values listed is fewer than the number of file key fields, the extra keys are set blank. If the number of key values listed is greater than the number of file key fields, the extra values are discarded. See The key = clause.
[re = label]	The data in the file’s key fields must provide a unique key for the new record. If a record with the supplied key already exists, then the Record exists condition is generated. The re = clause traps this event, and passes control to the line specified in label. The file position is unchanged by a failed insert. 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.
[riu = label]	Traps the Record in use condition. This occurs when the file is locked, because another process has locked the file with the readlock or writelock command. The riu or traps clauses can be used to pass program control to a specified label in this event. If the Record in use condition is generated but not trapped, the message Waiting… is displayed and program tries again to insert the record every three seconds until it is successful. If an untrapped riu occurs in a !report section, no Waiting… message is output. The program merely waits for the record to become available.
[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). See ![o]file.
If the file is not open in read mode an error message is printed and the program aborts.
If there is insufficient space on the disk for the new record and its index entry, an operating system error occurs and the file may become damaged. See kfcheck and kfri for information on repairing damaged files.
The write command is used to update an existing record.
If an insert command fails because a record with a key equal to the attempted insert already exists, then the pre-existing record will be locked and hence may now be the subject of a write command.

EXAMPLE

!function OKInsert() {
     if (isblank(Customers)) {
          prompt "", \
          " Insert a record with all null values - are you sure? " \
               button = " Yes " \
               button = " No  ", INSERT_CONTINUE
    }

     insert Customers re = INSERT_RE riu = INSERT_RIU
     return

INSERT_RE:
     info "Record already exists with this key"

INSERT_CONTINUE:
     SetFocusKey1()
     return

INSERT_RIU:
     info "File has been locked by another process"
     SetFocusKey1()
     return

INSERT_TRAPS:
     info "Cannot insert record (unknown error)"
     SetFocusKey1()
     return
}

RELATED TOPICS