A DDM data queue points to the *STD data queue on the other machine. After the type parameter comes the maximum entry length. It is here that you define the maximum length of your data queue message. The maximum length you can use is 64512 bytes, or 64K. The next parameter I want to talk about is the sequence parameter. You have three choices: *FIFO, *LIFO, or *KEYED. If you select *KEYED, you are then prompted for the key length. Just as with a database file, the key length is the length of the data you are going to use as the key to the data queue. Next, you determine whether or not you want to include the sender ID, which is the job name and user's profile, with each message written to the queue. The next parameter is broken up into two parts and is used to determine the maximum size of the data queue and the initial number of entries. The maximum size can go to 2 gig. The initial number of entries tells OS/400 how much space to reserve when the queue is created. You can extend the queue up to the maximum size, but, depending on your application, you may want to reserve a specific amount of space to start off. The default is 16. A new parameter and feature of data queues introduced in V5R1 is the automatic reclaim feature. This allows OS/400 to reclaim unused space in a data queue when that queue is empty. The need for this feature comes from the fact that the data queue size extends as you add messages beyond what you set in the initial number of entries parameter. Answering *YES to this parameter causes OS/400 to automatically reclaim the storage whenever the data queue is empty. The size of the data queue will then go back to the initial size at creation, which is determined by the maximum message size and number of initial entries parameters. One note of caution if you use this feature is that the data queue is locked while this reclaim takes place.

Client/Server Application

To better illustrate the APIs, I thought I would show them to you in action. DQClient and DQServer are RPG programs that employ data queue APIs. DQClient writes messages to a data queue using the QSNDDTAQ API. In our make-believe client/server world, it is one of many clients that will write to the same data queue, all with different messages. DQServer will use the QRCVDTAQ API to receive messages from all the clients and process them accordingly. The rest of the RPG is pretty straightforward stuff, so I'm just going to concentrate on the API code.

Take a look at DQClient. It calls the QSNDDTAQ API, which accepts four parameters. If I would have used *KEYED data queues, I would have added two more parameters to determine the key and key length, but in this example I am writing to a *FIFO data queue so that the server can receive entries in the order in which they are written. Below is the code, with an explanation in parentheses, that writes to the data queue.

 C   call 'QSNDDTAQ'
C  parm      queue (Name of data queue)
C  parm      lib   (Library Containing data queue)
C  parm      len   (Length of data being written to data queue)
C  parm      data  (Actual data being written to data queue)

This particular client will write a message type in the first two bytes, followed by the actual data that is required. In this case the two-byte type is OH, for order header, and the rest of the data is the actual order number. As you'll see shortly, the server will read that message and, based on the message type, process that message accordingly. Let's take a look at the server.

DQServer is a never-ending job, in that it will wait on the data queue, process the entry when one is written from one of the clients, and wait for the next entry. The job will only end normally when a client sends a special shut-down request. To run this program, you would submit it using the SBMJOB command. You could call it from a command line, but since it is a never-ending job, it will lock up your interactive session. This program uses the QRCVDTAQ API with a wait parameter of –1. Remember earlier in the article I mentioned that a negative number in the wait parameter meant that the program would wait indefinitely on the queue? Below is the code, with an explanation in parentheses, to receive from the queue.

C  call 'QRCVDTAQ'
C  parm   queue (Name of data queue)
C  parm   lib (Library containing data queue)
C  parm   len (Length of data received from data queue)
C  parm   data (Actual data received from data queue)
C  parm   wait (Time to wait before continuing processing)

As you will see in my other article, there are other parameters you can use with this API, but since this is a *FIFO queue containing no sender ID, these five parameters are all you need. Once the message is received, the program interrogates the first two bytes to determine the message type and processes the appropriate logic. In this case, my client sent an OH, so a program is called to create and order header record.

Sniff This!

I have provided you some very basic data queue concepts upon which to build. However, even though this is basic stuff, it has a practical, real-world application. Most data queue processing I do includes *FIFO data queues. Check out my other article in this issue to see how to use *KEYED data queues in a subfile application. Also, mess around with the other commands and APIs I mentioned in this article. Soon, you too will see why data queues are the Elmer's glue of iSeries programming.

Sponsored By ALDON COMPUTER GROUP

Free Whitepaper on Application Modernization Through Multi-Platform Development. Aldon Computer Group, the industry leader in multi-platform change management, offers a cutting-edge solution for companies seeking e-business success. Aldon Affiniti is the only application development tool that allows you to manage all your code, whether RPG, JAVA, COBOL, C++, or anything else from ONE single screen. Find out more today at www.aldon.com. (And while you're at it, don't forget to sign up for a FREE online seminar on multi-platform development.)