Getting your feet wet in cooperative processing may be easier than you think.

Brief: If you're at V2R2 and use the extended DOS or OS/2 versions of PC Support, you can easily get your AS/400 and PC programs to communicate using IBM's new PC Support data queue function.

It seems that all you hear lately is talk about the benefits of cooperative processing. After all, what a great concept-use the machine most suited to a task. But how does the average AS/400 programmer who doesn't know that much about communications programming write cooperative processing systems? Have you ever looked at the Communications or PC Support APIs? ...Not exactly something for novice programmers. Well, I have good news. With the new PC Support data queue function, cooperative processing just got a whole lot easier.

By no means am I suggesting that the PC Support data queue function will meet all of your cooperative processing needs. There are all kinds of AS/400 communication programming methods available which may provide better, more efficient solutions. You'll also find many non-IBM cooperative processing software products. New ones seem to be appearing every day. But data queues can be very useful in this environment and they make it much easier for you to get started with cooperative processing.

In this article, I first describe the PC Support data queue function. Then I present two simple cooperative processing applications to illustrate the uses of the function. Specifically, the applications illustrate how the function can permit a PC to retrieve data from an AS/400 and how one PC can execute commands on another PC. Only simple DOS PC batch programs are used for the PC portion of the examples, which means all you need is a PC editor-no compiler is required. For OS/2 PCs, these batch programs can be easily adapted to OS/2 command files, although I won't discuss how to do that here.

Read on and find out how you can begin orchestrating your AS/400(s) and PC(s).

What Are Data Queues?

A data queue is an AS/400 object (type *DTAQ) used to communicate data to and from programs within a job or between jobs. It is like a job queue (JOBQ) that contains jobs to be processed, or an output queue (OUTQ) that contains spooled files to be printed, or a message queue (MSGQ) that contains messages to be read. The difference is data queues contain data instead of jobs, spooled files or messages.

As with any queue, something enters the queue to be processed and leaves after processing is complete. The queue is processed in a predetermined order; most often it's first in first out (FIFO). However, data queues can also be processed by last in first out (LIFO) order or by key.

Data is written (sent) to a data queue something like a record to a file or a message to a message queue. It stays there until one of your programs requests (receives) the data. The data is not meant to be stored there permanently-only temporarily until a program receives it for processing.

The sending and receiving of data is what the data queue is all about. Unlike database files, getting data to or from data queues involves very little overhead. In fact, data queues are the fastest means of communicating between two jobs.

There are countless ways in which you can take advantage of data queues in your applications. For the purposes of this article, however, we don't need to get into them. For ideas and more information, see "AS/400 Data Queues" (MC, August 1990) and "Lining Up for Data Queues" (MC, May 1992).

We'll now look at how data queues can be used in a cooperative processing environment.

The Part They Play

The communication abilities of data queues are what brings the PC Support data queue function into the cooperative processing picture. Applications on your AS/400 and on any PC connected to it via the extended DOS or OS/2 version of PC Support can communicate with a data queue. This means you can indirectly link programs even when they are on different machines.

For a conceptual view of this, refer to 1. You can see that, no matter what machine an application is on, it can send or receive data through the data queue. In this illustration, the data queue acts like a communications hub for the applications in this network. Any application can essentially talk to another application.

For a conceptual view of this, refer to Figure 1. You can see that, no matter what machine an application is on, it can send or receive data through the data queue. In this illustration, the data queue acts like a communications hub for the applications in this network. Any application can essentially talk to another application.

For example, let's say a PC application needs some data from the AS/400. The PC program sends a request to the data queue that an AS/400 application program can recognize. The AS/400 program could then get the requested data and place it on the data queue. The PC program would lastly retrieve the data it wants from the data queue. Pretty simple stuff, yet powerful. In reality, you might want to create more than one data queue for a similar example (one to process requests from the PC and one to process the data from the AS/400).

Working with Data Queues

Data queues are nothing new on the AS/400, and the PC Support data queue function really doesn't add anything new to how you work with them. You can use the Create Data Queue (CRTDTAQ), Delete Data Queue (DLTDTAQ) and Work with Data Queue (WRKDTAQ) commands. The WRKDTAQ isn't as powerful as it sounds-it only provides a create, delete or change description function.

The only direct AS/400 interface to a data queue is through APIs. You can send data to the data queue with the QSNDDTAQ API, receive data with the QRCVDTAQ API or clear data with the QCLRDTAQ API. See the articles mentioned earlier or the CL Programmer's Guide for more information on how to use these APIs. PC Support offers eight commands for the PC that allow you to work with data queues: one for activating the data queue function, and seven for data queue management and operation functions. I'll give you a brief overview of the commands here; for more information on formatting requirements, see the chapter devoted to "Using Data Queues with PC Support" in the PC Support/400 DOS User's Guide or the corresponding chapter in the PC Support/400 OS/2 User's Guide. You can also get online help on your PC by keying PCSHELP followed by a space and a valid command, provided PC Support is active. For example, to get help for the CRTDTAQ command, just key:

PCSHELP CRTDTAQ

The Load Data Queue (LOADDQ) command loads the data queue function into extended PC memory as a terminate and stay resident (TSR) program.

The management commands are Create Data Queue (CRTDTAQ), Delete Data Queue (DLTDTAQ) and Query Data Queue (QRYDTAQ). QRYDTAQ isn't as powerful as it sounds. It displays only the attributes, not the data that may be in it.

The operational commands are Send Data Queue (SNDDTAQ), Receive Data Queue (RCVDTAQ), Clear Data Queue (CLRDTAQ) and Stop Data Queue (STPDTAQ). STPDTAQ ends any active data queue conversations, but doesn't remove the TSR function from memory. You must use the Remove PC Support (RMVPCS) command for that.

All of the commands (except for LOADDQ and STPDTAQ) allow you to optionally specify an AS/400 library where a data queue can be found or created. If a library is not specified, the system will use the default library list associated with your user profile to find the data queue; if you are creating a data queue and don't specify a library name, the system will use the current library.

Some Useful Examples

Now, let's look at two working cooperative processing examples that employ data queues. The first example illustrates how a PC program can retrieve data from an AS/400; the second example illustrates how one PC can execute a command on another PC. (The first example requires the PC Organizer to be active. Both require the data queue function to be already loaded on the PC(s) that will be executing the sample programs.)

The first example is a PC batch program (RTVUSRD) which retrieves a user profile's description from the AS/400 and loads it into a PC file. There are three components: a PC batch program (RTVUSRD.BAT, in 2), an AS/400 command (SNDUSRD, in 3) and a CL program (USR004CL, in 4). This is an example of a PC program cooperating with an AS/400 program. Although the PC batch program is simple, the steps would be the same even if you were retrieving the data from a program running under Microsoft Windows or OS/2. The program serves no practical purpose; it's only meant to show how data can be passed from one system to another through a data queue.

The first example is a PC batch program (RTVUSRD) which retrieves a user profile's description from the AS/400 and loads it into a PC file. There are three components: a PC batch program (RTVUSRD.BAT, in Figure 2), an AS/400 command (SNDUSRD, in Figure 3) and a CL program (USR004CL, in Figure 4). This is an example of a PC program cooperating with an AS/400 program. Although the PC batch program is simple, the steps would be the same even if you were retrieving the data from a program running under Microsoft Windows or OS/2. The program serves no practical purpose; it's only meant to show how data can be passed from one system to another through a data queue.

To execute the program, be sure the PC Organizer function is loaded. Key the program name followed by a space, and the user profile you would like to retrieve the description from. For example:

RTVUSRD RSHALER

The RTVUSRD batch program (2) is very easy to follow. I first attempt to create the data queue with the CRTDTAQ command. If it's already there, no problem-the redirection to NULL eliminates the error message you would see. The program then executes the AS/400 SNDUSRD command (3) through the PC Support Remote Command (RMTCMD) command. If you've never used RMTCMD, you should check it out. It allows you to execute any AS/400 command from the PC. Although it does have some limitations (e.g., if the AS/400 command outputs to the display, you won't receive the output), overall it can be quite useful.

The RTVUSRD batch program (Figure 2) is very easy to follow. I first attempt to create the data queue with the CRTDTAQ command. If it's already there, no problem-the redirection to NULL eliminates the error message you would see. The program then executes the AS/400 SNDUSRD command (Figure 3) through the PC Support Remote Command (RMTCMD) command. If you've never used RMTCMD, you should check it out. It allows you to execute any AS/400 command from the PC. Although it does have some limitations (e.g., if the AS/400 command outputs to the display, you won't receive the output), overall it can be quite useful.

The command processing program (USR004CL, in 4) for the SNDUSRD command displays the user profile information to an output file and then reads the output file to retrieve the user profile description. As its final task, the program sends the profile description as data to the PCDTAQ data queue using the QSNDDTAQ API.

The command processing program (USR004CL, in Figure 4) for the SNDUSRD command displays the user profile information to an output file and then reads the output file to retrieve the user profile description. As its final task, the program sends the profile description as data to the PCDTAQ data queue using the QSNDDTAQ API.

When the remote command (SNDUSRD) completes, the PC batch program receives the data sent by the AS/400 to the PCDTAQ data queue and redirects it to file USRD. We now have a file with data in it from the AS/400. The program displays the data in the file with the TYPE command as evidence the data was received.

Although this first example doesn't accomplish much, don't underestimate what is happening here. Using the same method, any PC application can retrieve data from the AS/400.

The second example is more useful and illustrates cooperative processing between three machines: a PC, the AS/400 and another PC. Let's say it's late and you want to go home, but there are some jobs yet to be run on your PC. If you could run these jobs remotely from your PC at home, you could leave. The programs in this example would enable you to do just that. Assuming that your PC at home and your PC at work are connected to your AS/400 via PC Support, all you have to do is execute the Receive Remote Request (RCVRMTRQ.BAT) program (see 6) on the PC at work before you leave for home. When at home, you can then use the Send Remote Request (SNDRMTRQ.BAT) program (see 5) to send any command you would like to your PC at work and it would be executed on the AS/400.

The second example is more useful and illustrates cooperative processing between three machines: a PC, the AS/400 and another PC. Let's say it's late and you want to go home, but there are some jobs yet to be run on your PC. If you could run these jobs remotely from your PC at home, you could leave. The programs in this example would enable you to do just that. Assuming that your PC at home and your PC at work are connected to your AS/400 via PC Support, all you have to do is execute the Receive Remote Request (RCVRMTRQ.BAT) program (see Figure 6) on the PC at work before you leave for home. When at home, you can then use the Send Remote Request (SNDRMTRQ.BAT) program (see Figure 5) to send any command you would like to your PC at work and it would be executed on the AS/400.

Basically, you're sending the PC command to a data queue. The PC on which you would like to execute this command is running a program that is waiting to receive data from the data queue. When data (in this case a PC command) is received, the PC executes the command. That's all there is to it.

Let's examine things in more detail, starting from the remote PC sending the command to be processed on the PC at work. It uses program SNDRMTRQ. From your home PC, key SNDRMTRQ followed by a blank and an identifier (maximum of six characters) for the remote PC. It starts by creating the RMTRQDTAQ data queue on the AS/400. Notice that the data queue is indexed with a key. This allows you to identify the PC where you want to process the remote command you send and to execute commands on more than one remote PC. Then the program calls the PC Support/400 SNDDTAQ command which prompts the user for data (it actually requests data using the term "message"). You key the PC command and press Enter. You can enter additional commands if you'd like; each one becomes another entry in the data queue. (If the remote PC is waiting forever for a command-you'll learn about this later-enter 'quit' as the last command.) Lastly, press F6 followed by Enter. This tells the SNDDTAQ command that you are done.

Now let's watch the PC at your work location. It must be running the RCVRMTRQ program. At the time you start this program, you pass it two parameters: the first identifies the PC running the command and the second tells the program how long to wait for a remote request from the data queue.

You can use any value (maximum of six characters) to identify the PC. The reason for this is so you can be running the program on more than one PC-each one using a different identification. Any command sent to the RMTRQDTAQ data queue with the same key value used by an active RCVRMTRQ program will be executed on that PC.

For the wait parameter you can submit three different values. Use 'F' (or 'f') to indicate that the program should wait forever for a command. Once the RCVRMTRQ program receives a command, it is executed and the program loops back and waits again. This is how the program processes more than one command.

A positive integer value indicates how many seconds to wait and a value of zero means don't wait. If no value is submitted for this parameter, the wait time defaults to zero. With a positive value or a value of zero, the program receives and executes only one command. There is no looping for additional commands when these values are used.

Many of you may be uncomfortable with these PC batch programs; but as long as you key them correctly, they should work. Also remember that they will be on the MC-BBS for downloading by the time you read this. I encourage you to give them a try. (If you plan on getting into cooperative processing, you will eventually have to acquire some degree of PC knowledge.)

All Kinds of Possibilities

With the PC Support data queue function, we were able to create two simple yet powerful cooperative processing applications. It wouldn't take much imagination to create different and/or more complex ones. For example, one day several months ago I was talking to an MIS manager about a zip code database that was available for the PC and the AS/400. The PC version on CD-ROM was selling for a fraction of what the AS/400 version cost. Furthermore, the MIS manager's AS/400 DASD was nearing capacity. We thought it would be great if the AS/400 could access the data on the PC, so literally thousands of dollars could be saved and the AS/400 DASD wouldn't have to be burdened.

Later, I came across the new data queue function of PC Support and suddenly realized that the AS/400 could access information on a PC through a data queue. The AS/400 could get to the PC database with a surprisingly small amount of programming.

Here is a brief sketch of a possible solution. When the AS/400 operator needs to validate an address by examining the PC zip code database, he presses a function key. A request for the validation and the address is placed on a data queue. The PC with the zip code database runs a program charged with the full- time job of waiting for requests from the data queue. When a request is received, the PC validates the address and then sends information on the validity of the address to another data queue. The AS/400 program that sent the request then receives the information sent by the PC via this data queue.

This solution may not be the ultimate approach, but it does allow a rather simple solution to the problem. It's easy to see a whole world of possibilities with the PC Support data queue function.

Richard Shaler is a senior technical editor at Midrange Computing.

Author's Note: Thanks to Ron R. Turull for his assistance with the PC programs.

References

Microsoft MS-DOS manual CL Programmer's Guide (SC41-8077, CD-ROM QBKA7101) CL Reference (SC41-0030, CD-ROM QBKA8201) PC Support DOS User's Guide (SC41-8199, CD-ROM QBKA6201) PC Support OS/2 User's Guide (SC41-8200, CD-ROM QBKA6601)

Easy Co-op Processing Programming with Data Queues

Figure 1 AS/400 and PC Data Queue Shraing Concept:

 UNABLE TO REPRODUCE GRAPHICS 
 
 Easy Co-op Processing Programming with Data Queues
 
 Figure 2 Retrieve User Description (RTVUSRD.BAT) Batch Prog
 
 @echo off rem ==================================================================== rem Retrieve user profile description rem Parameter 1 is used to pass user profile name rem ==================================================================== IF '%1' == '' ECHO Parameter one must contain a user profile name. IF '%1' == '' PAUSE IF '%1' == '' GOTO ENDPGM rem Create data queue CRTDTAQ PCDTAQ /L=QGPL /M=50 /O=FIFO /Z > NULL rem Execute remote Send User Description (SNDUSRD) command on the AS/400 rem This will place the user description in data queue PCDTAQ RMTCMD SNDUSRD %1 /Z > NULL rem Get the data from the PCDTAQ data queue and redirect to file USRD RCVDTAQ PCDTAQ /W=0 /Z > USRD ECHO. ECHO Data from AS/400 data queue follows: ECHO. TYPE USRD ECHO. :ENDPGM 
 
 Easy Co-op Processing Programming with Data Queues
 
 Figure 3 SNDUSRD Command
 
 /*===============================================================*/ /* To compile: */ /* */ /* CRTCMD CMD(XXX/SNDUSRD PGM(XXX/USR004CL) + */ /* SRCFILE(XXX/QCMDSRC) */ /* */ /*===============================================================*/ CMD PROMPT('Send user profile description') PARM KWD(USRPRF) TYPE(*NAME) LEN(10) PROMPT('User + profile') 
 
 Easy Co-op Processing Programming with Data Queues
 
 Figure 4 CPP Program USR004CL
 
 /*===============================================================*/ /* To compile: */ /* */ /* CRTCLPGM PGM(XXX/USR004CL) SRCFILE(XXX/QCLSRC) */ /* */ /*===============================================================*/ USR004CL: PGM PARM(&USRPRF) DCL VAR(&DQ) TYPE(*CHAR) LEN(10) VALUE(PCDTAQ) DCL VAR(&DQLIB) TYPE(*CHAR) LEN(10) VALUE(QGPL) DCL VAR(&DLEN) TYPE(*DEC) LEN(5 0) VALUE(50) DCL VAR(&USRPRF) TYPE(*CHAR) LEN(10) DCLF FILE(QADSPUPB) MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(ENDPGM)) DSPUSRPRF USRPRF(&USRPRF) OUTPUT(*OUTFILE) + OUTFILE(QTEMP/USRD) MONMSG MSGID(CPF2204) EXEC(DO) CHGVAR VAR(&UPTEXT) VALUE('No user profile found + for' *BCAT &USRPRF) GOTO CMDLBL(SNDDTAQ) ENDDO OVRDBF FILE(QADSPUPB) TOFILE(QTEMP/USRD) RCVF SNDDTAQ: CALL PGM(QSNDDTAQ) PARM(&DQ &DQLIB &DLEN &UPTEXT) DLTOVR FILE(QADSPUPB) ENDPGM: ENDPGM 
 
 Easy Co-op Processing Programming with Data Queues
 
 Figure 5 Send Remote Request (SNDRMTRQ.BAT) Batch Program
 
 @echo off rem ==================================================================== rem rem Send remote request to AS/400 data queue RMTRQDTAQ. rem Parameter 1 contains the key value that identifies the remote PC rem rem ==================================================================== rem Create data queue CRTDTAQ RMTRQDTAQ /L=QGPL /M=80 /O=KEYED /C=6 /Z > NULL rem Send remote request to data queue CALL SNDDTAQ RMTRQDTAQ /K=%1 
 
 Easy Co-op Processing Programming with Data Queues
 
 Figure 6 Receive Remote Request (RCVRMTRQ.BAT) Batch Progra
 
 @echo off rem ==================================================================== rem rem Receive remote request from AS/400 data queue RMTRQDTAQ. rem rem Parameter 1 contains the key value that identifies the PC rem executing this program. rem rem Parameter 2 contains the number of seconds to wait for the data. rem The default value is 0. rem rem Possible values: rem rem 'F' - wait forever and try again after rem message is received rem Positive value - wait the specified number of seconds rem Value of 0 - don't wait rem rem ==================================================================== set var= rem Create data queue CRTDTAQ RMTRQDTAQ /L=QGPL /M=80 /O=KEYED /C=6 /Z > NULL rem Create the QUIT.BAT file echo set var=quit> quit.bat rem Create a batch file named the same as the key value echo echo Command completed > %1.bat SET WAIT=%2 IF '%2' == 'F' SET WAIT=-1 IF '%2' == 'f' SET WAIT=-1 IF '%2' == '' SET WAIT=0 :RCVDTAQ rem Get remotely submitted command CALL RCVDTAQ RMTRQDTAQ /W=%WAIT% /K=%1 /S=EQ /Z > CMD.BAT rem Execute remote command CALL CMD.BAT IF '%VAR%'=='quit' GOTO EXIT IF %WAIT% == -1 GOTO RCVDTAQ :EXIT SET VAR= SET WAIT= 

Also Read

The Power of Writing Code in a Low-Code Solution

TechTip: Let’s Have a Date, Part 2

Going off the Rails