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.
In conclusion
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.