Perforce Public Knowledge Base - Reading Journal and Checkpoint Files
Downloads Blog Company Integrations Careers Contact Try Free
Menu Search
Reset Search



Reading Journal and Checkpoint Files

« Go Back



Under normal circumstances Helix Server 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 server's database and experience difficulties using your current checkpoint or journal files, contact Perforce Software's Technical Support team.

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 (for 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

Please ask the Perforce Technical Support Team for links to earlier schema versions.

  • 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@ - 'put value', inserting new data. Replaces "@put@" from earlier database revisions.
      • @dv@ - 'delete value', removing data. 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 value', updating an existing 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@ - 'verify value', a sanity-check used to ensurecorrect sequential playback of journals.Journals Only

        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 notesallows 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 librarian' - this instruction removes the corresponding librarian files from your archives.

        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:

Related Links
Latest Database Schema

A couple of online tools for converting unix epoch timestamps into human-readable date/time format. (external third-party site, not affiliated with Perforce Software)
Epoch Unix Time Stamp Converter (external third-party site, not affiliated with Perforce Software)



Was this article helpful?



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

Characters Remaining: 255