/* Remote VPLUS invocation facility Version 1.3 / 04.apr.02 - 08.jun.03 Copyright (C) 2002-2003 Lars Appel This package is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this package; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ ______________________ Notes for Remote VPLUS Lars Appel, 14.apr.02 / 08.jun.03 ________ overview Remote VPLUS invocation facility is a quick and dirty prototype for intercepting calls to the VPLUS intrinsic API and redirecting them to an(other) MPE/iX session across a socket connection. It can be useful when debugging a VPLUS program on an HP 3000, where the VPLUS screens can be sent to a separate terminal (which does not have to be a nailed DTC serial LDEV) so that they don't interfere with the debugger output. It can also be useful when trying to migrate VPLUS based programs to another platform (like Unix) where no immediate replacement for the VPLUS user interface might be available. By redirecting VPLUS calls to an HP 3000 session, you can first focus on other migration issues before having to deal with the user interface. The main parts of Remote VPLUS are the intercept library and the display server, which communicate with a TCP/IP socket connection. The server program has to be run on MPE/iX using a VPLUS capable terminal or emulator (because it invokes the real VPLUS intrinsics and carries the forms display), whereas the client program that is linked with the intercept library can be run on MPE/iX or Unix. At present, I have only run the client part on MPE/iX and HP-UX. When using Linux or other Unix flavours, issues like character set (Roman8 versus ISO 8859_1, for example) and byte ordering (PA-RISC processors are big-endian machines by default) need to be solved. _________ compiling The Makefile has to be customized for the target platform and compiler being used. You can find setting sections for mpeix with gcc as well as hpux with ansic or gcc near the top. Just uncomment one of them (or customize for different tools or needs). The package includes a small example in Pascal and COBOL. If you have the appropriate compilers installed, you can build them as well. Use the precompiled binaries (or your own examples) if not. On MPE/iX use... shell/iX> make mpeix shell/iX> make test1m shell/iX> make test2m On HP-UX use... $ make hpux $ make test1u Compiling the COBOL example depends on your specific COBOL compiler, with AcuCOBOL or MicroFocus COBOL you might have to generate a custom runtime system to link in the intercept library routines. The build process will generate the VPLUS intercept routines as an archive and shared library (NMRL or NMXL in MPE terms), so you can either link the code to your program or reference it at runtime. _______ running Run the display server program in one session... :chdir /YourACCT/YourGRP/rvplus :xeq /bin/sh " -c 'SERV_PORT=12345 ./rvpserv' " Run the client program in another MPE session... :chdir /YourACCT/YourGRP/rvplus :setvar SERV_ADDR "127.0.0.1" :setvar SERV_PORT "12345" :run ./test1m Or run the client program on a Unix machine... $ cd /path/to/rvplus $ export SERV_ADDR=your_3000_ip_addr $ export SERV_PORT=12345 $ ./test1u Notice that the display server program forks a child process for each incoming client connection. This works best if you add calls to cli_init() and cli_exit() at the beginning and before the exit of the client program. If you do not do this, the first call to one of the intercepted VPLUS intrinsics will call cli_init() for you, however, the lack of cli_exit() will cause the server side child process to not terminate properly. However, you will need to Break and :ABORT the display server program anyway, because it does not know if your client application was a single process or a process family sharing the VPLUS terminal. ______ issues The error handling in the current version is somewhat quick and dirty. In many cases I simply called DEBUG() to get a "hands up". This is certainly an area for improvements. At present, I have no idea why the server program cannot simply be started with (implied) RUN but needs to be launched via Shell invocation. When run directly from the CI, I always get a "bad file number" error from the call to bind() the server socket. (see SR 8606-228487 and related MPE/IX NST patches for a fix) The program intercepts quite a number of VPLUS intrinsics, even "exotic" ones like VBLOCKWRITE and VBLOCKREAD. However, until now I have not yet tested whether all of them work properly. This is an area for community contributions or feedback ;-) The intrinsics VGETSAVEFIELD and VPUTSAVEFIELD that have been added as part of Year 2000 enhancements are also intercepted by this package. However, it turned out that some systems do either not have them installed or (due a bad patch) have them installed as hidden. This can result in the server program failing with an Unresolved Externals error message. To work around this issue, you can link the server program with two stub routines by using "make STUB=stub.o mpeix" (which will only work if your client program does not really call those two intrinsics, of course). ________ java gui I have added a small Java GUI program that can be used as an intermediate stage for tracing the VPLUS calls between client and server. It acts as a middleman for the socket traffic and displays a trace of VPLUS calls passing by. At present, this is not more than just the intrinsic names, but this could be extended to also display the request and response parameters. It might even be possible to evolve this into a Java GUI that takes over parts or all of the VPLUS functionality. The Java GUI program acts as a "socket server" for the VPLUS client and as a "socket client" for the VPLUS display server, so you run the Java GUI program, telling it what port number to listen to and how to contact the real VPLUS display server on MPE/iX. The you run the VPLUS client program against the Java GUI program instead of the VPLUS server directly... :# in the vplus display session :xeq /bin/sh " -c 'SERV_PORT=12345 ./rvpserv' " C:\> rem -- on the java gui platform C:\> java Disp 23456 ip_of_the_3000 12345 :# in the vplus client session :setvar SERV_ADDR "ip_of_the_java_box" :setvar SERV_PORT "23456" :run ./test1m The above also works if the vplus client is running on Unix ;-) _______ history 14.apr.02 - added debug.c source file that was missing in invent3k tarball - fixed hp32209() in client.c to pass proper buffer size (14 byte) - fixed vsetlang() in client.c and server.c for by-value langnum - added #ifdef U384 to client.c and Makefile for make U384=-DU384 - adjusted Makefile to use test1m and test1u for MPE/HPUX targets - adjusted Makefile to send Pascal compiler listing to $NULL now 18.apr.02 - added vputsavefield and vgetsavefield intrinsics (thanks to Keven) - added test2.cbl as Cobol example to the existing Pascal test1.p[as] 20.apr.02 - added stub.c for systems with missing v???savefield intrinsics - introduced GNU Lesser GPL as file Copying and added references - added a Java GUI program that can act as "tracing middle-man" 03.mar.03 - v1.1 for mpeix and hpux: Makefile modified to also create librvp.sl 08.mar.03 - v1.2 for hpux: client.c now uses upper.c and lower.c VPLUS intercept 08.jun.03 - v1.3 for mpeix and hpux: fixed bug in vsetkeylabels() intercept - also merged build process to common Makefile for mpeix and hpux