Introduction

This article uses a sample program to show how to automate the deletion of journal receivers in an IBM® WebSphere® MQ for iSeries (WebSphere MQ) V5.2 or V5.3 queue manager.

During the normal operation of an IBM WebSphere MQ queue manager, a record is kept of transactions, persistent messages, and changes to queue manager object attributes. This record (or log) of changes is written into the AMQAJRN journal in the queue manager's library. To ensure data integrity, the journal entries are forced to disk, so the journal log represents the definitive history of processing for the queue manager.

Because of its high integrity, the log plays a vital role in the recovery of queue manager data in the event of an abnormal termination, and enables WebSphere MQ to recover queue manager objects if they become damaged. There is a price for this data integrity however, in that keeping all this recovery data consumes a large amount of disk space.

The AMQAJRN journal has a single attached journal receiver, to which journalized data is appended until the receiver reaches a predefined threshold size (100MB in WebSphere MQ for iSeries V5.3). When the receiver threshold size is reached, the operating system detaches the attached receiver and attaches a new one.

As time goes on, the information contained in older journal receivers is superseded, making the receivers redundant and eligible for deletion. WebSphere MQ does not automatically archive and delete these redundant journal receivers, so journal housekeeping must either be performed manually by the system administrator, or automatically by a process such as the one described here.

Back to top

Managing WebSphere MQ's journal receivers

WebSphere MQ only reads information from the journal for two purposes:

1. WebSphere MQ replays journal entries at queue manager startup time to roll back incomplete transactions and ensure that the data in WebSphere MQ queues is up to date. WebSphere MQ keeps track of how much journal information is required to start the queue manager and periodically reports this information to the user as a message (number AMQ7460). The message tells the user the timestamp or name of the oldest journal entry or journal receiver that is required in order to start the queue manager. This is known as the "Startup" journal entry.
2. WebSphere MQ replays journal entries to recover damaged objects -- either at startup time, or when a user issues the RCRMQMOBJ command. The journal entries needed to recover damaged objects are known as "Media recovery" entries, and the earliest entry required depends on the object that is being recovered. The queue manager keeps track of the oldest Media recovery journal entry that is needed to recreate any and all objects should they become damaged. This information is periodically reported to the user as message number AMQ7462.

Having two types of information in the logs, opens up a number of different possible strategies when planning the housekeeping of journal receivers. The options are:

Aggressive housekeeping: Pay no attention to the AMQ7460 and AMQ7462 messages. Archive and delete all journal receivers immediately after they are detached. This option means that minimum disk space is taken up by journal receivers, and the queue manager will be able to operate, but may require journal receivers to be restored in order to recover damaged objects or restart the queue manager.

Housekeeping for fast startup: Archive and delete journal receivers earlier than the one indicated by the AMQ7460 message; that is, keep those journal receivers that are required for startup. This option frees up some disk space and means that you can restart the queue manager without restoring any data, but you may need to restore receivers in order to recover damaged WebSphere MQ objects.

Conservative housekeeping: Under this strategy, you keep journal receivers on the system if they contain either startup or media recovery information. Journal receivers are only deleted once they are completely redundant, so there is no need to archive them before deleting. This requires more disk, but avoids the need to restore journal receivers from backup media, and eliminates the complication of managing journal receiver archives.

In WebSphere MQ V5.3 (and MQSeries V5.2 plus PTF SF67313), whenever the queue manager outputs the AMQ7460 and AMQ7462 messages, the startup and media recovery timestamps are compared, and the oldest timestamp of the two is written to a user space. The user space is called AMQJRNINF and can be found in each queue manager's library.

How the automation works

The command described in this article effectively implements the third technique described above; that is, it only deletes journal receivers once they are completely redundant.

The command invokes a C program, takes the following steps:

1. Read the AMQJRNINF user space to get timestamp of the oldest journal entry that WebSphere MQ needs for restart or for media recovery.
2. Use an OS/400® journal API call (QjoRetrieveJournalInformation) to get the list of receivers that are associated with the queue manager's AMQAJRN journal.
   Important: The program has been written to handle an arbitrary limit of up to 256 receivers in the receiver chain. While you can change this limit, it is not recommended that you let receiver chains get anywhere near this big.
3. Loop through the list of journal receivers from the newest to the oldest, to determine the receiver that contains the oldest journal entry. This will be the oldest receiver that is needed by the queue manager. To find this receiver, the program compares the timestamp of the oldest journal entry to the time that each receiver was attached to the journal. The program assumes that the receiver that contains the oldest journal entry will be the first journal receiver on the system that was attached before the oldest entry was written.
4. Loop through the list of receivers from the oldest to the newest. Delete any journal receivers that are older than the one that contains the oldest journal entry.

For example, in Figure 1, the oldest journal entry we need to keep is the "Media Recovery" entry time stamped 13:09:07.
Tip: The timestamps used by the program are in the form CYYMMDDHHMMSSmmm, but we will use HH:MM:SS in this example for the sake of simplicity.

We start our search at the current receiver AMQA0006, which was attached at 16:28:24. Receivers AMQA0006, AMQA0005, and AMQA0004 are after our timestamp, so we need to keep them. Receiver AMQA0003 was attached at 12:46:49 (before the entry we're looking for), so we can assume that this is the receiver that contains the oldest journal entry. We therefore need to keep receiver AMQA0003.

Earlier receivers do not contain any useful information, and you can be safely delete them.

Downloading and compiling the journal maintenance command and program

The sample is provided as a native OS/400 command and a C program in two source files.

1. Download the source by saving the following links to a PC.
   • jrnmaint.c
   • mqjrnmaint.cmd
2. Log on to your iSeries server, and type the following commands to create a library and source files:

   CRTLIB MQJRNMNT CRTSRCPF MQJRNMNT/QCSRC CRTSRCPF MQJRNMNT/QCMDSRC

   
   
   
3. FTP the source to your iSeries server by typing the following commands on your PC:

   FTP iSeries-hostname -- log on -- ASCII CD MQJRNMNT PUT jrnmaint.c QCSRC.JRNMAINT PUT mqjrnmaint.cmd QCMDSRC.MQJRNMNT QUIT

   
   
   
4. Type the following on the iSeries server to compile the program and the command:

   CRTBNDC MQJRNMNT/JRNMAINT MQJRNMNT/QCSRC CRTCMD CMD(MQJRNMNT/MQJRNMNT) PGM(MQJRNMNT/JRNMAINT) SRCFILE(MQJRNMNT/QCMDSRC)

   
   

Invoking the journal maintenance command

The journal maintenance command ( MQJRNMNT ) has three parameters. To prompt the command, type MQJRNMNT and press F4. Figure 2 shows the options available.

The parameters are:

Figure 3 shows a sample of the output when the program is run with OUTPUT(*PRINT) and DLTRCV(*YES). The output shows that eleven receivers are associated with AMQAJRN. The timestamp of the oldest entry is 14:05:35 on 27/05/03. This entry is contained within receiver AMQA000008, so you can delete receiver AMQA000007 and earlier receivers.

When using MQJRNMNT as part of an automated journal management strategy, you should consider periodically recording media images of all your queue manager objects. This is accomplished by running the command: RCDMQMIMG OBJ(*ALL) OBJTYPE(*ALL) MQMNAME(YourQMGR) DSPJRNDTA(*YES)

This command backs up all of the objects for a queue manager into the latest journal receiver and moves the media recovery point forward. It takes a checkpoint and allows old receivers to be deleted. If you ensure that a new journal receiver is attached to the journal prior to running the RCDMQMIMG, then you should be able to delete all previous receivers. To attach a new receiver, use the command: CHGJRN JRN(QMGRLIB/AMQAJRN) JRNRCV(*GEN)

Before committing to this strategy, be aware that RCDMQMIMG does not compress the data it copies to the journals. If you have large amounts of data in the queues, this will be an expensive operation and will itself result in an increase in the amount of space used by the journals.

Important: The journal receivers created by WebSphere MQ are owned by the QMQM profile, and so MQJRNMNT will need QMQM or *ALLOBJ authority for the DLTRCV option to work.

Back to top

Conclusion

Now, let's run the MQJRNMNT command in report-only mode a few times to verify that the command will delete the same set of journal receivers that you would delete after a manual check of the AMQ7460 and AMQ7462 messages.

Once you are satisfied that the command meets your needs, it can be incorporated into your journal housekeeping routine, replacing manual housekeeping. MQJRNMNT does not lock the journal and only uses a small amount of CPU, so it can be run without any need to quiesce the queue manager.

You can run MQJRNMNT at regular intervals as a scheduled job, or reuse the logic in jrnmaint.c in a Delete Journal Receiver exit program to indicate whether a receiver is eligible for deletion.

Back to top

Downloads

Name	Size	Download method
source.zip	.1 MB	FTP|HTTP
objectcode.zip	.4 MB	FTP|HTTP

Information about download methods

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Managing WebSphere MQ's journal receivers
• Conclusion
• Downloads
• About the author
• Comments

Next steps from IBM

• Try: WebSphere MQ
• Briefing: WebSphere flexible business processes
• Buy: WebSphere MQ

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers