Journaling for Journal and Commit APIs

Journaling allows you to specify database files or access paths you want to protect for recovery purposes, or allows you to provide an audit trail for changes to database files. In addition, journaling allows you to provide an audit or activity trail for other objects or activities either by system activities, such as security auditing, or by user activities, such as the Send Journal Entry (SNDJRNE) command or QJOSJRNE API.

Two objects are associated with journaling: journals and journal receivers.

A journal is the object that identifies:

• The journaled objects, if any
• The current journal receivers
• Any journal receivers on the system that have been, or are, associated with the journal
• Any remote journals that are associated with the journal

A local journal is the journal that is the initiator of the original journal deposit. Objects can be journaled to a local journal, and journal entries are deposited into a local journal due to changes made to the journaled objects, or because journal entries were sent to the local journal.

A remote journal is a journal that has been associated with another journal via the Add Remote Journal (QjoAddRemoteJournal) API. Objects cannot be journaled to a remote journal nor can journal entries be directly deposited into a remote journal. Instead, a remote journal has journal entries replicated to it from its upstream source journal. The upstream source journal can be either a local journal or a remote journal.

A journal receiver is the object that contains journal entries, and can be associated with either a local or remote journal. For a journal receiver attached to a local journal, journal entries are directly deposited into the journal receiver. For a journal receiver attached to a remote journal, journal entries are replicated into the journal receiver from the source journal receiver associated with the upstream source journal.

Journal entries contain information such as:

• The job name, program name, and user that caused the journal entry to be deposited into the local journal.
• The date and time the journal entry was deposited into the local journal.
• Journal code.
• Entry type.
• Information that is unique to each journal entry type, called entry specific data.

For example, the entry specific data associated with the put of a record to a physical file member (journal code R, entry type PT) contains an image of the actual record that was put. The rest of the journal entry information helps determine at what time, by what user the entry was sent, and other details. If a user sends information to the journal using the SNDJRNE command or QJOSJRNE API (journal code U, entry type is defined at send time by the user), the entry specific data contains what was specified at that time.

When journaling is started for an object, a unique identifier called a journal identifier (JID) is assigned. This identifier remains the same even if the object is renamed or moved. The journal identifier is associated with every journal entry that is associated with a specific journaled object.

The JID allows the journal facility to associate the current name of an object with the journal entries, even if the entry was made before the object was renamed. To determine what name is currently associated with a particular JID, use the QJORJIDI API. See Retrieve Journal Identifier Information (QJORJIDI) API for more information on the JID and this API.

The SNDJRNE command and the QJOSJRNE API provide similar function, the sending of a journal entry at a user's request. See Send Journal Entry (QJOSJRNE) API for more information on this API. The major differences between the API and command are:

• The API allows up to 15761440 bytes of entry specific data, as opposed to 3000 bytes with the command.
• The API allows the association of the current commit cycle identifier with the journal entry. This support can be used with the QTNADDCR API. For more information see Add Commitment Resource (QTNADDCR) API.
• The API can optionally return the journal sequence number and journal receiver information for the entry that was deposited.

The QjoAddRemoteJournal, QjoRemoveRemoteJournal, and QjoChangeJournalState APIs allow you to establish, manipulate, and maintain a remote journal environment. A remote journal environment allows you to replicate journal entries from one system to another via communications methods such as TCP/IP, SNA, and OptiConnect for i5/OS^(TM). This support can be used to help replicate data from one iSeries^(TM) server to one or more additional iSeries servers. Using application programs, the replicated entries can then be used to maintain a backup, or replica of the primary systems data. If desired, the backup data can be used in the event the primary system fails. See Add Remote Journal (QjoAddRemoteJournal) API, Change Journal State (QjoChangeJournalState) API, and Remove Remote Journal (QjoRemoveRemoteJournal) API for more information on these APIs. The Add Remote Journal (ADDRMTJRN), Change Remote Journal (CHGRMTJRN), and Remove Remote Journal (RMVRMTJRN) commands provide support similar to these APIs.

The QjoRetrieveJournalInformation and QjoRtvJrnReceiverInformation APIs provide information that is similar to the Work with Journal Attributes (WRKJRNA) and Display Journal Receiver Attributes (DSPJRNCVA) commands, respectively. See Retrieve Journal Information (QjoRetrieveJournalInformation) API and Retrieve Journal Receiver Information (QjoRtvJrnReceiverInformation) API for more information on these APIs.