It's been nearly 20 years since Wayne O. Evans, a security expert and consultant who was working at IBM Rochester, came up with the idea of data queues. With the exception of messages and probably OPNQRYF, data queues are probably the most-used programmer resource on OS/400.

Data queues provide a "queue" onto which the programmer may stack data and then retrieve that data later. Since data queues are persistent objects, they may have data added to them in one job and that data may be retrieved in a secondary job. Often, in fact, multiple jobs will add data to a specific data queue, and a single batch job will retrieve the data off that data queue asynchronously. That batch job can wait for a specified period or forever for an entry to be added to the data queue.

The following commands are among the few CL commands that IBM ships with OS/400 for data queues:

• CRTDTAQ--Create Data Queue
• DLTDTAQ--Delete Data Queue
• WRKDTAQ--Work with Data Queues

Displaying the Description of a *DTAQ

To take advantage of data queues, you have to use APIs. Ironically, while most RPG programmers wrongly treat APIs like a Latin course in college, you really can't use data queues without APIs. Consequently, most people are using APIs, at least when it comes to data queues.

IBM provides APIs to send and received data to and from a data queue, as well as to retrieve information about the data queue. The APIs that IBM provides to manipulate data queues are as follows:

• QSNDDTAQ--Send Data Queue Data
• QRCVDTAQ--Receive Data Queue Data
• QCLRDTAQ--Clear Data Queue
• QMHRDQM--Retrieve Data Queue Entry
• QMHQRDQD--Retrieve Data Queue Description

The Send and Receive APIs are, of course, widely used throughout the RPG application world, so I won't bother explaining them.

The QCLRDTAQ API clears either all the entries on the specified data queue or a subset of entries identified by a "key" parameter. You specify a key to delete, and the API deletes the entries in the data queue that match that key. Normally, entries in a data queue are removed when they are retrieved with the QRCVDTAQ API, so the use of QCLRDTAQ is not widespread.

The QMHRDQM API retrieves one or more entries from a data queue. This is similar to what is done with the conventional QRCVDTAQ API, but that is where the similarity ends. The QMHRDQM API does not delete the data entries it retrieves.

The QMHRDQM and QCLRDTAQ APIs along with QRCVDTAQ and QSNDDTAQ APIs are interfaces that are used to manipulate the data on the data queue itself, whereas the QMHQRDQD API returns information about the data queue itself.

The QMHQRDQD API returns the description of the data queue along with information about the size and number of entries on the data queue. While this API is useful for testing for entries on a data queue before attempting to retrieve an entry, that capability is already integrated into the QRCVDTAQ API.

So what use is the QMHQRDQD API? It can be used to create a Display Data Queue Description (DSPDTAQD) command.

The DSPDTAQD command accepts a data queue name and displays the appropriate information about that data queue. Figure 1 contains the command definition source code for the DSPDTAQD command.

Figure 1: DSPDTAQD (Display Data Queue Description) Command Source

To compile this command, use the CRTCMD command as follows:

The command requires a command processing program (see Figure 3), which also requires a display file to display the data queue's information. The DDS source for this display file is listed in Figure 2.

Figure 2: DSPDTAQDF Source

The final piece of this puzzle is the command processing program for the DSPDTAQD command. The RPG IV program DSPDTAQD receives the name of the data queue and uses the QMHQRDQD API to retrieve the description of that data queue. The source for the DSPDDTAQD RPG IV program is listed in Figure 3.

Figure 3: RPG IV Source for DSPDTAQD Program

Once this command is compiled, you can use it to display the description of any data queue for which you have authority.

Figure 4 illustrates an example of the information that is displayed by the DSPDTAQD command.

Figure 4: The Display from the DSPDTAQD Command (Click image to enlarge.)

Bob Cozzi has been programming in RPG since 1978. Since then, he has written many articles and several books, including The Modern RPG Language--the most widely used RPG reference manual in the world. Bob is also a very popular speaker at industry events such as RPG World and is the author of his own Web site and of the RPG ToolKit, an add-on library for RPG IV programmers.