Maintaining history records

The database interface includes the ability to access history records. History records are one-line descriptions that can be associated with a file, with an image channel within a file, and with a data segment within a file. Whenever a file is modified, it is good practice to add a history record describing the change.

When a new record is added, the previous records are "pushed down". Most file formats maintain the last 8 history records, with each record being a maximum of 56 characters.

For example, to write a new history record containing the message "Linear Enhancement" to image channel 2 of an already open file (fd) you would use:

call DBWriteHistory( fd, "IMG", 2, "Linear Enhancement" )

The second argument "IMG" specifies that the history record is being written to an image channel, and the third argument gives the channel number being written.

A specifier of "FIL" as the second argument indicates that a record for the overall file should be written, and in this case the third argument is ignored.

A specifier of "LUT", "PCT", or any other valid segment descriptor indicates that the corresponding segment type should be written, and in this case the third argument gives the corresponding segment number.

If the processing of an image database file is aborted for some reason, the data being operated on may be left in an incorrect state. In this case, it is useful to have a special history record written to indicate this state. This is accomplished by calling DBWriteHistory() without specifying a message. A special message, "Operation Aborted", will be written to the file. When the operation is completed successfully, a new history message can be written, and special logic will cause it to overwrite the "Operation Aborted" message instead of pushing it down. When using this technique, EASI code has the following form (where the variables filename, channel, and message are assumed to have been defined):

fd = DBOpen( filename, "r+")
call DBWriteHistory( fd, "IMG", channel )
! ... do some processing on the channel
call DBWriteHistory( fd, "IMG", channel, message )
call DBClose( fd )

History records can be read using the DBReadHistory() intrinsic. For example, to read the most recent history record for the lookup table in the segment stored in the variable segnum into a string variable called description:

description = DBReadHistory( fd, "LUT", segnum )

The second and third arguments to DBReadHIstory() follow the same conventions as for DBWriteHistory(). An optional fourth argument to DBReadHistory() specifies a specific history record to read. For example, to read the third most recent history record:

description = DBReadHistory( fd, "LUT", segnum, 3 )