CL Command Reference - APYJRNCHG
CL Command List > APYJRNCHG Reference
Description:
The Apply Journaled Changes (APYJRNCHG) command applies the changes that have been journaled for a particular journaled object to a saved version of the object to recover it after an operational error or some form of damage.
Object content changes, and most object level changes can be applied. Examples of object level changes include journal entries resulting from SQL statements like ALTER TABLE and many operating system commands (for example: CHGPF, RMVM, MOVOBJ, MOV, RNMOBJ and RNM). The one object level change that cannot be applied is for database file objects and it is journal code D, entry type CT (create file). Object level changes that do not deposit a journal entry, naturally, cannot be applied.
Note: Some object level changes can only be applied if the entries were deposited into the journal receiver on a V5R3 or later system. Those object level change entries include:
. D MA (member added)
. D FM (file moved)
. D FN (file renamed)
. E EM (data area moved)
. E EN (data area renamed)
Note: Data queue entries can only be applied if the entries were deposited into the journal receiver on a V5R4 or later system.
Some object level changes that are applied are entries from SQL statements. The replay of these entries can cause the Apply Journaled Changes (APYJRNCHG) command to run for a long time. The default time-out for the replaying of the ALTER TABLE, REFRESH TABLE or the reorganizing physical file entry is 24 hours. The default time-out for commit, rollback or cancel rollback entry is 12 hours. The default time-out for the replaying of the DROP TABLE entry is 1 hour. The default time-out for other object level change entries from SQL statements is 5 minutes.
If you want to change these default values to a higher or lower value, then add an environment variable called:
. QIBM_JO_APPLY_ALTER_TABLE_TIMEOUT - alter table (D CG) entry
. QIBM_JO_APPLY_REFRESH_TABLE_TIMEOUT - refresh table (D TQ) entry
. QIBM_JO_APPLY_DROP_TABLE_TIMEOUT - drop table (F DM) entry
. QIBM_JO_APPLY_REORG_TIMEOUT - reorganize physical file (F RM) entry
. QIBM_JO_APPLY_TIMEOUT - for other object level change entries
. QIBM_JO_APPLY_CM_RB_CN_TIMEOUT - commit (C CM), rollback (C RB), cancel rollback (C CN) entry
The value for all the environment variables is in seconds.
The minimum for any of these environment variable is 60 seconds. If a value of less than 60 is specified for any of these environment variables, a value of 60 seconds will be used.
Environment variables must be in all capital letters and set before issuing the APYJRNCHG command.
Note: The commands to manipulate environment variables are Add Environment Variable (ADDENVVAR), Change Environment Variable (CHGENVVAR) and Work with Environment Var (WRKENVVAR).
A secondary thread is used to apply the object level changes for library objects. The apply of some journal entries may fail if the QMLTTHDACN system value is set to 3 (*NORUN). The recommended setting for QMLTTHDACN during an APYJRNCHG operation is 2. The status of the secondary thread may be monitored using WRKJOB option 20.
The journaled changes are applied from the specified starting point, either the point at which an object was last saved or a particular entry on the journal, until the specified ending point has been reached. The ending point can be the point at which the object has had all changes applied, the object was last restored, a specified entry has been reached, a specified time has been reached, or the object was opened or closed by a job (the CMTBDY parameter is used for handling changes that are still pending).
If you remove any database file members, delete any database files, or delete any integrated file system objects prior to restoring objects as part of your recovery scenario, you must be careful when selecting the range of journal entries to apply. Remember that the following entries in the journal will be applied if they are included in the specified range.
. Journal code F entry type DM (delete member)
. Journal code D entry type DT (delete file)
. Journal code B entry type BD (integrated file system object deleted)
In these cases, it is recommended that you specify either a specific ending journal sequence number, or recover to a specific date and time (which would be prior to starting any recovery steps).
Note: The Display Journal (DSPJRN) command can be used to help determine the desired starting and/or ending points.
A list of journaled objects can be specified. The journaled changes are applied in the order that the journal entries are found on the journal, which is the same order in which the changes were made to the objects.
For database files, record-level operations are not performed under commitment control. However, any database file object-level operations that were originally performed under commitment control are also performed under commitment control during the apply. If the commitment control transaction was originally committed, the object-level operations will be committed when the corresponding commit entry is applied. If the commitment control transaction was originally rolled back, the object-level operations will be rolled back when the corresponding rollback entry is applied. If the commitment control operation does not end within the range of journal entries being applied, then the changes are rolled back.
When applying database object-level changes, if the apply ends before the corresponding commit or rollback entry is applied, any pending object-level operations for database files are either committed or rolled back, depending on whether the transaction was originally committed or rolled back. This is different than what happens with database file record-level changes. For database file record-level changes, if an error occurs during an apply operation, the journal sequence number of the last successfully-applied entry is returned. Everything up to that journal sequence number is guaranteed to be applied, so the user may be able to start the apply again starting with the journal sequence number returned plus one. Since pending database file object-level operations prior to that journal sequence number may be rolled back, careful examination of the journal and user intervention is required before starting the apply again.
When applying all object-level changes, if a ROLLBACK of an object-level operation for a database file occurs due to an error condition, or one of the remaining journal entries which cause the APYJRNCHG command to end, the system may potentially be in a state where partial record-level changes have been applied and some transactions are not at a commit boundary. Careful examination of the journal and user intervention is required at this point.
For example, a transaction contains several inserts, followed by an ALTER TABLE to add a column, followed by several more inserts (with the new record length), but ends in a ROLLBACK. If the apply operation was interrupted just after the ALTER TABLE, the system would recognize that the transaction ended in a ROLLBACK and would roll back the ALTER TABLE. If the apply operation were restarted in this case, the second set of inserts would fail due to a record length mismatch. While this scenario is unlikely, it is important to understand the mechanics behind the apply, in order to continue the apply after an error.
If a journal code J entry type SI (Enter JRNSTATE(*STANDBY)) entry is found, the operation ends for all objects specified regardless of the OBJERROPT value specified. Objects may be only partially updated from the journal entries.
Additionally, the command can end applying for an individual object when journal entries list operations which cannot be replayed by the command. If additional changes for this particular object are encountered during this apply, then those changes will not be applied. However, the operation will continue for the other objects specified if OBJERROPT(*CONTINUE) is used. For example, the command ends for an object when a journal entry is found that indicates one of the following has occurred:
. An object was in use at system end and could not be synchronized with the journal. . An object was restored.
. The system had already applied or removed the changes through the Apply Journaled Changes (APYJRNCHG) command or the Remove Journaled Changes (RMVJRNCHG) command.
The command also ends for an object when illogical conditions are encountered, such as attempts to do the following:
. To add a record to an existing relative record number for a database file member
. To add a record beyond the next record position after the end of the database file
. To add a record that has a duplicate key for a database file member
. To delete a deleted record for a database file member
. To update a nonexistent record for a database file member
. To add a link to a nonexistent directory
Most illogical conditions are caused by starting the apply journaled changes operation at the wrong place in the journal with respect to the current contents of the objects.
If the command ends due to illogical conditions and it is logically possible to restart the apply operation, you can issue the command again specifying a new starting sequence number.
It is possible to apply changes even if the sequence numbers have been reset. The system sends an informational message and continues to apply the changes.
Restrictions:
. This command is shipped with public *EXCLUDE authority and the QPGMR and QSRV user profiles have private authorities to use the command. If FILE(library-name/*ALL) or OBJ(library-name/*ALL) is specified, the journal entries for objects to which a user is not authorized will be ignored.
. The objects specified on this command must currently have their changes journaled.
. If a restore operation occurs before the apply operation, the object being restored must have been journaled at the time of the save operation.
. The objects indicated on the command are allocated exclusively while the changes are being applied. If an object cannot be allocated, the command ends and no journaled changes are applied.
. If there is no journal entry that corresponds to the period indicated on the command, the command ends and no journaled changes are applied.
. If the journal sequence numbers have been reset in the range of the receivers specified, and a sequence number is specified on the FROMENTLRG, FROMENT, TOENTLRG, or TOENT parameter, the first occurrence of the sequence number specified on one of the parameters is used.
. The TOJOBO and TOJOBC parameters cannot be used to specify when the apply journaled changes operation is to end if one or more journal receivers in the specified receiver range was attached to a journal with a receiver size option (RCVSIZOPT) or a fixed length data option (FIXLENDTA) that would have omitted this data was in effect.
. The TOJOBO and TOJOBC parameters cannot be used if the object for which changes are being applied was not recording open and close entries. For further clarification, refer to the Omit journal entry (OMTJRNE) parameter for the STRJRN, STRJRNPF, and CHGJRNOBJ commands.
. The maximum number of objects that can have changes applied with this command is 12,000,000. If more than 12,000,000 objects are included in the specifications, an error message is sent and no changes are applied. You can change the values specified on the FILE, OBJ or OBJPATH parameter so that the limit is not exceeded. The limit will include any objects which are created as a result of applying the journaled changes to another object. This can happen during the apply operation if applying a file entry which then attempts to create a member or if applying a directory entry which then attempts to create an integrated file system object. If this limit is reached, the new member or the integrated file system object will not be created. APYJRNCHG will stop applying for the file or the directory that caused the create operation. All entries to the file or directory prior to this point will remain applied. Also, the apply operation will continue applying for any other members of the file or any other integrated file system objects in the directory that were created prior to the limit of 12,000,000 objects being exceeded if OBJERROPT(*CONTINUE) was specified. When applying changes for a database file, there is one object associated with each member and one additional object associated with the file.
. If OBJ(*ALLJRNOBJ) is specified, then the OBJPATH parameter cannot also be specified. OBJ(*ALLJRNOBJ) will include integrated file system objects.
. Using APYJRNCHG to apply changes from a journal receiver with journal entries deposited from another release (either previous or later) may cause unexpected results.
Examples:
Example 1: Applying Changes to First Member
APYJRNCHG JRN(FIN/JRNACT) FILE(FIN/RCVABLE)
This command causes the system to apply to the first member of file RCVABLE in library FIN all changes journaled to JRNACT in library FIN since the file was last saved. The receiver range is determined by the system. The changes are applied beginning with the first journaled change on the receiver chain after the file was last saved and continue through all applicable journal entries to the point at which the file was last restored.
Example 2: Applying Changes to a Specific Member
APYJRNCHG JRN(JRNA) FILE((LIB2/PAYROLL JAN))
RCVRNG(RCV22 RCV25)
FROMENT(*FIRST) TOENT(*LAST)
This command causes the system to apply all changes journaled to JRNA to member JAN of the file PAYROLL in library LIB2. The journal receivers containing the journaled changes are contained in the receiver chain starting with receiver RCV22 and ending with receiver RCV25. Applying the changes starts with the first change journaled on this receiver chain and ends with the last change journaled on this receiver chain. The library search list (*LIBL) is used to find the journal JRNA and the journal receivers RCV22 and RCV25.
Example 3: Applying Changes to integrated file system Objects
APYJRNCHG JRN(JRNS/JRNA)
OBJPATH((¡¯/HRinfo/payroll/Jan*¡¯)
(¡¯/HRinfo/payroll/JanSummary¡¯ *OMIT))
SUBTREE(*ALL)
PATTERN((¡¯*.data¡¯) (¡¯Temp*.data¡¯ *OMIT))
RCVRNG(*CURRRENT)
FROMENT(20) TOENT(400)
This command causes the system to apply changes to integrated file system objects. The changes will be applied from starting sequence number 20 to ending sequence number 400 found in the journal receiver currently attached to journal JRNS/JRNA.
1. All objects in the integrated file system subtree ¡¯/HRinfo/payroll¡¯ that start with the characters ¡¯Jan¡¯, but omitting the object named ¡¯/HRinfo/payroll/JanSummary¡¯.
2. All objects in the subtree of any directories that matched number 1, whose names end with ¡¯.data¡¯, but omitting names ending in ¡¯.data¡¯ that begin with the characters ¡¯Temp¡¯.