Midrange Programmer

With the iSeries possibly being one of many disparate platforms in your IT organization, it has become more vital to share data among these platforms. One way to accomplish the sharing of data is to use data queues. But one complaint about data queues is that they don't guarantee delivery. If something happens during the transmission of data, or a queue gets cleared or deleted, you're hosed. That is until V5R1 came along and IBM extended the journal function to include data queues.

Many of you have been journalizing your physical files and access paths for years. You may do so for backup and recovery, data propagation, or simply because it's cool technology. Well, now you can add data queues, along with data areas and Integrated File System files, to the list of journal-capable objects. Journalizing data queue entries allows you to fortify your data-queue-centric data propagation applications by guaranteeing delivery. If you start the journal function for data queues and something goes bad during the running of your data queue application, you can go back to the journal and resend those entries. Let's check out the steps to set it up.

The first thing you need to do is to create the journal and journal receiver that will hold you data queue journal entries. Figure 1 shows the Create Journal Receiver (CRTJRNRCV) command. The receiver must be created before a journal can be attached to it.

For now, just take the default options and only provide journal receiver and library names. Press Enter and you now have a receiver called MYJRNRCV.

Now you need a journal to attach to that receiver. Figure 2 shows the Create Journal (CRTJRN) command you will use to accomplish this task.

Again, you can take the defaults on this command (unless you are a seasoned veteran)--except for the name and the library of the journal--and the journal receiver and library you want to attach to. The journal receiver is the one you created in the previous step.

Now you have created a journal called MYJRN and attached the journal receiver, MYJRNRCV, to it. Now let's start the journal function for a data queue. Figure 3 shows how to start the journal function.

The Start Journal Object (STRJRNOBJ) command was new with V5R1. It allows you to start the journal function for data queues, data areas, and IFS objects. In my example, I am going to journal the data queue MYDATAQ in library MYLIBRARY. The only other parameters I need to add are the object type, *DTAQ, and the journal that will contain the journal entries, MYJRN. The last parameter allows you to determine whether to capture "after" images or both "before" and "after" images. For data queues, you can only capture "after" images, so leave this parameter as it is. Press Enter and you are now journalizing your data queue entries to the journal receiver MYJRNRCV, in journal MYJRN.

Now it's time to write some entries to a data queue. If you don't have a data queue application to test or are new to data queues, check out "Data Queue Basics."

Once you've entered some data in your data queue, you can display your journal by using the Display Journal (DSPJRN) command, illustrated in Figure 4, and see what was done to your data queue.

The DSPJRN command is very powerful and flexible, but, for the purpose of this article, after you type the journal name, MYJRN, and the library where MYJRN exists, you are going to take all the defaults to this command and display all the contents of this journal. Press Enter after you enter the journal name and library, and you'll be presented with a screen like the one in Figure 5. Note that your data may vary, depending on the entries you wrote to your data queue, but whatever the case, you should see a list of those entries.

From this list you can select option 5 next to one or more of the entries to see more detailed information about each entry. This screen shows the complete journal entry, as well as header information about the journal entry, such as the type, code, and sequence. The journal doesn't just contain entries that were written to the data queue; it also contains information about actions that were taken against the queue. For example, Figure 6 shows the results of taking option 5 next to a journal entry that was written when the data queue was cleared using the QCLRDTAQ API.

Notice that the code Q shows that the entry was a data queue operation and that the type QJ signifies that a keyed data queue was cleared. You may also notice that the entry shows nothing more than GE. That is how the API clears the data queue. What this states is that the queue was cleared by removing all entries with a key greater than or equal to (GE) blanks, which qualifies all entries.

Now you have the ability to journalize your data queue entries. In the next issue, I'll show you how to recover those entries, should something happen to your data queue or data transmission. For now, play around with the commands I've shown you and get to know them better. They could come in handy as you work toward bullet-proofing your applications.