Journals and Journal Receivers

Journaling requires two objects at minimum: a journal (*JRN) and a journal receiver (*JRNRCV).

The journal receiver is the object in which the events are recorded. Each event is recorded as a journal receiver entry, which is automatically time-stamped and identified with the name of the user who originated it and the complete qualified name of the job the user was running.

The journal receiver must be created first, using the Create Journal Receiver (CRTJRNRCV) command, as follows:

      CRTJRNRCV JRNRCV(MYLIB/RCV0001) THRESHOLD(10000) 

This command creates a journal receiver in MYLIB called RCV0001. For reasons that will become apparent, journal receiver names should always end in four digits beginning with 0001. The THRESHOLD parameter is the size, in KB, that, when the journal reaches it, will trigger a notification. A value of 10,000 is 10,000 KB (10 MB). When the journal receiver grows to that size, the system sends message CPF7099, but keeps recording.

The journal is a channel through which an event reaches the journal receiver. A journal can have one or two journal receivers attached; if it has one, events are recorded in that journal receiver only. If it has two, the same event is recorded in both receivers as an added precaution.

Once the journal receiver exists, you can then create the journal using the Create Journal (CRTJRN) command:

      CRTJRN JRN(MYLIB/JOURNAL) JRNRCV(MYLIB/RCV0001) MSGQ(QSYSOPR) 

With this command, you create a journal called JOURNAL in MYLIB and attach to it the journal receiver you created earlier. The MSGQ parameter names the message queue to which the system sends message CPF7099 when the journal receiver's size threshold is reached.

Journaling Physical Files

Events most likely to be journaled are those changes made in database files. When you journal a physical file, the system records an image of the record as it was before the change and an image of the record after the change. You can also request to record only the "after" images.

Journaling a physical file can simplify data recovery. If you save a journaled file weekly, and save the journal and journal receiver daily (or every other hour), and you lose the file, you can restore the file from last week's backup and use the journal to reapply all the updates your users have made to the file.

Journaling also can work the other way around. If you run a mass-update program that adversely affects a journaled file, you can undo the mass update by removing the changes recorded in the journal. However, you can only undo the changes if you are recording both "before" and "after" images of the database records in your journals.

Here are the details:

Start journaling using the Start Journal Physical File (STRJRNPF) command. To run the STRJRNPF, the physical file must not be in use by anyone. After you run STRJRNPF, the file can be again used as usual:

      STRJRNPF FILE(MYLIB/ITMMST) JRN(MYLIB/JOURNAL)      IMAGES(*BOTH) 

This command requests both "before" and "after" images of the records that are changed. IMAGES(*AFTER) can be used if you would rather record only "after" images.

Immediately afterwards, save the file using the Save Changed Object (SAVCHGOBJ) command, as follows:

      SAVCHGOBJ OBJ(ITMMST) LIB(MYLIB) DEV(SYSTAP01) OBJTYPE(*FILE) OBJJRN(*YES) 

When you run this command, the system allows you to apply journaled changes to the file, which is the reason you are journaling the file. The key is the OBJJRN(*YES) parameter.

You can stop journaling a physical file by using the End Journal Physical File (ENDJRNPF) command.

Journaling Other Objects

Physical files are not the only objects you may journal. Use the Start Journal Object (STRJRNOBJ) command to journal data areas and data queues. After you begin journaling an object of these types, you must save the object, otherwise you will not be able to apply journal changes to the object, if necessary.

Journaling the Integrated File System

Use the Start Journal (STRJRN) command to journal stream files, directories, and symbolic links in the Integrated File System (IFS). You may also use STRJRN to journal changes to data areas and data queues. After you begin journaling an object of one of these types, you must save the object, otherwise you will not be able to apply journal changes to the object, if necessary.

Journaling Using SNDJRNE

As mentioned earlier in this chapter, you can use journaling to record all kinds of events. Journaling database changes is automatic, but other events must be recorded manually using the Send Journal Entry (SNDJRNE) command. Once recorded, you can view the journal entries using the Display Journal (DSPJRN) command.

The basic format of the SNDJRNE command (which can be included in your CL programs) is as follows:

      SNDJRNE JRN(MYLIB/JOURNAL) TYPE('SV') ENTDTA('Security      violation') 

This command records a journal entry of type SV (which is a code you can make up). The data is "Security violation" in this case, but it can be anything you want. If you include the SNDJRNE command in your CL programs, you can use CL variables and add their values to the ENTDTA parameter, such as:

      SNDJRNE JRN(MYLIB/JOURNAL) TYPE('SV') ENTDTA('Security      violation by user' *BCAT &USER *BCAT 'at workstation'      *BCAT &WS) 

The only restriction SNDJRNE imposes on you is that the value in the TYPE parameter must be greater than hexadecimal C000. If you make sure that the first character is a capital letter (which is at least x ‘C1’), this will not be a problem.

Maintaining Journal Receivers

Journal receivers grow in size as more and more entries are recorded. Periodically, you must maintain the journal.

To change journal receivers, run the Change Journal (CHGJRN) command to detach the journal receivers currently in use and attach new ones. The CHGJRN command creates new journal receivers and even names them. Because of this feature, it is best to give journal receivers names ending in four digits. It is simple for CHGJRN to generate a new name by adding 1:

      CHGJRN JRN(MYLIB/JOURNAL) JRNRCV(*GEN) 

Save the old journal receiver to tape or diskette (diskette may be impractical because journal receivers can be large objects):

      SAVOBJ OBJ(RCV0001) LIB(MYLIB) DEV(SYSTAP01)      OBJTYPE(*JRNRCV) 

Delete the old journal receiver from the system:

      DLTJRNRCV JRNRCV(MYLIB/RCV0001) 

You can have the system manage journal receivers for you. Specify MNGRCV(*SYTEM) when creating the journal. When the attached journal receiver reaches its threshold, the system will detach the receiver and create a new one:

      CRTJRN JRN(MYLIB/JOURNAL) JRNRCV(MYLIB/RCV0001)      MNGRCV(*SYSTEM) 

Journaling for Recovery

The most important application of journaling is that it provides a relatively easy and painless path to recover database files, especially those that change too much too quickly.

If a file undergoes many updates within a short period, a daily backup may not be enough to guarantee recovery.

Journaling, on the other hand, records all the changes in the journaled objects that you update through your application programs or utilities such as DFU or SQL. With journaling, you can recover objects in two different ways: forward or backward.

Forward Recovery

Use forward recovery if you need to restore an object from backup media (tape or diskette), and you want to reapply all the operations recorded in the journal up to the present point. Run the Work with Journals (WRKJRN) command, as shown in Figure 15.1.

Figure 15.1: Working with Journals (WRKJRN) command.

Figure 15.2: Working with forward recovery.

From the panel presented in Figure 15.1, select option 2 to perform forward recovery. Press Enter. The panel appears as shown in Figure 15.2.

Select option 2 when working with forward recovery. The system guides you through a series of steps necessary to restore your database file successfully and apply the journaled operations. These steps include the deletion of dependent logical files, restoration from tape, and recreation of the logicals.

Backward Recovery

Journaling can also work in reverse. If you are journaling your Accounting files and run your year-end General Ledger close, your database files go through a massive update process. If you are later informed that the fiscal year should not have been closed yet, journaling can help you undo the year-end close.

Run the WRKJRN command and select option 3 to perform backward recovery. A panel similar to the one shown in Figure 15.3 will appear.

Figure 15.3: Working with backward recovery.

From the screen shown in Figure 15.3, select option 2 to remove all the database operation changes you have journaled. You will have to know when to stop undoing operations, of course. You must run the DSPJRN command to find the exact journal entry sequence number where you need to stop.