Perforce Public Knowledge Base - Journal notes
Downloads Blog Company Integrations Careers Contact Try Free
Menu Search
Reset Search



Journal notes

« Go Back



Journal notes, first introduced in 2010.2, are purely metadata, They are similar to @mx@ and @ex@ records in that they don't record database table rows but instead record metadata information about events.




The presence of journal notes in journals and checkpoints allows later users of the journal or checkpoint to examine the notes and use the information in them to guide behavior. They also serve to enable features of replica servers, allowing replicas to take action based on the journal notes they process.

The basic structure of a journal note is as follows:

@nx@ type date @version@ i1 i2 i3 i4 i5 @s1@ @s2@ @s3@ @s4@ @s5@

All journal notes have three common fields:

@nx@ type date @version@ i1 i2 i3 i4 i5 @s1@ @s2@ @s3@ @s4@ @s5@

type =  journal note type
date =  timestamp indicating when the note was written
version = server version that wrote the note

plus additional information based on the type of journal note in the form of a set of integer (i1-i5) and string (s1-s5) flags:

@nx@ type date @version@ i1 i2 i3 i4 i5 @s1@ @s2@ @s3@ @s4@ @s5@

Summary of Journal Note Types





Checkpoint Header

i1 = case-handling & Unicode Enabled
s1 = database root
s2 = journal file name


Checkpoint Trailer



Journal Header

i1 = case-handling
i2 = journal type
s1 = database root
s2 = journal file name
s3 = server version

journal type field (i2) shows how the journal file was produced:
0 = normal journal
1 = p4d -jd
2 = p4d -jds
3 = p4d -xx (jnl.fix)
4 = journaldbchecksums -u


Journal Trailer



Table Summary

i1 = table version
i2 = old version
i3 = table checksum
i4 = table bad-unlock count
s1 = table name


Server Upgrade

i1 = start value of upgrade counter
i2 = destination value of upgrade counter


Table Upgrade

i1 = upgrade being performed
s1 = name of the upgrade function called


Server Startup

s1 = server port
s2 = server root
s3 = server name
s4 = serverid


Server Shutdown

s1 = server port


Unicode Enabled



Table Patched



Journal Replayed

i1 = flags in effect during journal replay
s1 = name of the journal/checkpoint replayed


Table Checksum

i1 = table version
i2 = table checksum
i3 = table bad-unlock count
i4 = table generation
s1 = table name


Unload Header

i1 = domain type (client/label/stream)
s1 = domain name
s2 = unload filename


Unload Trailer



Change Checksum

i1 = change number
i2 = number of revisions in change
i3 = written-by: journaldbchecksums (0), submit (1), populate (2), fetch/push/unzip (3)
s1 = change checksum


Table Dump

i1 = table version
i2 = table checksum
i3 = number of records
i4 = isCompressed
s1 = table name
s2 = dump file name


Block Checksum

i1 = table version
i2 = block number
i3 = block size
i4 = dump version
s1 = table name
s2 = first key in block
s3 = last key in block
s4 = block checksum


Master Up

s1 = port
s2 = name (may be blank)
s3 = serverid (may be blank)


Master Stopping

s1 = port
s2 = name (may be blank)
s3 = serverid (may be blank)


Master Transition

s1 = port
s2 = name (may be blank)
s3 = serverid (may be blank)


Standby Up

s1 = port
s2 = name (may be blank)
s3 = serverid (may be blank)


Workspace Up

s1 = port
s2 = name (may be blank)
s3 = serverid (may be blank)


Replica Transaction

s1 = serverid of this replica
s2 = current statefile position in this replica 
i1 = last pid seen in @ex@ or @mx@ record from target
i2 = last timestamp seen in @ex@ or @mx@ record from target

24User Renameds1 = old user name
s2 = new user name

Usage Examples

There are a number of different types of journal notes and the information in them can be used for a variety of purposes. The next few paragraphs illustrate how the presence of header/trailer notes in a checkpoint can be valuable.

Each checkpoint contains a checkpoint header note:

@nx@ 0 1296517759 @30@ 2 0 0 0 0 @/p4root@ @journal@ @@ @@ @@

and a checkpoint trailer note:

@nx@ 1 1296517767 @30@ 0 0 0 0 0 @@ @@ @@ @@ @@

The checkpoint header note, in its additional information, contains the case-handling and unicode flags in effect when the checkpoint was taken. This allows the Perforce Server to ensure that the same flags are in effect when the checkpoint is restored:

$ p4d -r /p4root -jr checkpoint.9
Perforce db files in '.' will be created if missing...
Recovering from checkpoint.9...
Perforce server error:
Journal file 'checkpoint.9' replay failed at line 1!
Bad transaction marker!
Case-handling mismatch: server uses Windows-style (-C1) but journal flags are Unix-style (-C0)!

Using the server version in the checkpoint header note, a warning is issued when restoring a checkpoint created by a newer version of server:

$ p4d -r /p4root -jr checkpoint.9
Recovering from checkpoint.9...
Perforce server info:
 Server version 30 is replaying a version 31 journal.

Since journal notes are independent of the other contents of a checkpoint or journal, in case of a problem they can always simply be removed. For example:

   grep -v '^@nx@' checkpoint.N >

The checkpoint trailer note, simply by its presence, can be used to confirm that the checkpoint completed successfully.

By subtracting the timestamps of the checkpoint header and trailer, you can determine how long it took to take the checkpoint.


Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255