================================================================= Z3TCAP.DOC 01/01/90 ================================================================= SCAN uses cursor addressing and other terminal video functions extensively. For compatibility with ZCPR3, SCAN looks for the terminal control sequences it needs to create its screen displays in either a standard or a new extended 128 byte ZCPR3 Z3TCAP (Zcpr3 Terminal CAPabilities) area, either internally or, when SCAN is operating in a ZCPR3 environment, in the Z3TCAP in the ZCPR3 environment. The rest of the required terminal and system characteristics are taken from user-patchable internal locations or from other parts of the ZCPR3 environment. The installation utility SCANINST may be used to select and install a Z3TCAP terminal file for your terminal into SCAN from the selection of terminals in the file Z3TCAP.TCP. See SCANINST.DOC for more information. A standard or extended Z3TCAP file (TERMNAME.Z3T) matching your terminal may also be patched directly into SCAN, as explained below. The other required terminal and system characteristics must also be patched into SCAN, as described in SCAN.PAT. When operating in a ZCPR3 environment, SCAN first checks the internal Z3TCAP for a terminal definition. If none is found, it checks the Z3TCAP in the ZCPR3 environment. When operating in a non-ZCPR3 environment, only the internal Z3TCAP is checked. If no terminal definition can be located, SCAN can't operate properly and will quit with an error message. Delete Line And Insert Line Terminal Control Sequences ------------------------------------------------------ SCAN looks for optional delete line and insert line terminal control sequences in user-patchable internal locations or in the extended Z3TCAPin order to help speed up the display process when scrolling the display up and down one line. If SCAN can't find delete or insert line sequences in either place, it will provide the new displays by refreshing the whole screen, which takes slightly longer. Using a Z3TCAP containing delete and insert line sequences or patching them into SCAN will result in faster and more WordStar-like screen displays, but is not absolutely necessary. Other Terminal Control Sequences -------------------------------- Except for the cursor motion sequence, the terminal control sequences in the Z3TCAP are the normal sequences for your terminal found in your terminal manual, as shown in the examples below. It should be noted that in a Z3TCAP, a terminal control sequence has no fixed location or length, but must instead be provided in the specified order, as described in the section below on Z3TCAP Structure. Each sequence must be terminated with a 0. To keep the order straight, each sequence MUST consist of at least the terminating 0, even if the sequence is not being used! Cursor Motion Control Macro --------------------------- The cursor motion control sequence is a special case. It is a macro of sorts and must be properly interpreted by SCAN. Characters in the cursor motion sequence will be sent to the terminal exactly as they appear with the exception of the command lead-in character '%' and the command character that follows it. The command character following the '%' indicates the specific action required and will be interpreted by SCAN whenever the cursor motion sequence is called. There are eight cursor addressing commands supported, as shown below (commands may be in upper or lower case): %I Increment Row/Col by 1 (before D, 3, 2 or .) %D Send Row/Col as one, two or three ascii digits %2 Send Row/Col as two ascii digits %3 Send Row/Col as three ascii digits %. Send Row/Col as binary %R Send Col before Row (Default is to send Row before Col) %+ Add the next character to Row/Col and send it %N Send NULL (0h) to terminal \ Send the next character literally (The \ command permits sending a literal % or \ to the terminal. Use '\%' to send a percent sign or '\\' to send a backslash) Examples: The common TeleVideo cursor motion command is ESC = ROW COL where Row and Col are biased by the addition of the space character (20H). The TeleVideo cursor motion string is expressed in the Z3TCAP as: DB 1BH,'=' ; Lead-in string DB '%+ ' ; Send Row + space (20H) DB '%+ ' ; Send Col + space (20H) DB 0 ; String termination (not sent) or: DB 1BH,'=%+ %+ ',0 The ANSI (VT-100) cursor motion sequence is ESC [ ROW ; COL H where Row and Col are ASCII decimal digits beginning with 1 rather than 0, which requires the command '%I' to increment the Row and Col digits by 1. The ANSI cursor motion string is expressed in the Z3TCAP as: DB 1BH,'[' ; Lead in string DB '%I' ; Row and Col begin with 1 instead of 0 DB '%D' ; Send Row in decimal DB ';' ; Send delimiter DB '%D' ; Send Col in decimal DB 'H' ; Send trailing H DB 0 ; String termination (not sent) or: DB 1BH,'[%I%D;%DH',0 Z3TCAP Structure ---------------- This is not intended to be an exhaustive tutorial on the ZCPR3 Z3TCAP, but it should provide enough basic information to enable you to create or modify a Z3TCAP for your terminal that will work with SCAN. If you have problems, someone on your local bulletin board versed in ZCPR3 should be able to help you find a Z3TCAP (such as MYTERM.Z3T) file for your terminal, which can then be patched into SCAN with DDT as described below. You may also extract the following assembly code, edit it to include the control sequences for your terminal, assemble it to create a Z3TCAP that will work with SCAN, and use DDT to patch it into SCAN. You may also patch the sequences into SCAN's internal Z3TCAP directly. The SCAN internal Z3TCAP begins at 100H in the file, and at 200H when in memory (since the file starts at 100H). The sample Z3TCAP below contains the ANSI terminal control sequences and other sequences specific to the WYSE WY75 terminal. ;=============================================================== ; ESC EQU 27 ; Escape character Z3TCAP: DB 'WYSE-75 (ANSI) ' ; Name of terminal (14 chars) ; NOTE: ; ===== ; Control sequences marked with an '*' are not used by SCAN, but ; must consist of at least a binary 0 to mark their places. ; The following two bytes at TCAP+14 and TCAP+15 are configured ; as 16 binary flags. These flags may be refered to by ; applications programs that need more specific information on ; your terminal type and individual configuration than provided ; by the terminal control sequences below. For example, SCAN ; checks bits b2 and b3 of byte B15 to see whether your terminal ; provides automatic wrap or scroll. If they do, SCAN configures ; itself so that it doesn't use the last display column in its ; displays. Bit assignments present Zero as the 'normal' case ; and One as the 'exception' such that 'all zeroes' will perform ; the old fashioned way, as if the type bytes weren't there. ; ; Definitions for B15 (SCAN doesn't check the bits marked '*') ; are: ; ; *B15 b0 - (0) SO is Normal or Dim / (1) SO is Reverse Video ; *B15 b1 - (0) No Powerup wait / (1) Powerup wait (10 secs) ; B15 b2 - (0) Wrap at End-of-Line / (1) No wrap at EOL ; B15 b3 - (0) Scroll at End-of-Page / (1) No scroll at EOP ; *B15 b4 - (0) Non-ANSI Sequences / (1) ANSI Sequences used B14: DB 00000000B ; Flag bits not currently defined B15: DB 00011101B ; 8 Flag bits for WY-75. ; No single character arrow keys in ANSI, use WordStar diamond. DB 'E'-'@' ; * Cursor up DB 'X'-'@' ; * Cursor down DB 'D'-'@' ; * Cursor right DB 'S'-'@' ; * Cursor left ; Delays required by terminal control sequences (one byte each). DB 00 ; CL delay DB 00 ; CM delay DB 00 ; CE delay ; Terminal Control Strings start here. DB ESC,'[H',ESC,'[J',0 ; CL (Home cursor/clear screen) DB ESC,'[%i%d;%dH',0 ; CM (Cursor motion macro) DB ESC,'[K',0 ; CE (Clear cursor to end-of-line) ; There are several ways to set up your Z3TCAP so that your ; terminal gives you normal and standout video modes according to ; your preferences. The most common method is where the SO control ; string sets your standout mode (dim or reverse video) and SE ends ; it, giving you text in normal video and SO modes in dim or ; reverse video. If you normally use dim video as your default ; terminal mode and want to use normal video for a bright standout ; mode, you can have SO set normal video and SE set dim. ; Alternatively, you can start with normal video, use TI to set ; your terminal to dim, SO to set normal and SE to set dim, and TE ; to reset the terminal to normal video on exit, giving you text in ; dim video with SO modes in normal video, and leaving you with ; normal video on exit. DB ESC,'[7m',0 ; SO (Set standout ; - reverse video for WY-75) DB ESC,'[m',0 ; SE (End standout) DB 0 ; TI (Terminal initialization) DB 0 ; TE (Terminal deinitialization) ; Extensions to Original TCAP. DB ESC,'[M',0 ; LD (Line delete) DB ESC,'[L',0 ; LI (Line insert) DB ESC,'[%Dm',0 ;*; SA (Set attribute macro) DB 0 ;*; AT (Attribute string) DB ESC,'[J',0 ;*; CD (Clear from cursor to ; end of screen) ; Graphic extensions. ; The graphic extension definitions have not been finalized at ; this writing. They are not used by SCAN. ; Fill unused space with Nulls REPT 128-[$-Z3TCAP] DB 0 ENDM END Patching a Z3TCAP file into SCAN -------------------------------- You may use DDT, DDTZ, or a similar patching utility to patch a Z3TCAP file (named, for example, MYTERM.Z3T) into SCAN.COM: A0>ddt scan.com DDT VERS 2.2 NEXT PC 1880 0100 -imyterm.z3t ; Read in MYTERM.Z3T -r100 ; Read it in at 100 hex offset NEXT PC 1880 0100 -g0 ; Return to operating system A0>save 24 newscan.com ; Save 24 pages as NEWSCAN.COM and ; test it before renaming it ; to SCAN.COM. If you are using C.B. Falconer's DDTZ27 (highly recommended), you must use the 'N' and 'L' commands instead of DDT's 'I' and 'R'. A0>ddtz scan.com DDTZ v2.7M by CB Falconer. CPU=Z80 Next PC Save 1880 0100 24 -nmyterm.z3t ; Read in MYTERM.Z3T -l100 ; Read it in at 100 hex offset Next PC Save 1880 0100 24 -q ; Return to operating system A0>save 24 newscan.com ; Save 24 pages as NEWSCAN.COM and ; test it before renaming it ; to SCAN.COM. =================================================================