APPC communication Testing on the AS/400
By Thibault Dambrine
Part I, the configuration
If you have done any kind of communication programming on the AS/400, you must know that the first few attempts to get a conversation going between two programs is hard enough without having to worry about lines and configurations to a remote system.
Getting a spare system to communicate with or a line that you can vary on or off without disturbing ongoing operations can be difficult and/or inconvenient. Fortunately, the AS/400 has some convenient built-in tools that go a long way in cutting the aggravation of finding lines, hardware, and generally speaking, resources, at least for the initial testing phases.
This article will discuss two types of configuration that allow communication testing within the walls one AS/400 box and information on debugging and tracing an ICF conversation.
Let's assume that you are developing a two-program , two-different-AS/400-system application, with one program talking to the other through a communication line. Program "A" will send a customer information request to program "B", program "B" will do a lookup in a file, retrieve the customer information and send it back through the line to program "A" to display it.
We assume at this point that both programs are coded and ready for testing. If you have two AS/400's available, you can start configuring the lines, controllers and devices, vary the lines on both systems and start from there. An ideal situation.
Unfortunately, for a thousand different reasons, this might not be the case. The more likely situation is that you have only one AS/400 to work with and you will have to rely on simulations for your testing until proper resources can be used or made available. This is where the communication testing options provided by OS/400 can be very helpful.
The INTRASYSTEM link
The simplest and easiest testing tool for simulating communication between two parties is the intrasystem feature. Here is how it works:
Use the CRTDEVINTR (Create Device Description Intra) command. Here is an example:
CRTDEVINTR DEVD(INTRADEV) RMTLOCNAME(INTRARMT) +
ONLINE(*NO) TEXT('Text for intra device')
Notice, there are no controllers or lines involved here. They are implied, since all the communication is going on inside the same AS/400 No hardware resource is involved. This device is all that is needed, on either side of the conversation you are setting up. You can evoke, acquire, read, write and invite, mostly the same way as you would do it from one system to an other.
This device behaves just as if it were connected to a controller and a line. The only difference is that if, for example you would do an evoke of an other program, the evoked program would be on the local system. You can add this device with it's remote location name to an ICF file just like you would do for a normal device. The Intra functionalities are similar to APPC, but not completely the same, we will get to this later on.
This is the simplest possible solution to do simulations. It can be most useful if you are writing an AS/400 application that will "talk" to a non-AS/400 machine. In this case, you could code a simple "echo" program that will respond to your originator through the INTRA device. Good enough to test and work out the obvious bugs. All the signals are internal, nothing goes through the outside world, bugs can be cleaned up with minimum difficulty and hassle.
APPC with LINKTYPE(*LOCAL)
Although INTRA is a good testing solution and it does the job rather well, if you will code an application that will use APPC, it might not be your best testing option. Here are some of the reasons why:
- Intrasystem communications implicitly responds to a confirm request in the AS/400 environment, whereas APPC communications does not.
- Intrasystem communication does not buffer data, APPC does.
- Not all the four-digit return codes match from APPC to INTRA.
Coming to the point. We need a different tool to test APPC applications. Fortunately, we do have that tool. An APPC controller with linktype *LOCAL does the same job as the intrasystem device, exept with a few extra configuration steps. We still do not need a line, but this time a controller is necessary. Here is an example of the APPC local link configuration:
CRTCTLAPPC CTLD(APPCTSTCTL) LINKTYPE(*LOCAL) ONLINE(*NO) +
TEXT('Controller for testing APPC communication applications')
CRTDEVAPPC DEVD(APPCTSTDV1) RMTLOCNAME(APPCLOC2) +
ONLINE(*NO) LCLLOCNAME(APPCLOC1) +
RMTNETID(*NETATR) CTL(APPCTSTCTL) +
APPN(*NO) SECURELOC(*YES) +
TEXT('Device #1 description for testing APPC communication applications')
CRTDEVAPPC DEVD(APPCTSTDV2) RMTLOCNAME(APPCLOC1) +
ONLINE(*NO) LCLLOCNAME(APPCLOC2) +
RMTNETID(*NETATR) CTL(APPCTSTCTL) +
APPN(*NO) SECURELOC(*YES) +
TEXT('Device #2 description for testing APPC communication applications')
Having configured these devices and controllers, you can test your APPC application, just as if you had configured a real line between two different systems. Be careful to match the local and remote addresses properly. Not doing so will result in failure to bring these newly created devices up.
An interesting side benefit to have this type of setup on your system, is that you can test your virtual devices with it. You can use this local link to passthrough to the same machine as the one you are on. Use the command STRPASTHR with the remote location name of either APPC device attached to the (local) controller. In this way, you can litterally passthrough to yourself.
Part 2: Tracing conversations
Both INTRA and APPC *LOCAL allow you to use TRCICF (Trace ICF). It is the most common and easy to use tool when debugging a conversation between two programs.
It shows the data that goes through the line, the length of the messages, the remote locations, time stamps and communication return codes. The TRCICF instruction can be included in the CL that calls your application and it yields most of the necessary ICF (Intersystem Communication File) information.
Unfortunately, TRCICF does not always tell the full story. Some of the "undercover" support codes and message exchanges are not displayed by TRCICF. To get down to the bits and the nitty-gritty of the binds, you need an other tool: STRCMNTRC, or Start Communication Trace.
STRCMNTRC requires a physical line, emulators such as intra devices are not enough. This means that before you use this type of trace, you have to be far enough to be configured to an ouside system.
STRCMNTRC is similar to having a separate electronic line monitor physically plugged to your wire. The CMNTRC command set shows everything. It is mostly useful when you have used up all possibilities of finding an answer with TRCICF.
There are several commands associated with this type of command trace:
- STRCMNTRC : Start communications trace
- ENDCMNTRC : End communications trace
- PRTCMNTRC : Print communications trace
- DLTCMNTRC : Delete communications trace
Note: To use those trace tools, you need either QSECOFR or QSRV authority
Some of the bind codes and SNA signals are completely useless unless you have the SNA formats manual to be able to decipher them. Using CMNTRC commands is something you will want to consider only when you come to a stage where really, there is not enough information coming from TRCICF.
The ability to test, trace and debug the whole project on one machine has several advantages:
It will save initial setup configuration time. It will eliminate the need to propagate programs on two different machines every time you make a new modification. It will reduces possible line delays between two systems to a mimimum (everything is on the one box) while you are testing.
The various testing and debugging aids presented here are part of the operating system on the AS/400. If you do decide to explore ICF programming from AS/400 to AS/400 or from AS/400 to any other machine; these tools are valuable time savers. For more information, see the ICF Programmer's Guide and the Intrasystem Communications Programmer's Guide.