Apply Journaled Changes Extend (APYJRNCHGX)

Where allowed to run: All environments (*ALL)
Threadsafe: No

The Apply Journaled Changes Extend (APYJRNCHGX) 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.

There are slight differences between this command and the Apply Journaled Changes (APYJRNCHG) command. This command only applies entries for database files and requires entries to be applied for all files in a library.

Note: The Apply Journal Changes Extend (APYJRNCHGX) command is a tactical solution that provides function that was not provided by the standard APYJRNCHG command until V6R1M0. Support for the APYJRNCHGX command will be withdrawn in a future release.

Some object level changes that are applied are entries from SQL statements. The replay of these entries can cause the Apply Journaled Changes (APYJRNCHGX) 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, delete file (D DT) entry, and delete member (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 APYJRNCHGX command.

Note: The commands to manipulate environment variables are Add Environment Variable (ADDENVVAR), Change Environment Variable (CHGENVVAR) and Work with Environment Var (WRKENVVAR).

See the Journal management topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for a complete listing of the various entries and how they are handled by this command including those entries which can stop the command. Search for "actions of applying or removing journaled changes".

APYJRNCHGX has nearly the same parameter list as APYJRNCHG for compatibility purposes but the OBJ and OBJPATH parameters are not available. Also, the file specification is restricted to library/*ALL, and the member specification is restricted to *ALL

A secondary thread is used to apply the object level changes. 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 APYJRNCHGX 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).

Note: If you delete any files prior to restoring the database library as part of your recovery scenario, you must be careful when selecting the range of journal entries to apply. Remember that "DELETE FILE" entries in the journal will be applied, if they are included in the specified range. In this case, 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.

Like the APYJRNCHG command, record-level operations are not performed under commitment control. However, any 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 an error occurs during the apply before the corresponding commit or rollback entry is applied, any pending object level operations are either committed or rolled back, depending on whether the transaction was originally committed or rolled back. Since pending 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.

If a ROLLBACK of an object level operation occurs due to an error condition, 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 specified. For example, the command ends for an object when a journal entry is found that indicates one of the following has occurred:

A physical database file member was restored.
Journaling was ended for a physical database file.
The system had already applied or removed the changes through the Apply Journaled Changes (APYJRNCHG or APYJRNCHGX) 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

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.
The objects specified on this command must currently have their changes journaled.
Commitment control cannot be active in the job prior to using this command.
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 FROMENT, FROMENTLRG, TOENT, or TOENTLRG parameter, the first occurrence of the sequence number specified on any 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 RCVSIZOPT(*MINFIXLEN) 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, STRJRNLIB, 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.
This limit will include any objects which are created as a result of applying object level operations. If this limit is reached, the new member will not be created. The apply will end for the object that was causing the create (a database file) at that point (and all entries up to that point will be applied). The apply will continue with other members in the file and other files 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.
Using APYJRNCHGX to apply changes from a journal receiver with journal entries deposited from another release (either previous or later) may cause unexpected results.
APYJRNCHGX cannot be used to apply changes from journal receivers that may be missing journal entries due to remote journal object filtering or program filtering.

Keyword	Description	Choices	Notes
JRN	Journal	Qualified object name	Required, Positional 1
	Qualifier 1: Journal	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
FILE	Journaled file identification	Values (up to 300 repetitions): Element list	Required, Positional 2
	Element 1: Journaled physical file	Qualified object name
	Qualifier 1: Journaled physical file	*ALL
	Qualifier 2: Library	Name
	Element 2: Member	*ALL
RCVRNG	Range of journal receivers	Single values: LASTSAVE, CURRENT Other values: Element list	Optional, Positional 3
	Element 1: Starting journal receiver	Qualified object name
	Qualifier 1: Starting journal receiver	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
	Element 2: Ending journal receiver	Single values: *CURRENT Other values: Qualified object name
	Qualifier 1: Ending journal receiver	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
FROMENTLRG	Starting large sequence number	Character value, LASTSAVE, FIRST	Optional
TOENTLRG	Ending large sequence number	Character value, LASTRST, LAST	Optional
TOTIME	Ending date and time	Element list	Optional
	Element 1: Ending date	Date
	Element 2: Ending time	Time
TOJOBO	Fully qualified job name	Qualified job name	Optional
	Qualifier 1: Fully qualified job name	Name
	Qualifier 2: User	Name
	Qualifier 3: Number	000000-999999
TOJOBC	Fully qualified job name	Qualified job name	Optional
	Qualifier 1: Fully qualified job name	Name
	Qualifier 2: User	Name
	Qualifier 3: Number	000000-999999
CMTBDY	Commitment boundary	YES, NO	Optional
OPTION	Option	NONE, IGNINQMSG	Optional
OBJERROPT	Object error option	CONTINUE, END	Optional
OUTPUT	Output	NONE, OUTFILE	Optional
OUTFILE	File to receive output	Qualified object name	Optional
	Qualifier 1: File to receive output	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
OUTMBR	Output member options	Element list	Optional
	Element 1: Member to receive output	Name, *FIRST
	Element 2: Replace or add records	REPLACE, ADD
DETAIL	Detail	ALL, ERR	Optional
FROMENT	Starting sequence number	1-9999999999, LASTSAVE, FIRST	Optional
TOENT	Ending sequence number	1-9999999999, LASTRST, LAST	Optional

Apply Journaled Changes Extend (APYJRNCHGX)

Restrictions:

Parameters

Journal (JRN)

Qualifier 1: Journal

Qualifier 2: Library

Journaled file identification (FILE)

Element 1: Journaled physical file

Qualifier 1: Journaled physical file

Qualifier 2: Library

Element 2: Member

Range of journal receivers (RCVRNG)

Single values

Element 1: Starting journal receiver

Qualifier 1: Starting journal receiver

Qualifier 2: Library

Element 2: Ending journal receiver

Qualifier 1: Ending journal receiver

Qualifier 2: Library

Starting large sequence number (FROMENTLRG)

Ending large sequence number (TOENTLRG)

Ending date and time (TOTIME)

Element 1: Ending date

Element 2: Ending time

Fully qualified job name (TOJOBO)

Fully qualified job name (TOJOBC)

Commitment boundary (CMTBDY)

Option (OPTION)

Object error option (OBJERROPT)

Output (OUTPUT)

File to receive output (OUTFILE)

Qualifier 1: File to receive output

Qualifier 2: Library

Output member options (OUTMBR)

Element 1: Member to receive output

Element 2: Replace or add records

Detail (DETAIL)

Starting sequence number (FROMENT)

Ending sequence number (TOENT)

Examples

Example:

Error messages