Using Data Queues in VARPG

by Raymond Everhart

[The code for this article is available for download.]

Somewhere in your company, there is someone downloading data into a spreadsheet, manipulating this data, and then presenting it to management, who will use it to make some decision. What if this person makes a mistake? What if he leaves the company and you have train someone else to do his job? What if a PC that contains several years' worth of spreadsheets suddenly crashes? The answer is usually the same: Call the IT department.

My last article, "The Opportunity of a Lifetime," explored using an ODBC/JDBC part to retrieve data from a Microsoft Access database. But now that you can retrieve information from other database systems, how do you get that data back to the iSeries? You could write the retrieved data to a PC file, then use some file transfer method to move that data to the iSeries. But after moving entire files back and forth between platforms for years, the job of keeping these files synchronized and up to date becomes unmanageable. A file transfer works great when moving files around, but what you really need is a way to have record-level access to all files on all systems.

A Quick Data Queue Review

A data queue is the fastest way to move data between programs. And the programs sharing the data do not even need to be on the same platform. Data queues are supported on most platforms, via callable APIs or custom controls. There are even third-party data queue interfaces available. Data queues can be accessed from many languages. A Java program can write data to a data queue, and an RPG program can read data from a data queue. Another benefit of data queues is that more than one program can be processing a data queue at the same time.

An example would be a program on the iSeries that reads through an open receivables file and looks for any customer with an invoice over 60 days old. When a late invoice is found, the customer number and a record code are placed on a data queue. Another iSeries program scans the open order file and looks for any order with back-ordered items. When such an order is found, the order number and a record code are placed on the same data queue. Another iSeries program scans the sales history file and looks for any sales rep whose sales have dropped for several consecutive months. When a match is found, the sales rep's number and a record code are placed on the data queue. Another program monitors Web site requests for quotations and places the data and a records code on the data queue. Then a VisualAge for RPG program reads the data queue, retrieves the information, and displays a screen that can used by a customer service person to handle the situation. This solution allows for multiple events or situations to be monitored and for multiple customer service people to handle the workload. You can even monitor such things as the number of entries in the data queue, the average time for resolution, or employee productivity. VARPG supports data queues, via calls to APIs, on the iSeries. These are the same APIs you would use if you were coding an RPG IV application on the iSeries.

There are five data queue APIs that you can use to exploit the power of data queues in VARPG.

• QSNDDTAQ sends data.
• QRCVDTAQ receives data.
• QCLRDTAQ clears data queues.
• QMHRDQM retrieves a data queue's messages.
• QMHQRDQD retrieves a data queue's description.

In the examples to follow, we will use the Send and Receive APIs. More information about data queue APIs is available in the IBM Information Center manual for object APIs (download PDF file), or check out the "Data Queue Basics" article, by Kevin Vandever.

A Disclaimer

One thing to keep in mind is that the contents of a data queue are not saved by any save command. Don't place anything in a data queue that isn't recoverable in the event of a system or object failure, unless you journal the data queue (new to OS/400 V5R1) or plan some other recovery method.

Creating a Data Queue

There is no API to create a data queue. Instead, you use the CrtDtaQ command:

CRTDTAQ DTAQ(YourLibrary/DEMO) MAXLEN(255)

For our example, we will name the data queue DEMO and give it a maximum length of 255 positions. For more information about the options that can be specified when a data queue is created, see the Information Center document CL Programming (download PDF file) or the "Data Queue Basics" article.

Placing Data in a Data Queue

Next we will code a simple VARPG program to place the contents of a data entry field in a data queue.

Step 1

Create a new GUI project in VARPG by clicking the New GUI project icon.

Step 2

Right-click Window with Canvas and select Properties. Change the part name to MAIN. Change the title to Add Entry to Data Queue. Click OK.

Step 3

Drag a static text part onto your canvas. Double-click the static text part that you added to the canvas and change the text to Data Queue Name. Click OK.

Step 4

Drag an entry field onto your canvas. Double-click the entry field part that you added to the canvas and change the Part Name to DQName. Click the Data tab of the Properties window, and change the length of DQName to 10. Click the Style tab of the Properties window and check the Caps Lock box. (The name of the data queue object on the iSeries will always be in upper case letters.) Click OK.

Step 5

Drag a static text part onto your canvas. Double-click the static text part that you added to the canvas and change the text to Data Queue Library. Click OK.

Step 6

Drag an entry field onto your canvas. Double-click the entry field part that you added to the canvas and change the part name to DQLibrary. Click the Data tab of the Properties window, and change the length of DQLibrary to 10. Click the Style tab of the Properties window and check the Caps Lock box. (The library name on the iSeries will always be in upper case letters.) Click OK.

Step 7

Drag a static text part onto your canvas. Double-click the static text part that you added to the canvas and change the text to Data Queue Length. Click OK.

Step 8

Drag an entry field onto your canvas. Double-click the entry field part that you added to the canvas and change the part name to DQLength. Click the Data tab of the Properties window, and change the length of DQLength to 5. Change the type to numeric. Click OK.

Step 9

Drag a multiline edit part onto your canvas. Double-click the entry field part that you added to the canvas and change the part name to DQData. Click OK.

Step 10

Drag a push button onto your canvas. Double-click the entry field part that you added to the canvas and change the part name to PSB_Send. Change the label to send. Click OK.

Step 11

Arrange the parts created in steps 3 through 10 to look something like the Add Entry to Data Queue panel (see Figure 1).

Figure 1: At this point, the Add to Data Queue application should look like this

Step 12

Right-click the Send push button and select Event and then Press from the pop-up menus. Copy the ADD2DQ source code into the program. (Don't forget to copy in the D-specs.)

Step 14

Create your application. Define your AS/400 information. (This step tells your application what system to connect to.) Save the project (see Figure 2). Build the project.

Figure 2: Save the add data queue entry project

Once this project is executed, a window is displayed that prompts you for the name of a data queue, the library in which the data queue resides, and the length of the data to send to the data queue. The text that you type in the multiline edit field will be placed in the data queue. Keep in mind that the data queue and library names must exist on the iSeries; otherwise an error will occur.

Retrieving Data from a Data Queue

Now we will code a simple VARPG program to retrieve the contents of a data queue entry and place it on a display. Most of the screen design and logic will look the same as the Send to Data Queue program that we just created.

Step 1

Click the New GUI project icon in VARPG.

Step 2

Right-click Window with Canvas and select Properties. Change the part name to MAIN. Change the title to Retrieve Data Queue Entry. Click OK.

Step 3

Drag a static text part onto your canvas. Double-click the static text part that you added to the canvas and change the text to Data Queue Name. Click OK.

Step 4

Drag an entry field onto your canvas. Double-click the entry field part that you added to the canvas and change the part name to DQName. Click the Data tab of the Properties window and change the length of DQName to 10. Click the Style tab of the Properties window and check the Caps Lock box. (The name of data queue object on the iSeries will always be in upper case letters.) Click OK.

Step 5

Drag a static text part onto your canvas. Double-click the static text part that you added to the canvas and change the text to Data Queue Library. Click OK.

Step 6

Drag an entry field onto your canvas. Double-click the entry field part that you added to the canvas and change the Part Name to DQLibrary. Click the Data tab of the Properties window, and change the length of DQLibrary to 10. Click the Style tab of the Properties window and check the Caps Lock box. (The library name on the iSeries will always be in upper case letters.) Click OK.

Step 7

Drag a multiline edit part onto your canvas. Double-click the entry field part that you added to the canvas and change the Part Name to DQData. Click OK.

Step 8

Drag a push button onto your canvas. Double-click the entry field part that you added to the canvas and change the part name to PSB_Retrieve. Change the label to Retrieve. Click OK.

Step 9

Arrange the parts created in steps 3 and 8 to look something like the panel shown in Figure 3.

Figure 3: This is how the Receive Data Queue Entry application should look so far

Step 10

Right-click the retrieve push button and select Event and then Press from the pop-up menu. Copy the RCVDQ source code into the program. (Don't forget to copy in the D-specs.)

Step 11

Create your application. Define your AS/400 information. (This step tells your application what system to connect to.) Save the project (see Figure 4). Build the project.

Figure 4: Save the receive data queue entry project

Explore the Power of Data Queues

Now that you have a send and a receive program, you can try them on different machines. The real power of data queues comes when you enable different processes to interface with one another without needing a constant, dedicated connection, or when a single application is used to service requests from multiple clients. Look for a future article that will explain how to combine the ODBC/JDBC part and data queues to create a VARPG application that receives requests from an RPG IV program on the iSeries, looks up data from a PC database, then passes the results back to the requesting program.

Raymond Everhart is an independent programmer and consultant in the Dallas/Fort Worth area and has 17 years of experience with IBM midrange servers. He can be reached at reverhart@raecodesign.com.

Sponsored By ASNA

How the City of Pinellas Park, FL is saving $2.25 million using ASNA Visual RPG: The City Pinellas Park's police officers have used laptop computers in their cruisers to enter case report information since 1991. Originally, the reports were entered on the laptops in their vehicles and later when officers went back to the station, the reports were then uploaded into the Records Management System on an AS/400. However, this was very time-consuming because uploading data from laptops to the AS/400 was extremely slow and officers were spending too much time in the station uploading these reports. As a solution, the Pinellas Park Police Department used ASNA Visual RPG (AVR) to take advantage of their team's RPG skills and to develop user-friendly Windows applications that were deployed in the police cruisers along with a wireless network. The ease of using these new AVR-developed applications saves officers time because they can upload data, via the wireless network, from their cruisers directly to the AS/400 with the speed of record-level access. Because the officers can do this directly from their vehicles instead of at the police station, they can now spend more time on the street and less time at the station uploading reports. Pinellas Park spent roughly $15,000 on the cost of development time and by using this new AVR-developed application, they have projected an annual savings of $225,000 by having the ability to keep their officers on the street. This means the police department will conceivably save $2.25 million over the 10-year period that the application is in use. "The use of AVR has increased our efficiency and functionality, we are now saving the equivalent of salaries for five full-time police officers per year." -- Jim Shanks Download your FREE copy of AVR today! http://www.asna.com/downloads.asp