Z3INStp AUTO-INSTALLER FOR TURBO-PASCAL PROGRAMS RUNNING ON ZCPR3 SYSTEMS ; This file and all files in the LIBRARY called ZTP-INS2.LBR ; are copyright 1985 by Steven M. Cohen, and therefore remain ; his property. You may freely distribute it, but you may not ; sell it or bundle it as part of any package for sale ; without the express written consent of the author. Introduction Last June, in the first blush of my enthusiasm for ZCPR3, I released a package called ZTP-INS.LBR. That package contained a Turbo-Pascal program that installed Video control sequences directly from ZCPR3 TCAPS (Terminal Capability Segments) into other programs compiled by Turbo-Pascal. ZTP-INS was not a bad program, but it's documentation was florid, and it contained several features that were practically useless. Worst of all, it contained the 10 or so K run-time package that all Turbo-Pascal programs use making for a much bigger program than was necessary for such a simple task. This package, contained in ZTP-INS2.LBR contains an assembly-language version of the old program, called Z3INSTP.COM, which deletes the features that were not useful in the earlier version and adds a few new ones: 1> the ability to turn off highlighting -- Some programs may be written on systems with reduced intensity. When these are ported to systems that have inverse video instead of reduced intensity the resulting screens actually look worse than they would without any highlighting. A simple command line switch allows highlighting to be turned off. 2> the ability to REVERSE high and low video -- as above, in some cases, simply reversing what was highlighted and what was normal will improve things considerably. This too can be selected on the command line. 3> the option to install the arrow keys directly into the program for any program written to take advantage of this capablility. This scheme will work for any terminal that has arrow keys which generate single bytes. This option is also selectable at the command line. .heZ3INStp - Auto-installs Turbo-Pascal programs on ZCPR3 systems 4> Z3INSTP.COM is a ZCPR3 utility and accesses the environment descriptor automatically, instead of needing it to be specified on the command line. Like most Z3 utilities it comes with it's own built-in help screen. Z3INStp also gives full control of user areas with Z3's DU: specification but not the DIR: form. Installing Z3INStp Since Z3INSTP.COM is a ZCPR3 utility it must be installed as all ZCPR3 utilities are, for the user's system. The command line for this is the usual: Z3INS SYS.ENV Z3INSTP.COM Z3INStp now be ready to use on the user's system. Invoking Z3INStp Z3INStp is easily invoked from the command line. For the default mode (without options) simply type: Z3INSTP filename where filename is the name of a .COM file optionally prefixed with a DU: (disk-user) specification. E. G. Z3INSTP FATCAT Z3INSTP FATCAT.COM Z3INSTP B7:FATCAT.COM Note that the .COM extension is optional on the command line. If a file of .COM type is not found, an error message will result. If you type for example Z3INSTP FATCAT.OBJ the program will look only for FATCAT.COM, aborting if it is not found, even if FATCAT.OBJ is present. In other words, Z3INStp only installs .COM files. Furthermore, Z3INStp checks to see if the specified file was compiled under Turbo-Pascal (version 2.0 or higher), again aborting if it was not. This prevents against damaging files which will not work with these installations. As an added measure of safety, Z3INStp first renames the file to be installed with the name filename.OLD, then creates a new file from scratch upon which the new installed values are placed. If for some reason Z3INStp fails, simply rename filename.OLD back to filename.COM. If filename.OLD already exists, you are queried before the old copy is deleted. Better safe than sorry. Options Options are selected on the command line as parameters after the filename is typed. Options, if any, are combined into a single "word" as the second command line parameter: Z3INSTP FATCAT A Z3INSTP FATCAT.COM AR Z3INSTP FATCAT HA There are only 3 options: option 'H' - turns off highlighting in the program being installed, as described above. That is the program will run as though it were running on a terminal without highlighting. option 'R' - reverses what is highlighted and what is not, as described above. If this option is chosen together with the 'H' option, then it will be ignored. option 'A' - installs the arrow keys as described above. Note that for this option to work the program documentation must specify that arrow keys can be installed this way. As of now, the only program that can be installed in this way is FATCAT by the author of Z3INStp. Hopefully, other programmers may decide that this is a useful idea and implement it in their programs. Also, arrow keys must be installed in the user's TCAP -- and for this to happen, the arrow keys must generate only single- character sequences. Most arrow keys work this way, but a few do not. However, not to worry. Even if the program you are installing does not support this convention, it does no harm. Programmers wishing to write programs using Z3INStp should consult the section "Arrow Key Programming" below. Theory of Z3INStp Z3INStp works because both ZCPR3 and Turbo Pascal code their terminal data in readily accessible places. Similar setups could be worked up for any program or programming language that used a similar method of accessing terminal data. As neatly as Z3INStp works it is important to note what it CANNOT do. It cannot make Turbo programs use the TCAP the same effortless way zcpr3 utilities do. That is, it can only install programs to specific TCAPs. It is easy to reinstall these programs for different TCAPs but you must reinstall for each TCAP used. You cannot simply LDR a new TCAP and expect your program to work right. The reason for this is simple. Turbo and ZCPR3 use completely different methods of formatting their terminal data. Turbo uses the fixed length string method, where each terminal function can be found at specific, exact locations in memory. These locations are the same for every Turbo program (at least those under versions 2.0 and 3.0), and indeed, for TURBO.COM itself. Further, they follow the Turbo-Pascal String format, wherein the first byte of the string variable is the actual length of the string. ZCPR3 TCAPs use the "null-termination" method so the beginning address of the TCAP is readily available, others are not. It would be possible, but hardly worthwhile, to write Turbo-Pascal programs redefining the terminal procedures such that they accessed the ZCPR3 locations. Therefore, we can best see Z3INStp as a halfway house between total ZCPR3-utility video compatibility, and non- compatibility. It is simply a translation program. Its main use as I see it, is to enable ZCPR3 users to install Turbo-programs on their terminals without the space-wasting and clumsy methods of TINST and GINST, which amount to a duplication of effort after you have installed your TCAP. It also is a nice demonstration of the advantages of ZCPR3 over CP/M. Weaknesses of Z3INStp and Future Directions Z3INStp will not work on terminals with "non-fixed-length ASCII " cursor addressing sequences. These are terminals which use the "%d" in their cursor addressing. For example the H19 Terminal ANSI mode, whose ZCPR3 cursor addressing sequence is 1BH,'[%d;%dH',0. I cannot find any such terminal definitions used by TURBO, so had no point of reference. I am reasonably sure that Z3INStp will work on terminals with "fixed-length ASCII addressing" but have not tried one, so would appreciate any bug reports on this at the "home base" listed below. (See chapter 22 of ZCPR3 - the Manual if you do not understand this paragraph.) Z3INStp has a couple of inherent weaknesses due to partial incompatibilities of ZCPR3 TCAPS with Turbo-Pascal terminal definitions. Specifically, TCAPS do not have sequences for Insert Line and Delete Line (the Turbo procedures InsLine and DelLine). Luckily, these are probably less used than the other terminal functions. I find that I seldom use them in my own programming; their most frequent use seems to be in the Turbo Editor itself; here, Borland's programmers have been smart enough to include workarounds for terminals not supporting these functions, a practice that others might want to emulate. Nonetheless, it would be nice to be able to access these functions. Looking at the TCAPS that currently exist, it would seem to be easy to add these functions at the end of the TCAP as they all seem to have ample space in the 128 byte standard allocation. I wonder what do the authors of ZCPR3 think about extending the TCAPS to include these functions? The other weakness in the concept behind Z3INStp has largely been largely eliminated with the arrow-key installation procedure described above. However, this creates some other minor difficulties for programmers, which I will now attempt to clear up. Programmer's Guide to Arrow Key Installation In designing the arrow-key interface, the following scheme suggested itself. The Turbo-Pascal Terminal Name string occupies 21 bytes in memory starting at 0153h. The first byte contains the actual length of this string, so there is a maximum of 20 bytes available for the terminal name. Quite by accident, the Turbo TCAP string holding the terminal name occupies a maximum of 16 bytes. Therefore we have four bytes available on the Turbo Interface page (0164 - 0167h) that will almost certainly not conflict with anything. These four bytes are not used in any way once the shorter TCAP string is overlaid over the original Turbo string. Therefore, all that is needed in your program to allow the arrow key option 'A' to work is the following code: VAR UpArrow : Char absolute $0164; DownArrow : Char absolute $0165; RightArrow : Char absolute $0166; LeftArrow : Char absolute $0167; However, this creates another problem if the program will also be run on non-Z3 systems. For those installations something similar to TINST or GINST must be used, and in that case characters from the 20 character Turbo terminal name will fill these spaces, with the possibly unfortunate consequence that a printable ASCII character will be interpreted by the program as an arrow key. This can be cured by placing the following statement at the beginning of the program: For X := Addr(UpArrow) to Addr(LeftArrow) do If Mem[X] in [32..127] then Mem[X] := 0; If the program has been installed by a GINST method, these locations will contain characters in the 32..127 range and will thus be converted to zeroes in memory. If there is a need in your program for the Terminal name, it can be copied out of this area before the above statement is executed. Other Possible Problems Turbo-Pascal programmers ought to end their programs with the CRTExit statement. That way, any special video effects can be turned off, if the user includes in his terminal definition a CRTExit string that returns the video attributes to normal. Unfortunately, many do not. If the user encounters this annoyance, he should redefine the TCAP to include an exit string that returns his video to the normal state as described above. Then, if the programmer has written his program as described in the last paragraph, at exit from the program, the video will be normal. It should be noted that the TCAPS supplied by Echelon, Inc. do not include this information in the reset string and it must be added with TCMAKE. Conclusion Source code is included in this library. Feel free to modify it. There is certainly room for improvement. However, the author would like to see what you have done. Please leave any messages, modifications, bug reports, etc. for me on Richard Jacobson's LilliPute ZNode in Chicago. The phone number for this excellent board is 312-649-1730, and you may leave messages there without being a member. However, as I said in the earlier version, his $40 membership fee is a bargain. Steve Cohen Nov. 30, 1985 Turbo-Pascal is a trademark of Borland International, Inc.