CHGJRN

CHGJRN (Change Journal)

CHGJRN Command syntax diagram

Purpose

The Change Journal (CHGJRN) command changes the journal receiver, the journal message queue, the manage receivers attribute, the delete receivers attribute, the receiver size options, the journal state, allowing minimized entry specific data,
journal caching,
or the text associated with the specified journal. The command allows one journal receiver to be attached to the specified journal. This replaces the previously attached journal receiver. The newly-attached journal receiver begins receiving journal entries for the journal immediately.
The sequence numbering of journal entries can be reset when the receiver is changed. If the sequencing is not reset, an informational message is sent indicating the first sequence number in the newly attached receiver. If RCVSIZOPT(*MAXOPT1 or *MAXOPT2) is in effect for the journal, informational message (CPF7019) is sent to the system operator recommending that the sequence numbers be reset when the first sequence number is greater than 9,500,000,000. Otherwise, CPF7019 is sent when the first sequence number is greater than 2,000,000,000.
If JRNRCV is *SAME, the currently attached journal receiver remains attached.
The journal receiver can be changed when these journal functions are in progress: comparing images, displaying journals, receiving or retrieving journal entries, applying or removing journal changes, working with journal attributes, or display journal receiver attributes.

Restrictions

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

The receiver specified must be created before issuing this command, and it must be empty (that is, the receiver must not have been previously attached to a journal or have been in the process of being attached to a journal).

No more than one journal receiver can be attached to the journal at any specific time.

Resetting of sequence numbers is not valid if JRNRCV is *SAME, if any objects being journaled contain changes that have not yet been forced to auxiliary storage, or if any commitment control changes associated with the journal are pending. When the maximum sequence number is reached, an error message is sent (entry not journaled) and all subsequent operations that require journaling fail.

If RCVSIZOPT(*MAXOPT1 or *MAXOPT2) is not to be in effect for the journal, the maximum threshold value that can be specified for any journal receiver being attached is 1,919,999 kilobytes.

SEQOPT(*RESET) must be specified if the journal currently has RCVSIZOPT(*MAXOPT1 or *MAXOPT2) in effect, and neither *MAXOPT1 or *MAXOPT2 is being specified as part of the CHGJRN request.

If the library containing the journal is on an independent ASP then the journal receiver specified must be located on an independent ASP that is in the same ASP group as the journal's library. Likewise, if the library containing the journal is not on an independent ASP, then the journal receiver specified cannot be located on an independent ASP.

RCVSIZOPT(*MINFIXLEN) and FIXLENDTA cannot be used for the system security audit journal QSYS/QAUDJRN. Journal entries in the security audit journal are required to contain all possible data that could be used for auditing purposes.

Required Parameters

JRN

Specifies the qualified name of the journal for which journal receivers or operational attributes are being changed.
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 journal having journal receivers or operational attributes changed.

Optional Parameters

JRNRCV

Specifies which journal receiver to attach to the specified journal.
*SAME: The value does not change.
*GEN: The journal receiver is created by the system and then attached to the specified journal. The journal receiver is created with the same attributes, with the same owner, with the same authorities, with the same audit level, and in the same library as the currently-attached journal receiver. The name of the new journal receiver is derived by appending a 4-digit number to a portion of the name of the current receiver, or by adding 1 to the number in the name of the current journal receiver. The name of the journal receiver that was created and attached is returned in an informational message. More information on generated journal receiver names is in the Journal management article in the Information Center.
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.

receiver-name: Specify the name of the journal receiver being attached to the identified journal. The journal receiver must have been previously created in the specified library, and must not have been previously attached to a journal or have been in the process of being attached to a journal.
Up to 2 journal receivers can be specified, but the second journal receiver is ignored.

SEQOPT

Specifies whether the journal sequence number is continued from the currently attached journal receiver or the journal sequence number is reset to 1 in the newly attached journal receiver.
*CONT: The journal sequence number of the next journal entry created is 1 greater than the sequence number of the last journal entry in the currently attached journal receiver.
*RESET: The journal sequence number of the first journal entry in the newly attached journal receiver is reset to 1. *RESET is not valid if JRNRCV(*SAME) is specified, if any object being journaled contains changes that have not yet been forced to auxiliary storage, or if any commitment control changes associated with the journal are pending.

MSGQ

Specifies the qualified name of the message queue associated with the journal. A message is sent to this queue when one of the following occurs:

When an attached journal receiver's threshold is surpassed, the message CPF7099 is sent if the journal has the MNGRCV(*USER) attribute.

When an attached journal receiver's threshold is surpassed, the system attempts to create and attach a new receiver if the journal has the MNGRCV(*SYSTEM) attribute. When the old receiver is detached, the message CPF7020 is sent. If the attempt fails due to lock conflicts, the system sends the message CPI70E5 and then tries again every ten minutes (or as often as requested via the MNGRCVDLY parameter)> until the change journal operation is successful.

If the journal receiver was attached while RCVSIZOPT(*MAXOPT1 or *MAXOPT2) was in effect for the journal, message CPI70E7 is sent when the sequence number exceeds 9,900,000,000. Otherwise, message CPI70E7 is sent when a journal receiver's sequence number exceeds 2,147,000,000.

When the system cannot determine if the journal has the MNGRCV(*SYSTEM) attribute, or if the attempt to create and attach a new journal receiver fails because of something other than a lock conflict, the message CPI70E3 is sent.

When remote journal operations occur. See the Journal management article in the Information Center for more details.

When the system cannot delete a receiver due to a lock conflict, an exit program indicating that the receiver cannot be deleted, or the receiver is not yet fully replicated to all remote journals, CPI70E6 is sent and the operation will be retried every 10 minutes (or as often as requested via the DLTRCVDLY parameter).> If a delete fails for any other reason, CPI70E1 is sent.

To set the threshold value, refer to the Create Journal Receiver (CRTJRNRCV) command description.

Note: A message queue that is in library QTEMP cannot be specified on this parameter.

*SAME: The value does not change.
journal-message-queue: Specify the name of the journal message queue to which the journal messages are sent. If this message queue is not available when a message is to be sent, the message is sent to the QSYSOPR message queue.
The name of the journal message queue 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.

MNGRCV

Specifies how the changing of journal receivers (detaching the currently attached journal receiver and attaching a new journal receiver) is managed.
*SAME: The value does not change.
*USER: The user manages the changing of journal receivers by issuing the CHGJRN command to attach a new receiver and detach an old receiver.
*SYSTEM: The system manages the changing of journal receivers (this function is called system change-journal management). When an attached journal receiver reaches its size threshold, the system detaches the attached journal receiver and creates and attaches a new journal receiver. Message CPF7020 is sent to the journal message queue when the journal receiver is detached. Additionally, during an initial program load (IPL), the system performs a CHGJRN command to create and attach a new journal receiver and to reset the journal sequence number of journals that are not needed for commitment control recovery for that IPL. Also, if the journal receiver was attached while RCVSIZOPT(*MAXOPT1 or *MAXOPT2) was in effect for the journal, the system attempts to perform a CHGJRN command to reset the sequence number when the journal receiver's sequence number exceeds 9,900,000,000. For all other journal receivers, the system attempts this CHGJRN when the sequence number exceeds 2,147,000,000.

Notes

The storage space threshold value must be specified on the Create Journal Receiver (CRTJRNRCV) command before this value is specified.

Specifying MNGRCV(*SYSTEM) does not prevent you from using this command to manage journal receivers.

DLTRCV

Specifies whether the system deletes journal receivers when they are no longer needed or leaves them on the system for the user to delete after they have been detached by system change-journal management or by a user-issued CHGJRN command.
*SAME: The value does not change.
*NO: The journal receivers are not deleted by the system.
*YES: The journal receivers are deleted by the system. To specify this value, no receivers other than the currently attached receiver can be in the receiver directory.

Note: To find out which journal receivers are in the receiver directory, you can view the Work with Receiver Directory display, which can be accessed using the Work with Journal Attributes (WRKJRNA) command.

When the journal has the DLTRCV(*YES) attribute, the following conditions can prevent the system from deleting the receiver. When one of these conditions occurs, the system sends message CPI70E6 to the journal message queue, and then retries the delete operation every 10 minutes (or as often as requested via the DLTRCVDLY parameter)> until the operation is successful.

A lock conflict occurs for either the journal receiver or its journal.

An exit program that was registered by way of the QIBM_QJO_DLT_JRNRCV exit point indicates that a receiver is not eligible for deletion.

A journal has remote journals associated with it and one or more of the associated remote journals do not yet have full copies of this receiver.

RCVSIZOPT

Specifies the options that affect the size of the receiver attached to the journal.
*SAME: The value does not change.
*NONE: No options affect the size of the journal entries attached to the receiver. All journal entries placed on the receiver are permanent. The fixed length data as defined by FIXLENDTA will be included in every journal entry deposited into the attached journal receiver. >
*RMVINTENT: The size of the receiver attached to the journal is reduced by automatic removal of the internal entries required only for initial program load (IPL) recovery when these entries are no longer required.
*MINFIXLEN: The size of the journal entries that are deposited into the attached journal receiver is reduced by the automatic removal of fixed-length data that is deemed not to be required for recovery purposes. This option is not valid when FIXLENDTA is also specified. >
*MAXOPT1: If this is specified for the journal, the journal receiver attached to that journal can have a maximum receiver size of approximately one terabyte (1,099,511,627,776 bytes) and a maximum sequence number of 9,999,999,999. Additionally, the maximum size of the journal entry which can be deposited is 15,761,440 bytes. These journal receivers cannot be saved and restored to any releases prior to V4R5M0 nor can they be replicated to any remote journals on any systems at releases prior to V4R5M0.
*MAXOPT2: If this is specified for the journal, the journal receiver attached to that journal can have a maximum receiver size of approximately one terabyte (1,099,511,627,776 bytes) and a maximum sequence number of 9,999,999,999. Additionally, the maximum size of the journal entry which can be deposited is 4,000,000,000 bytes. These journal receivers cannot be saved and restored to any releases prior to V5R1M0 nor can they be replicated to any remote journals on any systems at releases prior to V5R1M0.

Note: To remove a receiver size option, specify all the receiver size options you want to keep and do not specify the one you want to remove.

JRNSTATE

Specifies whether journal entries are allowed to be deposited into the journal.
*SAME: The value does not change.
*ACTIVE: Journal entries are allowed to be deposited into the journal.
*INACTIVE: Journal entries are not allowed to be deposited into the journal. If an attempt is made to deposit an entry into the journal, then an error indicating "Entry not journaled" will be received.
*STANDBY: Journal entries are not deposited into the journal. If an attempt is made to deposit an entry into the journal, then there will be no errors indicating that the entry was not deposited. While in standby state, journaling can be started or stopped. However, using commitment control is not allowed while in standby state. >

Note: See the Journal management article in the Information Center for which journal entries are allowed to be deposited in these states.

MINENTDTA

Specifies which object types allow journal entries to have minimized entry specific data.

Journal receivers with object types allowing minimized entry specific data cannot be saved and restored to any release prior to V5R1M0 nor can they be replicated to any remote journal on a system at a release prior to V5R1M0. See the Journal management article in the Information Center for restrictions and usage of journal entries with minimized entry specific data.
*SAME: The value does not change.
*NONE: No object type allows a journal entry with minimized entry specific data. Journal entries for all journaled objects will be deposited in the journal with complete entry specific data.
*FILE: Journaled files may have journal entries deposited with minimized entry specific data.
*DTAARA: Journaled data areas may have journal entries deposited with minimized entry specific data.

JRNCACHE

Specifies whether journal entries will be cached before written out to disk.
*SAME: The value does not change.
*NO: Journal entries are written to disk immediately if needed to assure single system recovery.
*YES: Journal entries are written to main memory. When there are several journal entries in main memory then the journal entries are written from main memory to disk. If the application performs large numbers of changes, this may result in fewer synchronous disk writes resulting in improved performance. However, it is not recommended to use this option if it is unacceptable to lose even one recent change in the event of a system failure where the contents of main memory are not preserved. This type of journaling is directed primarily toward batch jobs and may not be suitable for interactive applications where single system recovery is the primary reason for using journaling.

Note: Applications using commitment control will likely see less performance improvement because commitment control already performs some journal caching.

MNGRCVDLY

Specifies the time (in minutes) to be used to delay the next attempt to attach a new journal receiver to this journal if the journal is system managed (MNGRCV(*SYSTEM)).
*SAME: The value does not change.
manage-receiver-delay-time: When the system cannot allocate an object needed to attach a new journal receiver to this journal, it will wait the specified number of minutes before trying again. Valid values range from 1 through 1440.

DLTRCVDLY

Specifies the time (in minutes) to be used to delay the next attempt to delete a journal receiver associated with this journal if the journal has DLTRCY(*YES) specified.
*SAME: The value does not change.
delete-receiver-delay-time: When the system cannot allocate an object needed to delete a journal receiver associated with this journal, it will wait the specified number of minutes before trying again. Valid values range from 1 through 1440.

FIXLENDTA

Specifies the data that is included in the fixed-length portion of the journal entries that are deposited into the attached journal receiver. This parameter is not valid when RCVSIZOPT(*MINFIXLEN) is also specified.
*JOBUSRPGM: The job name, user name and program name will be included in the journal entries deposited into the attached journal receiver.
*JOB: The job name will be included in the journal entries deposited into the attached journal receiver.
*USR: The effective user profile name will be included in the journal entries deposited into the attached journal receiver.
*PGM: The program name will be included in the journal entries deposited into the attached journal receiver.
*PGMLIB: The program library name and the auxiliary storage pool device name that contains the program library will be included in the journal entries deposited into the attached journal receiver.
*SYSSEQ: The system sequence number will be included in the journal entries deposited into the attached journal receiver. The system sequence number gives a relative sequence to all journal entries in all journal receivers on the system.
*RMTADR: If appropriate, the remote address, the address family and the remote port will be included in the journal entries deposited into the attached journal receiver.
*THD: The thread identifier will be included in the journal entries deposited into the attached journal receiver. The thread identifier helps distinguish between multiple threads running in the same job.
*LUW: If appropriate, the logical unit of work identifier will be included in the journal entries deposited into the attached journal receiver. The logical unit of work identifies work related to specific commit cycles.
*XID: If appropriate, the transaction identifier will be included in the journal entries deposited into the attached journal receiver. The transaction identifier identifies transactions related to specific commit cycles.>

TEXT

Specifies the text that briefly describes the journal. More information is in Commonly used parameters.
*SAME: The value does not change.
*BLANK: Text is not specified.
'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Examples for CHGJRN
Example 1: Detaching Journal Receiver and Resetting Sequence Numbers
CHGJRN JRN(JRNLA) JRNRCV(RCV10) SEQOPT(*RESET)

This command detaches the journal receiver currently attached to journal JRNLA (JRNLA is found by using the library search list *LIBL). Journal receiver RCV10 (found using the library search list *LIBL) is attached to journal JRNLA. Because SEQOPT(*RESET) is specified, the first journal entry in journal receiver RCV10 has a sequence number of one.
Example 2: Creating and Attaching a New Journal Receiver
CHGJRN JRN(JRNLA) JRNRCV(*GEN)

This command detaches the journal receiver currently attached to journal JRNLA. A new journal receiver is created and attached to journal JRNLA. The library, owner, authority, and auditing level of the new journal receiver is the same as that of the detached receiver. The name of the new receiver depends on the name of the detached receiver. (For example, if the receiver is named RCVJRNA, the new receiver is named RCVJRN0001. If the receiver is named RCVJRN0001, the new receiver is named RCVJRN0002.) The first journal entry in the new journal receiver has a sequence number one greater than the last sequence number in the detached receiver.

Example 3: Changing to Use System Receiver Management
CHGJRN JRN(LIBY/JRN) JRNRCV(LIBX/RCV0001) MNGRCV(*SYSTEM) DLTRCV(*YES) RCVSIZOPT(*MAXOPT2) MNGRCVDLY(10) DLTRCVDLY(30)

This command detaches the journal receiver currently attached to journal JRN. The user previously created the journal receiver RCV0001 in library LIBX. This specified journal receiver is attached to the journal JRN. This new journal receiver will have a maximum size of approximately one terabyte. It will allow the sequence number to reach 9,999,999,999 and the maximum size of a journal entry that can be deposited in the journal receiver is 4,000,000,000 bytes. The first journal entry in the new journal receiver has a sequence number one greater than the last sequence number in the detached receiver. From this point on the system will manage attaching and detaching journal receivers. If the system cannot allocate an object during this process, it will wait 10 minutes and try again. From this point on, the system will also manage deleting the detached receivers. If the system cannot allocate an object while trying to delete the journal receiver it will wait 30 minutes and try again.

Error messages for CHGJRN
*ESCAPE Messages

CPF70A0

FIXLENDTA parameter not allowed.

CPF70A1

FIXLENDTA parameter not allowed with RCVSIZOPT(*MINFIXLEN).

CPF70A2

JRNRCV(*SAME) not allowed.

CPF70C9

State of journal &1 in &2 not changed.

CPF70CF

Cannot inactivate remote journal with given parameters.

CPF70DB

Remote journal function failed.

CPF70DD

Cannot attach dual receivers to journal &1.

CPF70DE

State of journal &1 in &2 not changed.

CPF70DF

Cannot change attribute for a remote journal.

CPF70D1

Cannot activate remote journal through CHGJRN command.

CPF70D2

Cannot detach journal receiver &3.

CPF70D9

Changing journal state not allowed. Reason code &3.

CPF70E0

Operation on &1 not allowed.

CPF70E2

DLTRCV(*YES) not allowed.

CPF70E3

Only attached receivers allowed in receiver directory

CPF70E4

MNGRCV(*SYSTEM) not allowed.

CPF70E5

RCVSIZOPT values specified not allowed.

CPF70E7

MINENTDTA value not allowed with JRNRCV(*SAME).

CPF70F1

Journal receiver threshold too big for journal.

CPF70F5

Receiver threshold value is not valid.

CPF70F6

RCVSIZOPT value specified not allowed.

CPF70F8

RCVSIZOPT and FIXLENDTA value not allowed with JRNRCV(*SAME).

CPF7003

Entry not journaled to journal &1. Reason code &3.

CPF7004

Maximum number of objects journaled to journal &1.

CPF701A

Journal receiver not eligible for operation.

CPF701B

Journal recovery of an interrupted operation failed.

CPF7011

Not enough storage.

CPF7013

Journal receiver not created.

CPF7015

Error on JRNRCV specifications.

CPF7017

Library QTEMP not valid for message queue parameter.

CPF7018

Resetting sequence number not allowed. Reason code &3.

CPF704E

RCVSIZOPT(*MINFIXLEN) not allowed.

CPF708D

Journal receiver found logically damaged.

CPF708E

Journal receiver not allowed with *MAXOPT1 or *MAXOPT2.

CPF708F

Cannot place a remote journal in standby.

CPF709F

Start of journal caching not allowed. Reason code &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.

CPF9804

Object &2 in library &3 damaged.

CPF9806

Cannot perform function for object &2 in library &3.

CPF9810

Library &1 not found.

CPF9820

Not authorized to use library &1.

CPF9825

Not authorized to device &1.

CPF9830

Cannot assign library &1.
CPF9873

ASP status is preventing access to object.

CPF9875

Resources exceeded on ASP &1.