WalnutLog.Mesa
Copyright Ó 1984, 1988, 1992 by Xerox Corporation. All rights reserved.
Willie-Sue, May 23, 1988 6:37:25 pm PDT
Contents: types and procedures which take the current log file as explicit parameter
DIRECTORY
BasicTime USING [GMT],
IO USING [STREAM, Value],
Rope USING [ROPE],
ViewerTools USING [TiogaContents],
WalnutDefs USING [CheckReportProc, WalnutOpsHandle],
WalnutKernelDefs USING [LogEntry, WhichTempLog],
WalnutRoot USING [InternalLogInfo];
Types
GMT: TYPE = BasicTime.GMT;
ROPE: TYPE = Rope.ROPE;
STREAM: TYPE = IO.STREAM;
LogEntry: TYPE = WalnutKernelDefs.LogEntry;
WhichTempLog: TYPE = WalnutKernelDefs.WhichTempLog;
CheckReportProc: TYPE = WalnutDefs.CheckReportProc;
WalnutOpsHandle: TYPE = WalnutDefs.WalnutOpsHandle;
InternalLogInfo: TYPE = WalnutRoot.InternalLogInfo;
TiogaContents: TYPE = ViewerTools.TiogaContents;
LogHandle: TYPE = REF LogHandleRec;
LogHandleRec:
TYPE =
RECORD[
scanning: BOOL ¬ FALSE,
strm: STREAM,
scanningLog: InternalLogInfo, -- for logical start and end; also for lastLog
entryLengthHint: INT ¬ -1,
entryPos: INT ¬ -1
];
Logging of operations that perform actions on the Walnut database
ExpungeMsgs: PROC[opsH: WalnutOpsHandle] RETURNS[at, next: INT];
WriteExpungeLog: PROC[opsH: WalnutOpsHandle] RETURNS[at, next: INT];
CreateMsgSet: PROC[opsH: WalnutOpsHandle, name: ROPE] RETURNS[at, next: INT];
EmptyMsgSet: PROC[opsH: WalnutOpsHandle, msgSet: ROPE] RETURNS[at, next: INT];
DestroyMsgSet: PROC[opsH: WalnutOpsHandle, msgSet: ROPE] RETURNS[at, next: INT];
AddMsg: PROC[opsH: WalnutOpsHandle, msg: ROPE, to: ROPE] RETURNS[at, next: INT];
RemoveMsg: PROC[opsH: WalnutOpsHandle, msg: ROPE, from: ROPE] RETURNS[at, next: INT];
MoveMsg: PROC[opsH: WalnutOpsHandle, msg: ROPE, from, to: ROPE] RETURNS[at, next: INT];
HasBeenRead: PROC[opsH: WalnutOpsHandle, msg: ROPE] RETURNS[at, next: INT];
RecordNewMailInfo:
PROC[opsH: WalnutOpsHandle, logLen:
INT, when:
GMT, server:
ROPE, num:
INT]
RETURNS[at, next: INT];
StartCopyNewMail: PROC[opsH: WalnutOpsHandle] RETURNS[at, next: INT]; -- endCopy written by WalnutLogImpl
AcceptNewMail: PROC[opsH: WalnutOpsHandle] RETURNS[at, next: INT];
StartReadArchiveFile: PROC[opsH: WalnutOpsHandle, file: ROPE, msgSet: ROPE] RETURNS[at, next: INT];
EndReadArchiveFile: PROC[opsH: WalnutOpsHandle] RETURNS[at, next: INT];
StartCopyReadArchive: PROC[opsH: WalnutOpsHandle] RETURNS[at, next: INT]; -- endCopy written by WalnutLogImpl
Parsing a log (used by Scavenge and Replay)
SetPosition:
PROC[opsH: WalnutOpsHandle, startPos:
INT]
RETURNS[charsSkipped:
INT];
Set the position of the log to begin at the first log entry at or beyond startPos. Each of the parsing operations below take the current position of the log as an implicit argument. This procedure will skip ahead to the beginning of a log entry if startPos is not one -- the number of characters skipped is returned in charsSkipped.
SetIndex:
PROC[opsH: WalnutOpsHandle, pos:
INT];
sets the current log to the indicated position; used during expunge. The difference with SetPosition is that this asserts that the position is at the beginning of a log entry.
NextAt:
PROC[opsH: WalnutOpsHandle]
RETURNS[at:
INT];
returns the same value that NextEntry would return for at
NextEntry:
PROC[opsH: WalnutOpsHandle]
RETURNS[le: LogEntry, at:
INT];
The returned values include the entry found and the position it occupies on the log. If entry = NIL, then no more entries remain in the log (at = logLength); if at = -1 then the current read position does not point to the beginning of a log entry. A valid entry is "consumed", ie., a subsequent call to NextEntry will return a different position for "at".
Note: Successive calls to NextEntry will reuse the log entry returned -- if you need to keep information, copy it!
QuickScan:
PUBLIC
PROC[opsH: WalnutOpsHandle]
RETURNS[le: LogEntry, at:
INT];
Basically the same as NextEntry, but does not parse a message entry into its headers, but just returns the length of the headers section - used for the lazy enumeration of messages.
ArchiveEntry:
PUBLIC
PROC[opsH: WalnutOpsHandle, to:
STREAM]
RETURNS[ok:
BOOL];
Copies the next entry of the current log to an archive stream.
CopyBytesToArchive:
PROC[opsH: WalnutOpsHandle, to:
STREAM, startPos, num:
INT];
used to copy (parts) of messages to an archive stream; the format of the archive log bears little resemblence to walnut's log - it conforms to the laurel standard
Managing the current Log
InitLogStream:
PROC[opsH: WalnutOpsHandle]
RETURNS[ok:
BOOL];
getting off the ground - must be called first, does OpenLogStreams
LogLength:
PROC[opsH: WalnutOpsHandle]
RETURNS[length:
INT];
returns the length of the current log file
OpenLogStreams: PROC[opsH: WalnutOpsHandle];
ReleaseWriteLock:
PROC[opsH: WalnutOpsHandle];
for now, simply closes and re-opens the streams to downgrade the lock to none
ResetLog:
PUBLIC
PROC[opsH: WalnutOpsHandle, newLength:
INT];
used by parser for doing StartReadArchiveFile
ForgetLogStreams:
PROC[opsH: WalnutOpsHandle];
forgets the current state of the log streams
ShutdownLog:
PROC[opsH: WalnutOpsHandle];
does more thorough job of shutting down the log
Copying NewMail/ReadArchive logs
PrepareToCopyTempLog:
PROC[
opsH: WalnutOpsHandle, which: WhichTempLog, pagesAlreadyCopied:
INT, reportProc: CheckReportProc]
RETURNS[ok: BOOL];
makes sure there is enough space to copy the WhichTempLog onto the currentLog; returns FALSE if there is not enough space to extend the log
CopyTempLog:
PROC[opsH: WalnutOpsHandle, which: WhichTempLog, startCopyPos, fromPos:
INT, reportProc: CheckReportProc ];
copies the which templog, starting at fromPos to the end of the currentLog; writes an EndCopy log entry, and sets the length of which to 0, as an atomic operation; if the operation fails, WalnutDefs.Error is raised
FinishTempLogCopy:
PROC[opsH: WalnutOpsHandle, which: WhichTempLog];
releases the write lock on on the currentLog and reset the length of the temp log to something reasonable
CreateArchiveLog:
PROC[
opsH: WalnutOpsHandle, fileToRead:
STREAM, msgSet:
ROPE, reportProc: CheckReportProc]
RETURNS[ok:
BOOL];
reads fileToRead from the beginning and writes the readArchiveLog; writes an endReadArchive entry on the currentLog; returns TRUE if all went well; leaves the readArchiveLog closed, fileToRead open
Utilities
GetTiogaContents:
PROC[opsH: WalnutOpsHandle, textStart, textLen, formatLen:
INT]
RETURNS[contents: TiogaContents];
reads tioga text from log, returns NIL if EndOfStream is encountered
GetRefTextFromLog:
PROC[opsH: WalnutOpsHandle, startPos, length:
INT, text:
REF
TEXT];
reads length characters from log, sets length of text to 0 if EndOfStream is encountered