Perforce Public Knowledge Base - Journal notes
× PRODUCTS SOLUTIONS CUSTOMERS LEARN SUPPORT
Downloads Blog Company Integrations Careers Contact Try Free
Menu Search
Perforce
Reset Search
 

 

Article

Journal notes

« Go Back

Information

 
Problem

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.

 

 

Solution

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

Type

Name 

Flags

0

Checkpoint Header

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

1

Checkpoint Trailer

 

2

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

3

Journal Trailer

 

4

Table Summary

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

5

Server Upgrade

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

6

Table Upgrade

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

7

Server Startup

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

8

Server Shutdown

s1 = server port

9

Unicode Enabled

 

10

Table Patched

 

11

Journal Replayed

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

12

Table Checksum

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

13

Unload Header

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

14

Unload Trailer

 

15

Change Checksum

i1 = change number
i2 = number of revisions in change
i3 = note written by journaldbchecksums (0) or submit (1)
s1 = change checksum

16

Table Dump

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

17

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

18

Master Up

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

19

Master Stopping

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

20

Master Transition

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

21

Standby Up

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

22

Workspace Up

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

23

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 > checkpoint.N.new

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

Feedback

 

Was this article helpful?


   

Feedback

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

Characters Remaining: 255