Applying journaled changes

 

If an object becomes damaged or is not usable you can recover the object using the Apply Journaled Changes (APYJRNCHG) or Apply Journaled Changes Extend (APYJRNCHGX) command. If you restore an object that was saved with partial transactions, then apply journaled changes to that object before it is usable.

 

Difference between APYJRNCHG and APYJRNCHGX

There are slight differences between the Apply Journaled Changes (APYJRNCHG) command and the Apply Journaled Changes Extend (APYJRNCHGX) command. The APYJRNCHGX command only applies entries for database files and requires entries to be applied for all files in a library. This command will also apply entries for logical files found in the library, and it will apply the create file (D CT) journal entry. The APYJRNCHG command will not apply entries for logical files, or the create file entry. The APYJRNCHG command also applies entries for non-database objects.

 

Applying journaled changes to all objects

You can apply journaled changes to all objects that are journaled to the journal by specifying OBJ(*ALLJRNOBJ) on the APYJRNCHG command.

 

Applying journaled changes and commitment control

You can ensure that commitment transaction boundaries are honored during the apply journaled changes operations by using the commit boundary (CMTBDY) parameter. The default value for the CMTBDY parameter is *YES. If the system encounters a journal entry that causes the apply or remove process to stop for the object, the commitment boundary might not be honored.

 

Error handling

When the system encounters a journal entry it cannot process, it ends apply processing either for that specific object or for the entire apply operation. You can specify how the system behaves when it encounters a journal entry it cannot process with the Object Error Option (OBJERROPT) parameter on the APYJRNCHG or APYJRNCHGX command. If you specify OBJERROPT(*CONTINUE), the system ends apply processing for the specific object that has an error, but it continues apply processing for the other objects in the apply operation. If you specify OBJERROPT(*END), the system ends processing for the entire apply operation. The OBJERROPT parameter is also available for the Remove Journaled Changes (RMVJRNCHG) command. Actions of applying or removing journaled changes by journal code shows which entry types cause processing to end for an object.

 

Before you start applying changes

You must first reestablish the object to a condition that you know is undamaged.

• To reestablish the object, restore the last saved copy of the object. The object must have been saved while it was being journaled.

• If you saved a database physical file by using the Copy File (CPYF) command, use the CPYF command to restore the member by overlaying the contents of the existing object with the old values.

• If the member of a database physical file was just initialized, initialize the member again using the Initialize Physical File Member (INZPFM) command or a user-created application program.

• If a member of a database physical file was just reorganized, reorganize the member again using the Reorganize Physical File Member (RGZPFM) command.

You must restore the needed journal receivers if any of the following are true:

• If the journal receivers were deleted since the object was last staved (or some other point).

• If the journal receivers were saved with their storage freed.

When you apply journaled changes to an object, the object cannot be in use by anyone else.

 

Starting and stopping points for applying journaled changes

When the condition of the object has been established, use the APYJRNCHG or APYJRNCHGX command to apply the changes that are recorded in the journal to the object.

The system applies the changes to the object in the same order as they were originally made. You must plan where you want to start and stop applying changes. Use the Display Journal (DSPJRN) command to identify the desired starting and ending points. If you use a control language (CL) program for your recovery procedures, use the following:

• Receive Journal Entry (RCVJRNE) command to receive journal entries as they are written to the journal receiver.

• Retrieve Journal Entry (RTVJRNE) command to retrieve a journal entry and place it in program variables.

You can also use the QjoRetrieveJournalEntries API to retrieve the information into a High Level Language (HLL) program.

 

Starting applying journal entries

On the APYJRNCHG or APYJRNCHGX command, specify the first journal entry to be applied to the object. This entry can be selected from any of the following points:

• After the last save of the object

• From the first journal entry

• From an identified sequence number that corresponds to a date and time stamp

• From an identified sequence number that corresponds to the start or end of a particular job's use of the object provided that you did not specify one of the following:

  • OMTJRNE(*OPNCLO) when starting journaling or changing the journaling attributes for object.

  • OMTJRNE(*OPNCLOSYN) when starting journaling or changing the journaling attributes for a directory or stream file.

  • RCVSIZOPT(*MINFIXLEN) for the journal at any time while the object was journaled.

  • A FIXLENDTA option that omitted the job name.

• A specific sequence number

  If an object was restored with partial transactions, then specify FROMENT(*LASTSAVE) or FROMENTLRG (*LASTSAVE).

 

Stopping applying journal entries

You can stop applying the journal entries at the following:

• The end of the data in the last journal receiver in the receiver range

• A particular entry in the journal

• A date and time stamp

• A commitment boundary

• The start or end of a particular job's use of the data in the object, provided you did not specify the following:

  • OMTJRNE(*OPNCLO) when starting journaling or changing the journaling attributes for the object.

  • OMTJRNE(*OPNCLOSYN) when starting journaling or changing the journaling attributes for a directory or stream file.

  • RCVSIZOPT(*MINFIXLEN) for the journal at any time while the object was journaled.

  • A FIXLENDTA option that omitted the job name.

• The journal entry that indicates when the object was last restored

• A specific sequence number

 

The apply and remove journaled changes output file

It is highly recommended that you use the apply and remove journaled changes output file when you apply journaled changes. The output file contains a record for each object that the apply operation processes. It contains a record for each object created and each object deleted during the apply. This output file is especially useful when the apply ends early. It is much easier to query the output file for the status of each object rather then searching through the job log messages. Also the messages are limited to 512 while the output file is not limited.

 

Considerations for applying changes

Considerations for applying changes are as follows:

• When you apply journaled changes to integrated file system objects, you need to be aware of integrated file system considerations.

• If you need to apply entries for less than 300 objects, and your database files have only one member, or you will be applying changes to all members of the files, then you may wish to use the Forward Recovery option through the Work with Journals (WRKJRN) command.

• Integrated file system considerations for applying journaled changes
  If there is a create entry or delete entry in the range of journal entries to which you are applying journaled changes, changes to a directory can cause the creation or deletion of an object.

• Applying journaled changes with the WRKJRN command
  The Work with Journal (WRKJRN) command can be used to recover any journaled object. When you select option 2, you choose from a list of object types for recovery. Choose an object type to view the journaled objects of that type and the current status for each object.

 

Parent topic:

Recovery of journaled objects

Related concepts
Actions of applying or removing journaled changes by journal code Use of the QAJRNCHG file

Related reference
Apply Journaled Changes (APYJRNCHG) command Apply Journaled Changes Extend (APYJRNCHGX) command Copy File (CPYF) command Initialize Physical File Member (INZPFM) command Reorganize Physical File Member (RGZPFM) command Display Journal (DSPJRN) command Receive Journal Entry (RCVJRNE) command Retrieve Journal Entry (RTVJRNE) command Retrieve Journal Entries (QjoRetrieveJournalEntries) API