APYJRNCHG (Apply Journaled Changes)

APYJRNCHG Command syntax diagram

 

Purpose

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. 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: 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.

If an error is found at any point while the journal entries are being applied, the operation ends and the objects might be only partially updated from the journal entries.

Additionally, the command can end when journal entries list operations which cannot be replayed by the command. For example, the command ends when a journal entry is found that indicates one of the following has occurred:

See the Journal management article in the Information Center> for a complete listing of the various entries and how they are handled by this command including those entries which can stop the command.

The command also ends on illogical conditions, such as attempts to do the following:

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.

Note: If applying journaled changes ends for one of the objects specified, it ends for all of the objects specified.

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:

  1. This command is shipped with public *EXCLUDE authority and the QPGMR and QSRV user profiles have private authorities to use the command.

  2. The objects specified on this command must currently have their changes journaled and they must have been journaled to the specified journal throughout the period indicated on the command.

  3. If a restore operation occurs before the apply operation, the object being restored must have been journaled at the time of the save operation.

  4. 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.

  5. If there is no journal entry that corresponds to the period indicated on the command, the command ends and no journaled changes are applied.

  6. If the journal sequence numbers have been reset in the range of the receivers specified, and a sequence number is specified on the FROMENT or TOENT parameter, the first occurrence of the sequence number specified on either parameter is used.

  7. 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

    that had a RCVSIZOPT or FIXLENDTA option specified that omitted the collection of that data. >

  8. The maximum number of objects that can have changes applied with this command is 65,535. If more than 65,535 objects are included in the specifications, an error message is sent and no changes are applied. You can change the values specified on this parameter so that the limit is not exceeded.

    This limit will include any objects which are created as a result of applying the journaled changes to another object.

 

Required Parameters

JRN
Specifies the qualified name of the journal associated with the journal entries that are applied.

The name of the journal can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

journal-name: Specify the name of the journal associated with the journal entries being applied.

FILE
Specifies a maximum of 300 qualified names of physical database files to which journal entries are being applied.

Either the FILE parameter must be specified or the Object Information parameters (OBJ or OBJPATH) must be specified, but not both.

Element 1: File Name

The name of the file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

*ALL: All physical files in the specified library whose changes are journaled to the specified journal have their journal entries applied. The library name must be specified. If *ALL is specified and the user does not have the required authority for all the files in the library, a message is sent and the applying of journal entries ends.

file-name: Specify the name of the physical database file that is to have its journal entries applied.

Element 2: Member Name

The FILE parameter also specifies the name of the member in the file that has its journal entries applied.

*FIRST: The first member in the file has its journal entries applied.

*ALL: All members in the file have their journal entries applied.

member-name: Specify the name of the member in the file that has its journal entries applied.

If *ALL is specified for the first part of this parameter, the value specified for the member name is used for all applicable files in the library. For example, if *FIRST is specified, the first member of all applicable files in the library has the changes applied.

OBJ
Specifies a maximum of 300 qualified object names to which journal entries are being applied.

Either the FILE parameter must be specified or the Object Information parameters (OBJ or OBJPATH) must be specified, but not both.

Element 1: Object

The name of the object can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

*ALL: All objects in the specified library of the specified type whose changes are journaled to the specified journal have their journal entries applied. The library name must be specified. If *ALL is specified and the user does not have the required authority for all objects in the library, a message is sent and the applying of journal entries ends.

object-name: Specify the name of the object that is to have its journal entries applied.

Element 2: Object Type

*FILE: Entries for database file members are applied.

*DTAARA: Entries for data areas are applied.

Element 3: Member Name

*FIRST: The first member in the file has its journal entries applied.

*ALL: All members in the file have their journal entries applied.

member-name: Specify the name of the member in the file that has its journal entries applied.

If *ALL is specified for the first part of this parameter, the value specified for the member name is used for all applicable files in the library. For example, if *FIRST is specified, the first member of all applicable files in the library has the changes applied.

Note: If the specified object-type was not *FILE, the member name value is ignored.

OBJPATH
Specifies a maximum of 300 object path names to which journal entries are being applied. Only objects whose path name identifies an object of type *STMF, *DIR or *SYMLNK that is in the Root ('/'), QOpensys, and User-defined file systems are supported.

Either the FILE parameter must be specified or the Object Information parameters (OBJ or OBJPATH) must be specified, but not both.

Element 1: Path Name

path-name: Specify the name of the object that is to have it journal entries applied.

In the last component of the path name, an asterisk (*) or a question mark (?) can be used to search for patterns of names. The * tells the system to search for names that have any number of characters in the position of the * character. The ? tells the system to search for names that have a single character in the position of the ? character. Symbolic links within the path name will not be followed. If the path name begins with the tilde (~) character, then the path is assumed to be relative to the appropriate home directory. For more information on specifying path names, refer to path names.

Additional information about path name patterns is in the Integrated file system topic in the File systems and management category of the Information Center.

Element 2: Include or Omit

The second element specifies whether names that match the path name or a pattern should be included or omitted from the operation. Note that in determining whether a name matches a pattern, relative name patterns are always treated as relative to the current working directory.

Note: The SUBTREE parameter specifies whether the subtrees are included or omitted.

*INCLUDE: The objects that match the object name pattern are to be included in determining what journal entries are being applied, unless overridden by an *OMIT specification.

*OMIT: The objects that match the object name pattern are not to be included in determining what journal entries are being applied. This overrides an *INCLUDE specification and is intended to be used to omit a subset of a previously selected pattern.

 

Optional Parameters

SUBTREE
Specifies whether the directory subtrees are included in determining the objects for which journal entries are being applied.

Note: This parameter is only valid if one or more path names were specified on the OBJPATH parameter.

*NONE: Only the objects that match the selection criteria are processed. The objects within selected directories are not implicitly processed.

*ALL: All objects that meet the selection criteria are processed in addition to the entire subtree of each directory that matches the selection criteria. The subtree includes all subdirectories and the objects within those subdirectories.

PATTERN
Specifies a maximum of 20 patterns to be used to include or omit objects for which journal entries are being applied.

Note: This parameter is only valid if one or more path names were specified on the OBJPATH parameter.

Element 1: Name Pattern

'*': All objects that match the input OBJPATH parameter are to be included.

name-pattern: Specify the pattern to be used to include or omit objects for which journal entries are being applied. Only the last part of the path name will be considered for the name pattern match. Path name delimiters are not allowed in the name pattern.

If the Name Pattern parameter is not specified the default will be to match all patterns.

For more information on specifying path names, refer to path names.

Additional information about path name patterns is in the Integrated file system topic in the File systems and management category of the Information Center.

Element 2: Include or Omit

The second element specifies whether names that match the pattern should be included or omitted from the operation. Note that in determining whether a name matches a pattern, relative name patterns are always treated as relative to the current working directory.

*INCLUDE: The objects that match the object name pattern are included in the operation, unless overridden by an *OMIT specification.

*OMIT: The objects that match the object name pattern are not to be included in the operation. This overrides an *INCLUDE specification and is intended to be used to omit a subset of a previously selected pattern.

RCVRNG
Specifies the starting and ending journal receivers used in applying the journal entries. The system begins by applying the journal entries in the first journal receiver in this journal receiver range and proceeds through the receivers until it applies the journal entries in the last journal receiver in this journal receiver range.

Note: The maximum number of receivers that can be included in a range of receivers is 256. If more than 256 receivers are included in the range specified, an error message is sent and no changes are applied. You can change the values specified on this parameter so that the limit is not exceeded.

*LASTSAVE: The range of journal receivers used is determined by the system, as a result of save information for the objects that have their journaled changes applied. This parameter value is only valid if FROMENT(*LASTSAVE) is also specified.

*CURRENT: The journal receiver that is currently attached when starting to apply journal entries is used.

Element 1: Starting Journal Receiver

The name of the journal receiver can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

starting-journal-receiver: Specify the name of the journal receiver used as the first (oldest) receiver.

Element 2: Ending Journal Receiver

*CURRENT: The journal receiver that is currently attached when starting to apply journal entries is used.

The name of the journal receiver can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

ending-journal-receiver: Specify the name of the journal receiver used as the last (newest) receiver with journal entries to be applied. If the end of the receiver chain is reached before finding this receiver, no entries are applied, and an escape message is sent.

FROMENT
Specifies the entry that is used as the starting point for applying changes that have been journaled.

*LASTSAVE: The journal entries are applied beginning with the first journal entry after the object was last saved. The system determines the actual starting position for each of the objects specified on the command. The parameter value implies that the object was just restored on the system.

The system verifies information for each object specified, such as if the date and time of the restore is after the date and time of the last save. The system also verifies that the date and time of the saved version of the object that is restored on the system is the same as the date and time that the object was last saved, as indicated on the journal.

If the dates and times do not match, no entries are applied and an inquiry message is sent to the user or system operator requesting a cancel or ignore response. If an ignore response is given to the message, the operation is attempted. A cancel response causes the operation to end, and no journal entries are applied.

If the object was last saved with the save-while-active function, the saved copy of each object includes all changes in the journal entries up to the corresponding start-of-save journal entry. In this case, the system applies changes beginning with the first journal entry following the start-of-save entry.

If the object was last saved when it was not in use (normal save), the saved copy of each object includes all changes in the journal entries up to the corresponding object saved journal entry. In this case, the system applies changes beginning with the first journal entry following the object saved entry.

*FIRST: The journal entries are applied beginning with the first journal entry in the first receiver supplied in this command.

starting-sequence-number: Specifies the sequence number of the first journal entry that is applied from the journal entries supplied.

TOENT
Specifies the entry used as the ending point for applying changes that are journaled.

*LASTRST: The journal entries are applied ending with the entry before the object was last restored. The system determines the actual ending position for each of the objects specified on the command. The system verifies that the date and time of the restored version of the object on the system is the same as the date and time that the object was last restored, as indicated on the journal. If the dates and times do not match, no entries are applied and an inquiry message is sent to the user or system operator, requesting a cancel or ignore response. If an ignore response is given to the message, the operation is attempted. A cancel response causes the operation to end, and no journal entries are applied.

This parameter value is valid only if FROMENT(*LASTSAVE) is also specified. If no other TO parameter (TOTIME, TOJOBO, TOJOBC) is specified, TOENT(*LASTRST) is assumed.

*LAST: Journal entries are applied through the last entry.

ending-sequence-number: Specify the sequence number of the last entry that is applied to the file member.

TOTIME
Specifies the time and date of the last journal entry that was applied to the file member. The first entry with that or the next earlier time is the ending point for applying journal entries. The format of the date must be defined by the job attributes DATFMT and, if separators are used, DATSEP. The time can be entered as 4 or 6 digits (hhmm or hhmmss), where hh = hours, mm = minutes and ss = seconds. If colons are used to separate the time values, the string must be enclosed in apostrophes ('hh:mm:ss').

Element 1: Ending Date

ending-date: Specify the ending date.

Element 2: Ending Time

ending-time: Specify the ending time.

TOJOBO
Specifies the job identifier of the job that, when it opens an object that is specified, ends the applying of journal entries by this command. The first job open entry found for any of the specified objects, is the ending point for all the objects specified.

Only objects of type *FILE, *DIR or *STMF have journal entries related to job opens.

The job identifier has a maximum of three elements. 

job-name
user-name/job-name
job-number/user-name/job-name

The job name must be specified. The null value (*N) may be used in place of the job number or the user profile name to maintain the position in the sequence. For example, 123456/*N/job-name specifies the job number, 123456, and the job name, without specifying the user profile under which the job is run.

TOJOBC
Specifies the job identifier of the job that ends the applying of journal entries by this command. The first job close entry found for any of the specified objects, is the ending point for all objects specified. The applying of journal entries is ended when either of the following occurs:

  • The specified job closes an object that is specified.

  • The specified job is ended.

Only objects of type *FILE, *DIR or *STMF have journal entries related to job closes.

The job identifier has a maximum of three elements. 

job-name
user-name/job-name
job-number/user-name/job-name

The job name must be specified. The null value (*N) may be used in place of the job number or the user profile name to maintain the position in the sequence. For example, 123456/*N/job-name specifies the job number, 123456, and the job name, without specifying the user profile under which the job is run.

CMTBDY
Specifies whether commitment boundaries are honored when the journal entries to which journaled changes are to be applied are part of a commitment control logical unit of work (LUW). More information on the use of commitment control is in the Commitment control topic in the Information Center.

Note: For purposes of this parameter description, the TO option is used to describe either the TOENT, the TOTIME, the TOJOBO, or the TOJOBC parameter, whichever is specified.

*NO: The journal entries are applied from the entry specified on the FROMENT parameter to the entry indicated on the TO option, regardless of commitment boundaries. Even if a journal entry within this range is a participant of the LUW, the operation is attempted.

*YES: The journal entries are applied from the entry specified on the FROMENT parameter to the entry indicated on the TO option, honoring commitment boundaries.

  • If the journal entry specified on the FROMENT parameter is in the middle of the LUW of which it is a participant, an error message is sent and the operation is not attempted.

  • If the journal entry indicated on the TO option is in the middle of the LUW of which it is a participant, the operation stops at the commitment boundary before that journal entry. A diagnostic message is sent at the end of the operation.

Note: If a journal entry is encountered that causes the operation to end before the entry indicated on the TO option, commitment boundaries might not be honored.

Examples for APYJRNCHG

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 IFS Objects 

APYJRNCHG JRN(JRNS/JRNA) OBJPATH(('/HRinfo/payroll/Jan*')            
('/HRinfo/payroll/JanSummary' *OMIT))                                
SUBTREE(*ALL) PATTERN(('*.data') ('Temp*.data' *OMIT))               
FROMENT(20) TOENT(400)

This command causes the system to apply changes to IFS objects. The changes will be applied from starting sequence number 20 to ending sequence number 400 in journal JRNS/JRNA.

  1. All objects in the IFS 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'.

Error messages for APYJRNCHG

*ESCAPE Messages

CPFA0D4
File system error occurred.
CPF70CC
Cannot perform operation beyond journal entry &7.
CPF70CD
Cannot perform operation beyond journal entry &7.
CPF70CE
Cannot perform operation beyond journal entry &7.
CPF70EB
Referential constraint error on member &3.
CPF70EC
Referential constraint error. Reason code &9.
CPF70EE
Maximum encoded vector access paths for member &3.
CPF7002
File &1 in library &2 not a physical file.
CPF7003
Entry not journaled to journal &1. Reason code &3.
CPF7006
Member &3 not found in file &1 in &2.
CPF7007
Cannot allocate member &3 file &1 in &2.
CPF701B
Journal recovery of an interrupted operation failed.
CPF704A
Record length incorrect for member &3.
CPF704F
TOJOBO or TOJOBC parameter not valid for receiver range.
CPF7041
Entry for job &3/&2/&1 not found.
CPF7042
Object not journaled or journaled to different journal.
CPF7044
Apply or remove of journaled entries failed, reason code &7.
CPF7045
Journal receiver &1 in &2 partially damaged.
CPF7046
Duplicate key not allowed for member &3.
CPF7047
Member &3 file &1 in &2 full.
CPF7048
Cannot perform journaled change to member &3.
CPF7049
Cannot perform operation beyond journal entry &6.
CPF705A
Operation failed due to remote journal.
CPF7050
LASTSAVE date not same as restored version of *&4 object.
CPF7051
Save entry for *&6 object not found in RCVRNG.
CPF7052
Select/omit failure in logical file over member &3.
CPF7053
Values for RCVRNG parameter not correct; reason code &1.
CPF7054
FROM and TO values not valid.
CPF7055
Maximum number of objects exceeded.
CPF7057
*LIBL not allowed with FILE(*ALL) or OBJ(*ALL).
CPF7058
Apply or remove journaled entries operation failed.
CPF7059
Entry for &1 not found in RCVRNG.
CPF7067
FROMENT option not valid. Commit boundary violation.
CPF7068
Entry needed for apply or remove operation not found.
CPF7069
No entries applied or removed using journal &1.
CPF7075
Restore date of *&4 object not same as in journal.
CPF7076
Restore entry for *&6 object not found in RCVRNG.
CPF7077
Key mapping error on member &3.
CPF7078
Cannot apply or remove changes to member &3.
CPF9801
Object &2 in library &3 not found.
CPF9802
Not authorized to object &2 in &3.
CPF9803
Cannot allocate object &2 in library &3.
CPF9809
Library &1 cannot be accessed.
CPF9810
Library &1 not found.
CPF9812
File &1 in library &2 not found.
CPF9820
Not authorized to use library &1.
CPF9822
Not authorized to file &1 in library &2.