Reading Journal and Checkpoint Files

Info & Tags

Article #:
533
Created:
07/20/06
Modified:
01/09/08
Tags:
p4d

Links

  1. 2004.2 Database Schema
  2. 2005.1 Database Schema
  3. 2005.2 Database Schema
  4. 2006.1 Database Schema
  5. 2006.2 Database Schema
  6. Web-Based Unix Time Convertor
    Note: This is a third party site not affiliated with Perforce.

SUMMARY

Under normal circumstances Perforce administrators should never have to view nor edit checkpoints or journal files. However there are situations where it's necessary to troubleshoot issues involving recovering from a checkpoint or journal -- this article will help clarify the more arcane 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.

DETAILS

Checkpoint and journal files are text format files that can be read using most text editors or text tools (grep, split, and so forth). 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 revision of Perforce used:

Revision 97.3 and earlier:

@put@ - Writes (puts) the record to the database.

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

Revision 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 revision without first checkpointing and truncating the journal.

@rv@ - Replace record.

This is functionally identical to "@pv@" as far as the server is concerned -- it's main purpose is to improve the readability of the checkpoint and journal.

Revision 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 truncated 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.

Revision 2006.2 and later:

@ex@ - Journals Only - Transaction record.

This records includes the process ID (PID) and timestamp of a transaction being logged in the journal file. This is to improve the readability of a journal file and is ignored when playing back a journal file to the server.

Note: All timestamps in the journal and checkpoint files is in seconds elapsed sine the start of the Unix "epoch" (Midnight, January 1, 1970). You can convert this number using any number of only conversions. The time returned is usually in Greenwich Mean Time (GMT).

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 changes on the database revision, review the database schema documentation for your specific revision of Perforce.