Perforce Public Knowledge Base - Reading Journal and Checkpoint Files
Reset Search
 

 

Article

Reading Journal and Checkpoint Files

« Go Back

Information

 
Problem

Under normal circumstances Perforce administrators should never have to view or edit checkpoints or journal files. However, there are situations where it is necessary to troubleshoot issues involving recovering from a checkpoint or journal -- this article will help clarify the more difficult aspects of journal and checkpoint file formats.

Warning: Editing checkpoints and journals without guidance can result in erratic server performance or data loss. If you need assistance restoring your Perforce database and experience difficulties using your current checkpoint or journal files, contact Perforce Support.
Solution
Checkpoint and journal files are text format files that can be read using most text editors or text tools (grep, split, and so on). Data in these files is stored in the following format:
  • Records are terminated with a newline ("\n") character.
  • Fields are delimited with spaces (" ").
  • At-marks ("@") are used to "quote" strings.
  • If a string contains an at-mark, it's listed twice ("@@").
Note: At-mark quoted strings can contain newlines (example: changelist descriptions), so care should be taken when using text oriented tools that read single lines based on newline termination (grep, split, and others).

Field Descriptions

Field 1

The first field describes the database action for that field, and varies according to the version of Perforce used:

Version 97.3 and earlier:
 
@put@ - Writes (puts) the record to the database.

@del@ - Deletes (removes) the record from the database.

Version 98.1 and later:
 
@pv@ - Replaces "@put@" from earlier database revisions.

@dv@ - Replaces "@del@" from earlier database revisions.

Note: While checkpoints will use one format or the other, there can be some situations where a journal file contains a mix of "@put@","@del@" and "@pv@", @dv@ records, particularly if the user upgraded from a pre-98.1 version without first checkpointing and truncating the journal.
 
@rv@ - Replace record.
 
This is functionally identical to "@pv@" as far as the server is concerned -- its main purpose is to improve the readability of the checkpoint and journal.

Version 99.2 and later:
 
@vv@ - Journals Only - Sanity check for journal playback sequence.
 
The value of this record (normally found at the beginning of a backed up journal file) is matched against the "journal" counter value to prevent re-playing journal files in the wrong order. A mis-match of this value while restoring a journal file generates a "Journal out of sequence" error. The error message will be along the lines of: "Perforce server error: 1 out of sequence journals were not replayed".
 

Version 2006.2 and later:
 
@ex@ and @mx@ - Transaction markers.
 
These lines include the process ID (PID) and timestamp of a transaction being logged in the journal file. These are for the benefit of journal replication tools and do not correspond to database records, so nothing is written to the database when these lines are restored.
 
Version 2010.1 and later:
 
@nx@ - Journal notes.
 
Similar to @mx@ and @ex@ records in that they don't record database table rows but instead record metadata information about an event which occurred. Journal notes allows later users of the journal or checkpoint to find that note and use the information in it to guide their behavior.
 
Version 2011.1 and later:
 
@dl@ - Delete content information.
 
These records contain information about file content which has been deleted from the server's repository by a command such as 'p4 obliterate', 'p4 archive', 'p4 shelve -d', etc.  This is made up from the the librarian file name, the librarian revision, and the librarian type of the archive content that was deleted. The record also contains information about the command which initiated the deletion, and the filespec that was passed to  that command.
 
 
 
Field 2

This contains a revision number for the record format

Field 3

The third field is the name of the database table. A file of the same name is created in the Perforce server root directory.

Remaining Fields

Since the remainder of the fields in any given record change based on the database version, review the database schema documentation for your specific version of Perforce. Database schema documentation for the most current release can be found at:

http://www.perforce.com/perforce/doc.current/schema/index.html

Please consult Perforce Support for links to earlier schema versions.

Related Links
Latest Database Schema
Web-Based Unix Time Convertor (Note: This is a third party site not affiliated with Perforce.)

Feedback

 

Was this article helpful?


   

Feedback

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

Characters Remaining: 255