Archiving logs with the ARCHIVE LOG command

An authorized operator can archive the current IBM MQ active log data sets whenever required using the ARCHIVE LOG command.

When we issue the ARCHIVE LOG command, IBM MQ truncates the current active log data sets, then runs an asynchronous offload process, and updates the BSDS with a record of the offload process.

The ARCHIVE LOG command has a MODE(QUIESCE) option. With this option, IBM MQ jobs and users are quiesced after a commit point, and the resulting point of consistency is captured in the current active log before it is offloaded.

Consider using the MODE(QUIESCE) option when planning a backup strategy for off site recovery. It creates a system-wide point of consistency, which minimizes the number of data inconsistencies when the archive log is used with the most current backup page set copy during recovery. For example:

ARCHIVE LOG MODE(QUIESCE)

If we issue the ARCHIVE LOG command without specifying a TIME parameter, the quiesce time period defaults to the value of the QUIESCE parameter of the CSQ6ARVP macro. If the time required for the ARCHIVE LOG MODE(QUIESCE) to complete is less than the time specified, the command completes successfully; otherwise, the command fails when the time period expires. We can specify the time period explicitly by using the TIME option, for example:

ARCHIVE LOG MODE(QUIESCE) TIME(60)

This command specifies a quiesce period of up to 60 seconds before ARCHIVE LOG processing occurs.

Attention: Using the TIME option when time is critical can significantly disrupt IBM MQ availability for all jobs and users that use IBM MQ resources.

By default, the command is processed asynchronously from the time you submit the command. (To process the command synchronously with other IBM MQ commands use the WAIT(YES) option with QUIESCE, but be aware that the z/OS console is locked from IBM MQ command input for the entire QUIESCE period.)

During the quiesce period:

Jobs and users on the queue manager are allowed to go through commit processing, but are suspended if they try to update any IBM MQ resource after the commit.
Jobs and users that only read data can be affected, since they might be waiting for locks held by jobs or users that were suspended.
New tasks can start, but they cannot update data.

The output from the DISPLAY LOG command uses the message CSQV400I to indicate that a quiesce is in effect.

For example, from Version 9.1.4:

CSQJ322I +CSQ1 DISPLAY LOG report ...
Parameter   Initial value          SET value
----------- ---------------------- ----------------------
INBUFF      60                                             
OUTBUFF     400                                            
MAXRTU      2                                              
MAXARCH     2                                            
TWOACTV     YES                                            
TWOARCH     YES                                             
TWOBSDS     YES                                            
OFFLOAD     YES                                            
MAXCNOFF    0                                              
WRTHRSH     20                                             
DEALLCT     0                                              
COMPLOG     NONE                                           
ZHYWRITE    NO                                         
End of LOG report                                          
CSQJ370I +CSQ1 LOG status report ...                       
Copy %Full zHyperWrite Encrypted DSName                                     
 1     68  NO          NO        VICY.CSQ1.LOGCOPY1.DS01                    
 2     68  NO          NO        VICY.CSQ1.LOGCOPY2.DS01                    
Restarted at 2019-08-15 09:49:30 using RBA=000000000891B000
Latest RBA=000000000891CCF8
Offload task is AVAILABLE
Full logs to offload - 0 of 4
CSQV400I +CSQ1 ARCHIVE LOG QUIESCE CURRENTLY ACTIVE
CSQ9022I +CSQ1 CSQJC001 ' DISPLAY LOG' NORMAL COMPLETION

For example, for Long Term Support and Continuous Delivery before Version 9.1.2:

CSQJ322I +CSQ1 DISPLAY LOG report ...
Parameter   Initial value          SET value
----------- ---------------------- ----------------------
INBUFF      60                                             
OUTBUFF     400                                            
MAXRTU      2                                              
MAXARCH     2                                            
TWOACTV     YES                                            
TWOARCH     YES                                             
TWOBSDS     YES                                            
OFFLOAD     YES                                            
MAXCNOFF    0                                              
WRTHRSH     20                                             
DEALLCT     0                                              
COMPLOG     NONE                                           
ZHYWRITE    NO                     YES                     
End of LOG report                                          
CSQJ370I +CSQ1 LOG status report ...                       
Copy %Full PPRC DSName                                     
 1     68  NO   VICY.CSQ1.LOGCOPY1.DS01                    
 2     68  NO   VICY.CSQ1.LOGCOPY2.DS01                    
Restarted at 2014-04-15 09:49:30 using RBA=000000000891B000
Latest RBA=000000000891CCF8
Offload task is AVAILABLE
Full logs to offload - 0 of 4
CSQV400I +CSQ1 ARCHIVE LOG QUIESCE CURRENTLY ACTIVE
CSQ9022I +CSQ1 CSQJC001 ' DISPLAY LOG' NORMAL COMPLETION

When all updates are quiesced, the quiesce history record in the BSDS is updated with the date and time that the active log data sets were truncated, and with the last-written RBA in the current active log data sets. IBM MQ truncates the current active log data sets, switches to the next available active log data sets, and issues message CSQJ311I stating that the offload process started.

If updates cannot be quiesced before the quiesce period expires, IBM MQ issues message CSQJ317I, and ARCHIVE LOG processing terminates. The current active log data sets are not truncated, nor switched to the next available log data sets, and the offload process is not started.

Whether the quiesce was successful or not, all suspended users and jobs are then resumed, and IBM MQ issues message CSQJ312I, stating that the quiesce is ended and update activity is resumed.

If ARCHIVE LOG is issued when the current active log is the last available active log data set, the command is not processed, and IBM MQ issues the following message:

CSQJ319I - csect-name CURRENT ACTIVE LOG DATA SET IS THE LAST
AVAILABLE ACTIVE LOG DATA SET. ARCHIVE LOG PROCESSING
WILL BE TERMINATED

If ARCHIVE LOG is issued when another ARCHIVE LOG command is already in progress, the new command is not processed, and IBM MQ issues the following message:

CSQJ318I - ARCHIVE LOG COMMAND ALREADY IN PROGRESS

For information about the messages issued during archiving, see Messages for IBM MQ for z/OS.

Restarting the log archive process after a failure

If there is a problem during the log archive process (for example, a problem with allocation or tape mounts), the archiving of the active log might be suspended. We can cancel the archive process and restart it by using the following command:

ARCHIVE LOG CANCEL OFFLOAD

This command cancels any offload processing currently in progress, and restarts the archive process. It starts with the oldest log data set that has not been archived, and proceeds through all active log data sets that need offloading. Any log archive operations that have been suspended are restarted.

Use this command only if we are sure that the current log archive task is no longer functioning, or if we want to restart a previous attempt that failed. This is because the command might cause an abnormal termination of the offload task, which might result in a dump.

Parent topic: Manage the logs