 |
|
|
|
       |
 |
|
|
Keyed Data Queues: The Key to Flexible Subfiles by Kevin Vandever [The code for this article is available for download.]
Why don't we talk about one of my favorite uses for data queues? Subfiles. What makes this technique so cool, in my opinion, is that data queues were probably never intended to be used in this manner. But don't worry! No data queues were hurt while using my technique. In fact, it is the data queue that makes my subfile programs more flexible than ever before. Why Use a Data Queue in a Subfile Program? This technique came to me when I was asked to create a subfile application that works like the Programming Development Manager. If you've ever looked at PDM on the AS/400, you may have marveled at what a cool subfile application it is. The problem is, PDM is not a subfile application; its displays are written using the User Interface Manager (UIM), the language used for many native OS/400 commands and all of the help panels on the AS/400. However, PDM is extremely flexible. It allows you to position to any place in a list, page forward or backward from that position, change a record on any page of the subfile, and process all changed records only when the Enter key is pressed. On its own, each feature is simple to code in an RPG subfile program. However, when you combine the features, the real fun begins. PDM-Like Subfiles To handle position-to logic, paging forward and backward even after repositioning the subfile using the position-to field, and saving subfile changes on any page until the Enter key is pressed, I use the page at a time subfile technique (SFLPAG = SFLSIZ in your DDS) and use the data queue to store a replica of the changed subfile record. Each time a subfile record is changed and the Enter key or Page key is pressed, the changed subfile record is stored in the data queue. I do this because I build the subfile one page at a time and need to know what records were previously changed because once records are no longer displayed on the screen, they are not part of the subfile. When the user positions through the subfile by scrolling or by keying something in the position-to field, the program will check to see if each record read from the data file exists in the data queue before loading it to the subfile. If the record exists in the data queue, it is written to the subfile along with the earlier changes and is marked as changed. When the user is ready to process all the changed records by pressing the Enter key with nothing in the position-to field, they will be processed appropriately from the data queue. The reason behind using data queues in a subfile program stems from a combination of user requirements and an interest in selecting the most efficient solution for that combination. Using data queues instead of data structures, files, or arrays, frees your job from performing some work. During an interactive job, the data queue APIs can provide better response time and can decrease the size the program as well as its process activation group (PAG). In turn, this can help overall system performance. In addition, data queues allow the programmer to do less work. When you receive an entry from a data queue using the QRCVDTAQ command, it is physically removed from the data queue. The programmer does not have to add code to deal with unnecessary entries. Here's what you do. The DDS Before I get to the RPG, I need to say a few things about the DDS, SFLDTAQDF. For this application to have the necessary flexibility, the RPG program--not OS/400--must completely control the subfile. You know what that means, right? For this to happen, the subfile page (SFLPAG) and subfile size (SFLSIZ) values must be equal. The subfile will never contain more than one page, but, as you will see, the program will make it appear that the subfile contains much more than one page of data. The CL Check out the CL, SFLDTAQCL. It is important to note that even though entries are removed from a data queue after they are received, the space containing the entry is not. So, over the long run, performance will suffer because the data queue's size will increase. For this reason, I delete and recreate the data queue each time the program is called. Even if you build your data queues in QTEMP, as I do, it is best to delete and recreate them in case the user calls the program more than once before signing off. The RPG Now that the setup issues have been covered, let's perform some magic. Look at the RPG program, SFLDTAQRG. I'm not going to discuss every detail of the program but will concentrate on how the program uses a data queue to make the subfile appear to be larger than it really is. The program's first task is to load the subfile with one page of records. Notice in the SFLBLD routine that each time a record is read from the data file, the RCVQUE subroutine is executed. For the initial subfile load, this subroutine will not accomplish anything, so I will defer explanation until later. However, after the initial load, the RCVQUE subroutine plays a vital part in the subfile load routine. Once the subfile is initially loaded and displayed, the user can do several things. He can scroll through the subfile; add, change, display, or delete records; position to another place in the subfile; or exit the program. No matter what the user decides, each time the Enter key is pressed, the ADDQUE subroutine is executed. This subroutine uses the READC op code to find changed records in the subfile and to add them to the data queue using the QSNDDTAQ API. The data queue entry will contain the option selected by the user and the key of the data file used to initially load the subfile. When the user presses PgDn (page down), an entry is added to the data queue that consisted of the option and the value in DBIDNM, which is the key to the data file, the key to the data queue, and a hidden field in the subfile. Now back to the RCVQUE routine. This subroutine attempts to receive an entry from the keyed data queue using the same key that the record read from the database file (DBIDNM). The QRCVDTAQ API does this for you. The order is set to EQ (equal) so that you will retrieve an entry only if there is one matching the record just read from the file. If the length is greater than 0 (len > 0), that means an entry was retrieved from the data queue. You then set on indicator 74, which conditions SFLNXTCHG in your DDS, to mark the record as changed when the subfile record is written. This way, subsequent READC operations will pick up the record the next time this page is processed. If a matching entry exists in the data queue, then the entry in the data queue, not the data from the database file, is written to the subfile. With this, the user can page and position through the subfile and store any changed records in the data queue. Whenever a record is read from the file, the data queue is checked to see if that record exists and, if so, it is displayed along with the option that was previously selected. So if our user, after having selected two records for delete on the second page, wanted to page up to see the first page, he could do so. He would see a 4 in the original record he selected for delete, and now the data queue would contain the two records from the second page. If the user presses the Enter key and the position-to field is empty, the ADDQUE routine executes one last time to load any changes to the current page, and the PRCSFL routine is executed. This subroutine uses the RCVDTAQ API instead of READC to process all the changed records. Remember, changed records will reside in the data queue, not the subfile, which never contains more than one page of data. By setting the key value, DBIDNM, to blank and the order to GE (greater than or equal), you are sure to retrieve all entries in the data queue. This API will be run until the length (len) parameter is 0. That will happen when no more entries exist in the data queue. Setting Up and Running the Application I have also included the DDS for physical and logical files, SFLDTAQPF and SFLDTAQLF, respectively. Download the source code, compile the necessary components, add some data to your physical file, and call the CL program using the following command: CALL SFLDTAQCL The data queue is automatically created for you in QTEMP. All you have to do is use the application. Wow Your Friends and Impress Your Users Controlling the subfile within the RPG program and using data queues to store and retrieve changed subfile records allows you to create an extremely flexible subfile application that will furnish your users with everything they ever wanted in a subfile program. OK, almost everything. And if that's not enough, look at it as magic to make a page-at-time subfile look like a lot like a load-all subfile.
|
Editors Contact the Editors |
Last Updated: 5/22/02 Copyright © 1996-2008 Guild Companies, Inc. All Rights Reserved. |
PROFOUND LOGIC SOFTWARE