Size
of Header
This section describes the format of the log file. The include file, <cbase/logfile.h>,
supplied with the C/Base Utilities defines the layout of a log file.
The first two things recorded in the log file are a magic number and version number. Drestore checks the magic number to insure that you gave it a valid log file. The version number is used to verify that the version of drestore and the version of the software that wrote the log file are compatible.
After the magic number and version number come the actual entries. The overall format of each entry is the same:
Size
of Header
Header
Size
of Log Record
Log Record
Size
of Argument
Argument
The argument is not always present. In that event, the size of the argument is zero.
Header Record
Every entry begins with a standard header. The actual format of this header is defined in the include file as TLHEAD. To summarize, the header includes the following information:
The type
of the entry.
The current
time (expressed as system GMT).
The process
ID of the program making the entry. It will always be zero on MS-DOS systems.
The actual log record follows the header.
The remainder of this section describes the format of each log record and when the record is written to the log file.
Process Record
The first entry a program makes in the log file is a process identification entry. This entry gives some basic information about the process. Its format is defined in the include file as TLPROC. It includes the following items:
The name
of the program making the entry.
The name
of the communication line being used by the program. This will be an empty string
on MS-DOS systems.
The real
and effective user id of the person running the program. This will be zero
on MS-DOS systems.
The real
and effective group id of the person running the program. This will be zero
on MS-DOS systems.
The program name is the optional argument of this record. If none has been defined at the time the record is written, a size of zero is recorded.
The function dlon(C-3) sets the program name. This also enables transaction logging if it had been disabled through the use of dloff(C-3). Dlon does not make the actual process ID entry. That is delayed until just before the first log record is recorded. If a process ID entry has already been written when dlon is called, a new entry showing the new program name is written just before the next log record.
Open File Record
Each time a logical RMSfile is opened for writing of any kind (append, update, create), an entry is recorded in the log file identifying the RMSfile. The format of this entry is defined in the include file as TLFILE. It includes the following information:
Database
name
Logical
RMSfile name
Number
of records (unused for opens)
Internal
file identification
This log record is used for all entries dealing with logical RMSfiles (hence the unused element for opens). The internal file identification is a unique number for the process to identify the logical RMSfile once it has been opened. This number is only used for open calls. For all other RMSfile operations it is zero.
Data Image Record
Each time a data record is inserted, deleted, or updated, an image log record is recorded in the log file. This shows what the data record looked like after an insertion, before a deletion, or before and after an update. The image log record is defined in the include file as TLCHG. It has the following information:
Changing
function (DUPDATE, etc.)
Internal
RMSfile identification
Record
number
The argument of this log record is the actual data record image.
The include file defines two types of image log records: before images and after images. When restoring from a log file, before images are compared with the current RMSfile's data records and after images are used as new values to duplicate changes. If the before image does not match the current record, the restore fails.
The function making the change is recorded in the log file to identify what change is being made. There are three functions that record images: dinsert(C-3), dupdate(C-3) and ddelete(C-3). Of these functions, only dupdate records both a before image and an after image.
Close File Record
When a logical RMSfile is closed, a logical RMSfile close entry is recorded in the log file. This entry has the same format as the data image log record, only the record number is zero and the argument (RMSfile's data record image) is empty.
Transaction Records
All transaction log records have the same basic form. Only the begin transaction record uses the argument for the comment of the transaction. For all other types of transaction records, the argument is empty. Transaction log records are defined in the include file as TLMARK. They contain the following information:
transaction identification
The combination of the process ID and transaction identification uniquely identifies each transaction. There are four types of transaction log records: begin, commit, cancel, and end. These types correspond to the transaction functions dlbegin(C-3), dlcommit(C-3), dlcancel(C-3) and dlend(C-3) respectively.
Change Format Record
The last set of log records are used when changing the format of a logical RMSfile. These records all use a format similar to the open file log record. In this case, the internal file identification is zero and the argument is used for the RMSfile definition. The actual format is defined in the include file as TLFILE. The following lists show how each of the functions record entries in the log file:
dlclear(C-3)
database name
logical file name
number of records (unused)
internal file identification (unused)
argument: (unused)
dldelete(C-3)
database name
logical file name
number of records (unused)
internal file identification (unused)
argument: (unused)
dlconv(C-3)
database name
logical file name
number of records (unused)
internal file identification (unused)
argument: new file definition
dlmake(C-3)
database name
logical file name
number of records
internal file identification (unused)
argument: new file definition
dlexpand(C-3)
database name
logical file name
number of records
internal file identification (unused)
argument: (unused)
If you read the documentation for the above functions, there is a note at the end of each one warning against indiscriminate use of the function. Heed these warnings well. The functions are documented only for the curious. There are commands for changing the file formats that in turn call these functions. Use the commands; not the functions. The following table shows the commands that call each of the above functions:
Function Commands
dlexpand(C-3) expandlf(C-1)
dlmake(C-3) makelf(C-1)
dlconv(C-3) convrtlf(C-1)
dlclear(C-3) clearlf(C-1)
dldelete(C-3) deletelf(C-1)