Brief: The buzzword "cooperative processing" is often taken to mean processing between an AS/400 and a PC. However, it is possible to create a cooperative processing application involving two AS/400 programs. This article describes one technique that uses a data queue to pass information from one program to another. Unlike traditional data queue applications, the method described here can be used to refresh a display without keyboard input from the user.

I have taken several airline flights recently, and I spent a good deal of time studying flight-schedule monitors in airport terminals. While studying the schedules, I saw parts of the display being updated as I watched. Neat trick- having the display refresh itself. I wondered if such a process could be applied to AS/400 displays.

An AS/400 panel usually refreshes in response to operator input. For example, on the Work Output Queue (WRKOUTQ) display, you refresh the information by pressing F5. Is it possible to perform a refresh without pressing a function key? A number of techniques come to mind such as the WAITRCD and WAIT options ("100 Hot Tips for the AS/400," MC, October 1993, Tip number 1) and the end- of-file delay parameter with a database file. Both of these techniques can be used to create auto-refresh programs. The refresh occurs when either a period of time has elapsed or another record has been added to a file.

What if you have an interactive program where you want to "wait for" (be informed of) new data, while continuing to use the program? For example, if you are using an inquiry program, and at some point you launch a lengthy search or perform an extensive computation? Do you simply start the operation and put the terminal into input-inhibited mode? Or, do you start a batch application and wait until it is done? How do you get status information back to the interactive application while the other process is operating?

OS/400 has a technique you can use for this type of requirement. Using a data queue associated with a display file, you can receive input from either the display file or the data queue. The data queue controls flow in the interactive application-as you'll see in the example, entries from the data queue are used to determine where the input comes from. The data queue automatically receives an entry when input comes from the display file. If the input is from the display file, then you process it as you normally would, either by editing input fields or by processing function keys. If the input is from another program, the target program can act based on the information in the data queue. The data queue can contain a command, request or status information sent from a second program (on the same or another system). Because the data queue-rather than the display file-is the controlling element, you could have many programs that pass information or instructions to a single interactive application.

Once you understand the technique, you can probably come up with a wide variety of applications where it would be useful. For example, an inquiry for retail order entry can become outdated while a salesperson is discussing a purchase with a customer. If the customer is trying to decide between a red shirt and a blue shirt and you only have one of each in his size, it's important to know that someone else has just sold the red one. This scenario applies anytime unique items or very limited quantities of a particular item are available. Another example involves data entry for a loan application: you could initiate a batch job to calculate payment amounts while the user continues to enter information about the customer. When the batch calculation is complete, the interactive application is updated so that the loan officer can tell the customer the payment amount.

The Sample Flight Schedule

To see this technique in action, I've created a sample flight schedule that you can update with your own flight entries. This simulation will give you a feeling for how two programs can communicate using this data queue method. 1 illustrates the relationships between the programs and the data file for this example. Instructions for compiling the display files and programs are included in each source member. The only other object you'll need to create is the data queue:

To see this technique in action, I've created a sample flight schedule that you can update with your own flight entries. This simulation will give you a feeling for how two programs can communicate using this data queue method. Figure 1 illustrates the relationships between the programs and the data file for this example. Instructions for compiling the display files and programs are included in each source member. The only other object you'll need to create is the data queue:

 CRTDTAQ DTAQ(xxx/FLIGHTDQ) + MAXLEN(80) 

The length of the data queue must be specified as at least 80. This is a requirement of display data management for data queues associated with display files as we're doing in this example.

To run the programs, you will need access to two interactive sessions. Ideally, you would run the programs from two terminals located next to each other, so that you can see each display concurrently. Alternatively, you can use multiple sessions at the same display, (using PC Support, for example). 2 illustrates the two programs running concurrently. The two programs are an example of a simple cooperative processing application. In this case, program FLT001RG is an interactive display of flight data and gets its data to display from the update program FLT002RG. The update program also controls the display-pressing F3 from FLT002RG ends both programs.

To run the programs, you will need access to two interactive sessions. Ideally, you would run the programs from two terminals located next to each other, so that you can see each display concurrently. Alternatively, you can use multiple sessions at the same display, (using PC Support, for example). Figure 2 illustrates the two programs running concurrently. The two programs are an example of a simple cooperative processing application. In this case, program FLT001RG is an interactive display of flight data and gets its data to display from the update program FLT002RG. The update program also controls the display-pressing F3 from FLT002RG ends both programs.

Operating the Programs

You can start the programs in either order. Program FLT001RG displays the initial flight schedule. It then waits for input from the data queue associated with the display file. The only valid keyboard input is the ENTER key. Pressing ENTER prints the current flight schedule. This input is channeled through the data queue and back to the inquiry program. Updates, additions and the request- to-quit instruction are sent from FLT002RG to FLT001RG through the data queue. Input from the data queue is used to update or add to the flight schedule or end the program.

Program FLT002RG is a simple data entry display that is similar to a DFU program. You must specify the line number of the schedule to be changed or added (line 1 to 10), in addition to the data for that line. When you press ENTER, the data is sent to the data queue, along with a code that the inquiry program interprets as an update request instruction. You can also press F3 to quit the program. Quitting FLT002RG causes a quit instruction to be sent to FLT001RG as a data queue entry.

Description of the Display Files

Display file FLT001DF (see 3) contains two record formats. Formats FLTSFL and FLTCTL in FLT001DF are used to describe the subfile display that shows the flight schedule. This is an extremely simple subfile definition, and it is not used as a rolling subfile in the programs. The purpose of this definition is to define a group of similar records on the display.

Display file FLT001DF (see Figure 3) contains two record formats. Formats FLTSFL and FLTCTL in FLT001DF are used to describe the subfile display that shows the flight schedule. This is an extremely simple subfile definition, and it is not used as a rolling subfile in the programs. The purpose of this definition is to define a group of similar records on the display.

The INVITE keyword that is specified at the file level within FLT001DF controls the actual reading of the display formats in program FLT001RG (the schedule display program). This option is described in more detail later.

The last feature we need to look at for this display file is the usage of the DTAQ parameter on the CRTDSPF command for FLT001DF. When you specify this value, you indicate that programs using the display file can also work with data queue entries associated with the display file. Other programs can put entries into the data queue. By specifying the DTAQ value, entries can also be placed into the data queue when an input operation occurs from an invited device.

What is an invited device? Remember that the INVITE DDS keyword is being used in the display file. This keyword is conditioned with indicator *IN98. When you want to receive input from both the display file and the data queue in FLT001RG, set *IN98 on before displaying a record format. The device to which the record format is written is invited.

When the display is invited and a data queue is associated with the display file, an input operation from the display causes an entry to be placed onto the data queue. The entry is formatted as shown in the first data structure in FLT001RG (4). Fields ENTTYP, FILEID, FILENM, FILELB and PGMDEV are filled in. The contents and usage of those fields are described in more detail in Chapter 10 of the Guide to Programming application and Help Displays.

When the display is invited and a data queue is associated with the display file, an input operation from the display causes an entry to be placed onto the data queue. The entry is formatted as shown in the first data structure in FLT001RG (Figure 4). Fields ENTTYP, FILEID, FILENM, FILELB and PGMDEV are filled in. The contents and usage of those fields are described in more detail in Chapter 10 of the Guide to Programming application and Help Displays.

In the example program, you only need to work with the value in field ENTTYP. When an input operation occurs for the display file, the value *DSPF is placed into that field. With the device invited, the example program receives all input via the data queue. It checks the value of ENTTYP to determine whether the entry on the data queue originated with the display file operation or elsewhere. If it originated with the display file, the program explicitly reads the display file to obtain the input data.

The concepts used for this technique are very unusual and may take some getting used to. The point is that the program writes the record format to the display and then waits to see who is eligible to get its attention first: either an input from the display file, or an input from the data queue. Note that the record format is written. The usual write/read operation (EXFMT in RPG terms) is not used, because you do not want to restrict the program while you are waiting for the operator to press a function key or ENTER.

The display file FLT002DF (Fig-ure 5) for the update program, FLT002RG, requires no special explanation. Format FLTRCD is the data entry panel. It includes the CA03 keyword to enable the F3 key.

Inquiry Program FLT001RG

Program FLT001RG (4) is where the most activity occurs in this demonstration, although in the spirit of a true cooperative-processing application, it cannot be called the more important of the two programs. Each program (FLT001RG and FLT002RG) plays a part in this demo.

Program FLT001RG (Figure 4) is where the most activity occurs in this demonstration, although in the spirit of a true cooperative-processing application, it cannot be called the more important of the two programs. Each program (FLT001RG and FLT002RG) plays a part in this demo.

FLT001RG uses the display file and a printer file. The printer file is explicitly opened and closed, so that it is easier to see the results of the print request.

The program starts by loading the first four lines of the flight schedule from the compile time array values. It then enters a do loop. The first operation in the loop sets indicator *IN98 on, which enables the INVITE keyword in the display file. Next, the subfile control record FLTCTL is written, which displays the control record and the four lines of the flight schedule. Note that because the WRITE operation is used, control immediately returns to the program, rather than waiting for operator input (ENTER or a function key).

The next section of code calls the Receive Data Queue entry (QRCVDTAQ) program and passes the parameters for the program name, the data queue and library, the length of the data queue entry, the name of the field into which the entry is to be received and how long to wait for data. The receiver field, DTAQFD, is defined in a data structure, so subfields are readily available. The last parameter, WAIT, specifies a wait value of -1, which means that the program will wait until an entry is placed onto the data queue before it continues processing. A time-out condition has not been set for the wait, although you can set one if that would be more appropriate for your application.

The QRCVDTAQ CALL is really the heart of the technique I am describing. You have already configured the display file so that it will put an entry onto the data queue if an input operation occurs. Presumably, there is another program somewhere in the system that can put an entry onto the data queue as well (in our example FLT002RG). That other program can perform any function. For example, it could be a search program that is creating a list of found items, a batch process that is accumulating an account total, or even a program that is processing on another system. At any point, the program can place an entry on the data queue, either to communicate status information ("1000 records processed, 9000 left") or final results. Because the data queue entry from the other program is free format, it can contain any type of data that is required.

The QRCVDTAQ program is waiting for an entry on the data queue. When that entry arrives, the program receives it in the DTAQFD field. Now all FLT001RG needs to do is determine how to process the entry.

The program decides how to process the entry by examining the entry type. I do this with a simple SELEC group. There are only two cases: either the entry is from the display file or from the data queue itself.

If an input operation occurred on the display file, the Entry Type (ENTTYP) field has the *DSPF value. Remember that this value is placed into the data queue entry by display data management. Values from any input fields in the record format are not placed into the data queue entry because those values are still in the record format itself, which remains to be read by the program. By pressing ENTER or a function key, you have caused a data queue entry to be made which indicates that there is an input available from the display file. It is then your responsibility to accept and process the input. Up to this point, you have only written (with the WRITE opcode) to the display file.

Program FLT001RG calls the DSPFIN subroutine if there is a display file input operation. If input comes from the update program, subroutine DTAQIN is called. No matter which subroutine is called, after it completes, the loop continues and displays the record format again.

Subroutine DSPFIN is simple. The first operation reads the display file, which is necessary to have access to any input fields on the display and to determine which function key was pressed (ENTER or another enabled key). In this example, no input fields are used, but the subroutine is doing something "useful" by printing the current flight schedule, which may have been updated since the program started. The printout is only intended to be an illustration, so I've kept it as simple as possible. It gives you an opportunity to see how entries from the display file are processed with this technique.

Subroutine DTAQIN is not complicated either. Remember that this routine is called in response to input that does not come from the display file. Some other program placed an entry on the data queue. DTAQIN processes the entry as an update request to the flight schedule.

In order to update the schedule, you must access the subfile display and update or add a subfile record with new schedule information. Because you will be accessing the display file, you first must cancel the outstanding INVITE by setting off indicator *IN98 and then writing record format FLTCTL again. FLTCTL is the subfile control record format that was written at the beginning of the loop. Because the INVITE is now cancelled, a *DSPF data queue entry cannot be generated. Disabling the INVITE and then rewriting the record format frees up the device associated with the display file so that we can perform other input/output operations on its record formats.

If you do not cancel the outstanding INVITE, you will receive message CPF5023, "GET NOWAIT pending." This situation is analogous to inviting guests to a party, and greeting them at the door by saying, "Sorry, the party is canceled." As in life, the polite way to handle this situation is to cancel the invitation before the invitee arrives. Also as in life, if you neglect to cancel the invitation and the invitee arrives and finds your attention absorbed elsewhere, a fairly embarrassing scene ensues.

After you cancel the outstanding INVITE, you are free to perform other input/output operations on record formats in the display file. You need this capability so that you can update the subfile records. After some shuffling of fields and validity checking, you either write a new schedule record or update an existing record in the subfile.

The new schedule is displayed when the loop in the mainline section of the code gets control again after the DTAQIN subroutine ends. INVITE is enabled again, followed by the write of the subfile to the display. At that point, you can see the updated schedule and the process starts over.

Update Program FLT002RG

The program that drives the schedule updates is trivial. All this program has to do is process display format FLTRCD. If the ENTER key is pressed, the values entered for schedule information are sent to the data queue, along with the *UPDT request. If F3 is pressed, the *QUIT request is sent through the data queue. F3 also ends the update program.

There is nothing complicated taking place in program FLT002RG (see 6). However, this program could also contain any processing that would be appropriate for your requirements. To communicate to client program FLT001RG, the example uses the Send Data Queue Entry (QSNDDTAQ) program. Because this is a user-defined entry, you must define the format of the entry you are sending and both programs have to agree on the content of the entry. I've accomplished this by formatting the schedule data into data structure fields that are sent to the data queue as one long field.

There is nothing complicated taking place in program FLT002RG (see Figure 6). However, this program could also contain any processing that would be appropriate for your requirements. To communicate to client program FLT001RG, the example uses the Send Data Queue Entry (QSNDDTAQ) program. Because this is a user-defined entry, you must define the format of the entry you are sending and both programs have to agree on the content of the entry. I've accomplished this by formatting the schedule data into data structure fields that are sent to the data queue as one long field.

Other Options

In addition to processing data queue entries from display file operations and user-defined entries, OS/400 can also use this technique to indicate that an ICF (Intersystem Communications Function) file has information available. This is very useful if you have an interactive program that also communicates with a program on another system. For example, you may be doing an inventory lookup on both your local system and on one or more remote systems. Rather than tie up the display while all of the remotes are being queried, you can launch the request on the other systems through the ICF file and continue using the display on the local system.

When the remote systems send back their replies in the ICF file, entries are placed on the associated data queue. As in the example shown here, your program then receives and processes each entry based upon an entry type of *ICFF rather than *DSPF. You can have all three types of inputs (*ICFF, *DSPF and program described) being processed from the data queue within the same program.

Design Mystique

The technique demonstrated in this example is representative of event-driven programming. As you can see, you seem to give up control of the program to outside events. Your program then responds to the outside events as they happen. Although this might seem difficult to grasp at first, by apparently giving up control, you gain a great deal more freedom and flexibility. Rather than write programs that force the user to watch an input-inhibited display until the computer is done doing something, you can now start a process and return control to the user immediately. When the "something else" is done, it informs your program and it is your program's job to work with the returned information. Your program is simpler since it only has to check in one place to determine what input is currently available. It doesn't require code to continuously check for a new record in a file, or query a message queue to see if something new is there. Using these deceptively simple techniques provides a very powerful method to get much greater control of your programs.

Craig Pelkie can be reached through Midrange Computing.

References

Control Language Programmer's Guide (SC41-8077, CD-ROM QBKA7101) DDS Reference (SC41-9620, CD-ROM QBKA7401) Guide to Programming Application and Help Displays (SC41-0011, CD-ROM QBKA7901)

For information about the data queue technique, refer to the guide to displays. The INVITE keyword is described in both the guide to displays and the DDS reference. The data queue programs (QRCVDTAQ and QSNDDTAQ) are described in the CL programmer's guide.

Event-driven Programming with Data Queues

Figure 1 Routing Data to the Flight Schedule Inquiry

 UNABLE TO REPRODUCE GRAPHIC 
 
 Event-driven Programming with Data Queues
 
 Figure 2 Sample Flight Schedule Display/Update Programs
 
 UNABLE TO REPRODUCE GRAPHIC 
 
 Event-driven Programming with Data Queues
 
 Figure 3 Display File FLT001DF
 
 *============================================================ * To compile: * * CRTDSPF FILE(XXX/FLT001DF) SRCFILE(XXX/QDDSSRC) * DTAQ(XXX/FLIGHTDQ) * *============================================================ *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+.. A 98 INVITE A R FLTSFL SFL A LINENO 2Y 0O 4 2TEXT('LINE NO') A EDTCDE(Z) A ARLINE 3A O 4 8TEXT('AIRLINE CODE') A ORIGIN 10A O 4 15TEXT('ORIGIN CITY') A DEST 10A O 4 27TEXT('DESTINATION CITY') A TIME 4Y 0O 4 41TEXT('ARRIVAL TIME') A EDTWRD(' 0: ') A STATUS 10 O 4 49TEXT('FLIGHT STATUS') A R FLTCTL SFLCTL(FLTSFL) A SFLSIZ(0010) A SFLPAG(0010) A SFLDSP A SFLDSPCTL A 1 25'Airline Flight Display Simulator' A 3 3'#' A DSPATR(UL) A 3 6'Airline' A DSPATR(UL) A 3 15'Origin' A DSPATR(UL) A 3 27'Destination' A DSPATR(UL) A 3 40'Arrival' A DSPATR(UL) A 3 49'Status' A DSPATR(UL) *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+.. 
 
 Event-driven Programming with Data Queues
 
 Figure 4 RPG Program FLT001RG
 
 *============================================================ * To compile: * * CRTRPGPGM PGM(XXX/FLT001RG) SRCFILE(XXX/QRPGSRC) * *============================================================ *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+.. FFLT001DFCF E WORKSTN F N KSFILE FLTSFL FQSYSPRT O F 132 OF PRINTER UC * E ARA 1 4 39 *============================================================ I* DTAQFD - Passed by DTAQ *============================================================ I DS I 1 80 DTAQFD I 1 5 ENTTYP I B 11 120FILEID I 13 22 FILENM I 23 32 FILELB I 33 42 PGMDEV I 43 80 RESVD I 6 44 DQFLDS *============================================================ I* ARAFLD - Initial Array Fields *============================================================ I DS I 1 39 ARAFLD I 1 20LINENO I 3 5 ARLINE I 6 15 ORIGIN I 16 25 DEST I 26 290TIME I 30 39 STATUS * * Initialize display C 1 DO 4 N 50 C MOVELARA,N ARAFLD C WRITEFLTSFL C END * * Write display, process DSPF/DTAQ inputs C ENTTYP DOUEQ'*QUIT' C SETON 98 *enable invite C WRITEFLTCTL *write invited * C CALL 'QRCVDTAQ' C PARM 'FLIGHTDQ'QNAME 10 *dtaq name C PARM '*LIBL' LIB 10 *dtaq lib C PARM 80 FLDLEN 50 *dtaq length C PARM DTAQFD 80 *dtaq field C PARM -1 WAIT 50 *wait unlimited * C SELEC C ENTTYP WHEQ '*DSPF' C EXSR DSPFIN C ENTTYP WHEQ '*UPDT' C EXSR DTAQIN C ENDSL * C ENDDO * C MOVE *ON *INLR *============================================================ * Process input from display file (print schedule) *============================================================ C DSPFIN BEGSR * C READ FLTCTL 99 * C OPEN QSYSPRT * C 1 DO 10 N C N CHAINFLTSFL 99 *99 - NRF C *IN99 IFEQ *OFF C EXCPTEXPRNT C ENDIF C ENDDO * C CLOSEQSYSPRT * C ENDSR *============================================================ * Process input from data queue *============================================================ C DTAQIN BEGSR * * Update/add to schedule request C SETOF 98 *disable invite C WRITEFLTCTL *cancel invite * C MOVELDQFLDS ARAFLD C LINENO IFGT 0 C LINENO ANDLE10 C LINENO CHAINFLTSFL 99 *99 - NRF C MOVELDQFLDS ARAFLD * C *IN99 IFEQ *ON *not found C Z-ADDLINENO N C WRITEFLTSFL C ELSE *found C UPDATFLTSFL C END C END * C ENDSR *============================================================ OQSYSPRT E 1 EXPRNT O ARAFLD *============================================================ *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+.. ** ARA - Initial flight schedule 01NECCHICAGO SAN FRAN 0515ON-TIME 02ZYYNYC PARIS 0739DELAYED 03AABLAX DALLAS 1005ON-TIME 04MNMSEATTLE ORLANDO 0827ARRIVED 
 
 Event-driven Programming with Data Queues
 
 Figure 5 Display File FLT002DF
 
 *============================================================ * To compile: * * CRTDSPF FILE(XXX/FLT002DF) SRCFILE(XXX/QDDSSRC) * *============================================================ *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+.. A R FLTRCD CA03(03) A 2 2'Line #' A LINENO 2Y 0I 2 15TEXT('Line number') A 3 2'Airline' A ARLINE 3A I 3 15TEXT('AIRLINE CODE') A 4 2'Origin' A ORIGIN 10A I 4 15TEXT('ORIGIN CITY') A 5 2'Destination' A DEST 10A I 5 15TEXT('DESTINATION CITY') A 6 2'Arrival' A TIME 4Y 0I 6 15TEXT('ARRIVAL TIME') A 7 2'Status' A STATUS 10A I 7 15TEXT('FLIGHT STATUS') A 23 2'F3=Exit' *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+.. 
 
 Event-driven Programming with Data Queues
 
 Figure 6 RPG Program FLT002RG
 
 *============================================================ * To compile: * * CRTRPGPGM PGM(XXX/FLT002RG) SRCFILE(XXX/QRPGSRC) * *============================================================ *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+.. FFLT002DFCF E WORKSTN *============================================================ I* DTAQFD - passed by dtaq *============================================================ I DS I 1 80 DTAQFD I 1 5 DQRQST I 6 70LINENO I 8 10 ARLINE I 11 20 ORIGIN I 21 30 DEST I 31 340TIME I 35 44 STATUS *============================================================ C *IN03 DOUEQ*ON *until F3 C CLEARDTAQFD C EXFMTFLTRCD * C *IN03 IFEQ *ON *F3 C MOVEL'*QUIT' DQRQST C ELSE C MOVEL'*UPDT' DQRQST C ENDIF * C CALL 'QSNDDTAQ' C PARM 'FLIGHTDQ'QNAME 10 *dtaq name C PARM '*LIBL' LIB 10 *dtaq lib C PARM 80 FLDLEN 50 *dtaq length C PARM DTAQFD *dtaq field C ENDDO * C MOVE *ON *INLR *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+..