Logging Commands

Logging commands work from the environment handle to control the use of the log files. Log files are opened when the environment is opened and closed when the environment is closed. In all of the commands in the logging subsystem that take or return a log sequence number, it is of the form:
{fileid offset}
where the fileid is an identifier of the log file, as returned from the log_get call.

> <env> log_archive [-arch_abs] [-arch_data] [-arch_log]

This command returns a list of log files that are no longer in use. It is a direct call to the log_archive function. The arguments are:

-arch_abs selects DB_ARCH_ABS to return all pathnames as absolute pathnames
-arch_data selects DB_ARCH_DATA to return a list of database files
-arch_log selects DB_ARCH_LOG to return a list of log files

> <env> log_compare lsn1 lsn2

This command compares two log sequence numbers, given as lsn1 and lsn2. It is a direct call to the log_compare function. It will return a -1, 0, 1 to indicate if lsn1 is less than, equal to or greater than lsn2 respectively.

> <env> log_file lsn

This command returns the file name associated with the given lsn. It is a direct call to the log_file function.

> <env> log_flush [lsn]

This command flushes the log up to the specified lsn or flushes all records if none is given It is a direct call to the log_flush function. It returns either a 0 (for success), a DB error message or it throws a Tcl error with a system message.

> <env> log_get [-checkpoint] [-current] [-first] [-last] [-next] [-prev] [-set lsn]

This command retrieves a record from the log according to the lsn given and returns it and the data. It is a direct call to the log_get function. It is a way of implementing a manner of log iteration similar to cursors. The information we return is similar to database information. We return a list where the first item is the LSN (which is a list itself) and the second item is the data. So it looks like, fully expanded, {{fileid offset} data}. In the case where DB_NOTFOUND is returned, we return an empty list {}. All other errors return a Tcl error. The arguments are:

-checkpoint selects the DB_CHECKPOINT flag to return the LSN/data pair of the last record written through log_put with DB_CHECKPOINT specified
-current selects the DB_CURRENT flag to return the current record
-first selects the DB_FIRST flag to return the first record in the log.
-last selects the DB_LAST flag to return the last record in the log.
-next selects the DB_NEXT flag to return the next record in the log.
-prev selects the DB_PREV flag to return the previous record in the log.
-set selects the DB_SET flag to return the record specified by the given lsn

> <env> log_put [-checkpoint] [-flush] record

This command stores a record into the log and returns the LSN of the log record. It is a direct call to the log_put function. It returns either an LSN or it throws a Tcl error with a system message. The arguments are:

-checkpoint selects the DB_CHECKPOINT flag
-flush selects the DB_FLUSH flag to flush the log to disk.

> <env> log_stat

This command returns the statistics associated with the logging subsystem. It is a direct call to the log_stat function. It returns a list of name/value pairs of the DB_LOG_STAT structure.