III. VLIB -- Video Terminal Interface Introduction . . . . . . . . . . . . . . . . . . . . . . 136 Using VLIB . . . . . . . . . . . . . . . . . . . . 136 Terminal Capabilities (TCAP) Extended Definition . 137 Basic VLIB Routines . . . . . . . . . . . . . . . . . . 143 Screen, Cursor, and Miscellaneous Routines . . . . 143 CLS, CLREOS, EREOL, AT, GOTOXY, DELLIN, INSLIN, ISCUR, VVERS Initialization . . . . . . . . . . . . . . . . . . 146 VIDINIT, Z3VINIT, VIDPTR (global) Print Routines . . . . . . . . . . . . . . . . . . 146 GXYMSG, VPRINT, VPSTR Standout Mode . . . . . . . . . . . . . . . . . . . 147 STNDOUT, STNDEND Terminal Initialization and De-Initialization . . . 148 TINIT, DINIT Graphics . . . . . . . . . . . . . . . . . . . . . . . . 149 Initialization . . . . . . . . . . . . . . . . . . 149 GZ3INIT, GRXON, GRXOFF Block Graphics . . . . . . . . . . . . . . . . . . 150 DRFULL, DRHASH Corners and Intersections . . . . . . . . . . . . . 150 ULEFT, URIGHT, LLEFT, LRIGHT, LTISEC, RTISEC, UISEC, LISEC, ISEC Horizontal and Vertical Bars . . . . . . . . . . . 151 DRHBAR, DRHORZ, ERAHORZ, GHBAR, ERAHBAR, DRVBAR, DRVERT, ERAVERT, GVBAR, ERAVBAR Box Drawing Routines . . . . . . . . . . . . . . . 155 DRFBOX, DRBOX, ERABOX, GFBOX, GBOX, GERBOX, CHKBOX Pull-Down Menus . . . . . . . . . . . . . . . . . . 156 SETPDM, CLRPDM, SELPDM, MCLS, PDMINI, ISPDM, SPDMCHR Reading the Terminal Screen . . . . . . . . . . . . 159 GETCUR, GETLIN VLIB -- Video Terminal Interface INTRODUCTION: VLIB is a library of routines originally designed by Richard Conn to support ZCPR3. Many changes have been incor porated in this version, including optimized code for the Z80 processor family, conversion to a table-driven mode for increased speed, and the addition of several new routines compatible with some of the GRWLIB and GRXLIB routines which were never widely adopted. Programs using routines from this library are able to enhance video displays with direct cursor addressing, video attributes, and new modes of operation such as pull-down menus in a portable manner among other Z-Systems without re-installation. Portability is achieved by accessing terminal descriptions con tained in the ZCPR3 TCAP, or compatible record. In most systems, the TCAP is stored in the second half of the ZCPR3 Environment Descriptor. USING VLIB: When writing programs to use VLIB, follow these steps: Z3EADR EQU 109H LD HL,(Z3EADR) ; get Environment address CALL Z3VINIT ; initialize ENVPTR and VIDPTR CALL GZ3INIT ; if you would use graphics CALL TINIT ; initialize the terminal .... ; your program CALL DINIT ; de-initialize the terminal .... ; housekeeping RET ; quit 1.Initialize pointers and routines. The two pointers needed are: - ENVPTR is the ZCPR3 Environment Descriptor address. - VIDPTR sets the Z3TCAP entry address. - If using graphics or pull-down menus, initialize that sybsystem as well. This routine returns flags that tell what new capabilities exist. 2.Call terminal initialization routine, TINIT. If your terminal uses DIM or reduced-intensity instead of reverse video, TINIT should set the default to the dim level as default, and use normal intensity for STNDOUT, with STNDEND returning to Dim. 3.Call VLIB routines within the program as desired. 4.Call terminal de-initialization routine, DINIT. If your terminal uses DIM or reduced-intensity attibutes instead of reverse or intensified video for Highlighting, DINIT should restore the terminal to normal intensity at exit. TERMINAL CAPABILITIES (TCAP) EXTENDED DEFINITION (as of February 3, 1990): The ZCPR3 TCAP is a 128-byte area positioned immedi ately after the Environment Descriptor. The configuration has been changed from the original descriptions contained in Richard Conn's book, ZCPR3: The Manual. The layout here is designed for backward compatibility with the original scheme while adding extensions to accomodate rudamentary business graphics and pull- down menus described in Dennis Wright's GRXLIB and portions of GRWLIB. Offsets mentioned in this description are from the base of the TCAP. offset item description 0 Terminal Name 13 characters, alphanumeric. The first character must not be a space. A lead ing space means uninstalled TCAP. By convention, a terminal name is unique in its first eight characters and the name is terminated with a space. 13 Offset to GOELD entry 14 High Terminal Characteristics Bit 7 is set (80h) to indentify extended TCAP. 15 Low Terminal Characteristics One byte indicating terminal details: b0 - type of standout mode (0 = dim; 1 = reverse). b1 - terminal delay at powerup (0 = no delay; 1 = 10 seconds). b2 - screen wraps on write in last col umn (0 = no; 1 = yes). b3 - screen scrolls if last row and column are written (0 = yes; 1 = no). b4 - ANSI terminal (0 = no, ASCII; 1 = yes, ANSI). The following four bytes are for single-byte cursor movement codes from the terminal. If your terminal has no independant cursor movement keys, or implements cursor movement with multi- byte sequences, use any convenient single-key sequence you de sire. The familiar WordStar "diamond" comprised of ^E (up), ^X (down), ^D (right) and ^S (left) is commonly used. 16 Cursor Up Cursor up code from terminal (^E). 17 Cursor Down Cursor down code from terminal (^X). 18 Cursor Right Cursor right code from terminal (^D). 19 Cursor Left Cursor left code from terminal (^S). Some terminals need delays to perform certain functions. This may be more important as interface speeds increase. Delays are in milliseconds. Consult your terminal manual for the correct values to insert. 20 Clear Screen Delay in milliseconds (0 to 255). 21 Move Cursor Delay in milliseconds (0 to 255). 22 Clear to End-of-Line Delay in milliseconds (0 to 255). Beginning at offset 23 from the beginning of the TCAP, a sequence of NUL-terminated strings define the command strings needed to make the terminal respond as desired. If particular features are not implemented or not needed by your terminal, a single NUL (binary 0) disables that feature. 23 Clear Screen (CL) Clear screen and home cursor. Cursor Movement (CM) Parsed string for cursor positioning. See ZCPR3: The Manual for details. "%N" string added to send binary 0 to termi nal. Clear to End-of-Line (CE) Clear from cursor position to the end of the current line. Cursor stays in cur rent place. Standout Begin (SO) Enter standout mode. If terminal uses dim or reduced intensity, the initiali zation string (TI below) should set to reduced intensity, and this function sets normal intensity. Standout End (SE) End Standout mode. If you use dim or reduced intensity with normal for "Standout", this restores the dim mode. Initialize Terminal (TI) Initialize the terminal. See notes for suggestions on dim and reduced intensity above. De-initialize Terminal (TE) Restore terminal to normal mode. See above notes. Delete Line (LD) Delete line on which the cursor resides and move lines below it up by one. Bottom line is blank. Insert Line (LI) Insert blank line before the one on which the cursor is positioned, and move lines below down one. Cursor moves to beginning of the new blank line. Clear to End-of-Screen (CD) Clear screen from current cursor posi tion to the end-of-screen. Set Attributes (SA) Set character attributes based on AT, below. Attributes (AT) Attribute characters for this terminal; usually normal, blink, reverse, and underscore. Read Cursor Position (RC) Return current cursor position. Read Terminal Line (RL) Read current line up to cursor. The following definitions implement portions of the GRXLIB and GRWLIB functionality, but in different TCAP locations. Graphics Delay (GOELD) Delay for graphics on/off. Use greater of the two delay times in milliseconds. Values of 0 to 255 are acceptable. Graphics Mode On (GO) Set terminal to graphics mode. End Graphics Mode (GE) Restore terminal to normal alphanumeric mode. Cursor Off (CDO) Disable cursor display. Needed for pull-down menus. Cursor On (CDE) Enable cursor display. Needed for pull- down menus. Several graphics strings are needed to implement the desired level of functionality. Each of these is needed in the specified order. The terminal should first be placed in the graphics mode, then the desired string sent. If strings for all terminals are only a single character, this may be reduced to a character array in the future. Upper-Left Corner (GULC) Upper-Right Corner (GURC) Lower-Left Corner (GLLC) Lower-Right Corner (GLRC) Horizontal Line (GHL) Vertical Line (GVL) Solid (Full) Block (GFB) Hashed Block (GHB) Upper Intersect (GUI) Lower Intersect (GLI) Intersection (GIS) Right Intersect (GRTI) Left Intersect (GLTI) The remainder of the TCAP should be filled with binary zeros to properly handle future additions. Example: ; Z3TCAP: NZWYS60.Z80 ; Author: Joe Wright ; Date: 12 October 87 ; Version: 1.0 ; VERSION: 2.2 3 February 90 ; ; Moved the CD (clear to end of screen) string back after LI string. ; Define B13 as offset from NZTCAP to GOELD. ; VERSION: 2.1 19 January 90 ; Added Read Cursor and Read Line functions. ; Graphics characters now in a table instead of individual strings. ; VERSION: 2.0 12 December 89 ; Modified for new VLIB4 graphics and for new SETATT and SETATR routines. ; The SA: macro string is modified for the routines and a new string, ; AT: is added to contain the four main attributes for this terminal: ; Normal, Blink, Reverse, Underscore ; Extended Termcap Data for NZ ; This is the proposed Termcap Data for the New Z-System. ; It more fully describes the terminal and its capabilities. ESC EQU 27 ; ASCII escape character ; I have adopted the convention that a terminal name is terminated ; with a space character, therefore no spaces within the name. ; Also that the terminal name is unique in the first eight characters. ; NZTCAP: DB 'WYSE-60D' ; name of terminal (13 chars) ; ; The Graphics section is no longer fixed so we must provide an ; offset to it. One byte is sufficient for a two-record TCAP. ; B13: DB GOELD-NZTCAP ; offset to GOELD ; ; Bit 7 of B14 indicates the new Extended TCAP. Bits 6-0 are undefined. ; B14: DB 10000000B ; extended TCAP ; ; It is often desirable to differentiate terminals with other than ; their commands. For example TeleVideo 955 has the same command ; set as Wyse 60 but takes less time to initialize (reset). ; ; 16 bits are now reserved for indicating terminal characteristics ; which cannot be known from the strings. I have defined five ; of these bits for my own purposes. ; ; B15 b0 Standout 0 = half-intensity, 1 = reverse video ; B15 b1 Power Up Delay 0 = none, 1 = 10 second delay ; B15 b2 No Wrap 0 = line wrap, 1 = no wrap ; B15 b3 No Scroll 0 = scroll, 1 = no scroll ; B15 b4 ANSI 0 = ASCII, 1 = ANSI ; B15: DB 00000111B ; power up delay ; DB 'K'-'@' ; cursor up DB 'J'-'@' ; cursor down DB 'L'-'@' ; cursor right DB 'H'-'@' ; cursor left DB 00 ; clear screen (CL) delay DB 00 ; cursor position (CM) delay DB 00 ; clear to EOS (CE) delay ; Strings start here. CL: DB ESC,'+',0 ; string to clear, home cursor 0 CM: DB ESC,'=%+ %+ ',0 ; string to position cursor 1 CE: DB ESC,'T',0 ; string to clear to end-of-line 2 SO: DB ESC,')',0 ; string to go to highlight video 3 SE: DB ESC,'(',0 ; string to return normal video 4 TI: DB 0 ; string to initialize terminal 5 TE: DB ESC,'(',0 ; string to de-initialize term 6 ; ; Extensions to Standard Z3TCAP ; LD: DB ESC,'M',0 ; string to delete line 7 LI: DB ESC,'L',0 ; string to insert line 8 CD: DB ESC,'J',0 ; string to clear to EOS 9 ; ; Set attribute strings for normal, blink, reverse, underline. ; SA: DB ESC,'G%+0',0 ; set attributes prefix 10 AT: DB '0248',0 ; attributes 11 ; ; These two allow reading the terminal's screen. ; RC: DB ESC,'?',0 ; read current cursor position 12 RL: DB ESC,'6',0 ; read line until cursor 13 ; ; Graphics start here. Wyse-60 goes graphic with bit 7 set. ; GOELD: DB 0 ; graphics on/off delay 0 ; ; Graphics strings offset from delay value. ; GO: DB 0 ; string to turn on graphics 1 GE: DB 0 ; string to turn off graphics 2 CDO: DB ESC,'`0',0 ; string to turn off cursor 3 CDE: DB ESC,'`1',0 ; string to enable cursor 4 GULC: DB 'Z'+80h ; upper left corner [*] 5 GURC: DB '?'+80h ; upper right corner [*] 6 GLLC: DB '@'+80h ; lower left corner [*] 7 GLRC: DB 'Y'+80h ; lower right corner [*] 8 GHL: DB 'D'+80h ; horizontal line [-] 9 GVL: DB '3'+80h ; vertical line [|] 10 GFB: DB '['+80h ; full block string [*] 11 GHB: DB '2'+80h ; hashed block string [#] 12 GUI: DB 'B'+80h ; upper intersection [+] 13 GLI: DB 'A'+80h ; lower intersection [+] 14 GIS: DB 'E'+80h ; intersection [+] 15 GRTI: DB '4'+80h ; right intersection [+] 16 GLTI: DB 'C'+80h ; left intersection [+] 17 ; ; Fill unused space with nulls. ; REPT 128-[$-Z3TCAP] DB 0 ENDM ; END ;------------- End of Sample NZ TermCap ------------- BASIC VLIB ROUTINES: SCREEN, CURSOR, AND MISCELLANEOUS ROUTINES: Routine: CLS Function: Clear entire screen and home cursor Entry: None Exit: A <> 0 zero flag reset (NZ) if screen cleared A = 0, zero flag set (Z) if function not available Affected: AF Usage: Most often used to provide initial entry condi tions, or to divide functions of a program for ergonomic reasons. Routine: CLREOS Function: Clear from current cursor position to end-of- screen leaving cursor in present position Entry: None Exit: A <> 0 zero flag reset (NZ) if screen cleared A = 0, zero set (Z) if function not available Affected: AF Usage: Removes transient information from the lower part of a screen while retaining information on the upper part. Routine: EREOL Function: Erase line from cursor position to end-of-line Entry: None Exit: A <> 0 zero flag reset (NZ) if line erased A = 0, zero flag set (Z) if function not available Affected: AF Usage: Insures that remaining information on a line is cleared Routine: AT Function: Position cursor from in-line code coordinate posi tions Entry: None; address of XY coordinates are on stack top Exit: None; execution resumes at instruction after XY coordinates Affected: None Usage: Positions the cursor at row and column address pointed to by the return address. Used where the desired row and column position is known by the program, and does not change with program flow. See GOTOXY for positioning routine that may be varied within a program. There is no checking of terminal limits in the environment. Example: EXT AT ; declare the routine ... ; ..other parts of program CALL AT ; call the positioning routine DEFB ROW,COL ; ..row and column (1,1 is home) ... ; program flow resumes here Routine: GOTOXY Function: Position cursor from row and column data in regis ters Entry: HL = desired cursor position (H=row, L=column) Exit: A <> 0 zero flag reset (NZ) if cursor positioned A = 0, zero set (Z) if function not available Affected: AF Usage: Position the cursor at row (in register H) and column (in L). The home position (top left cor ner) is H=1 and L=1. When the desired cursor position is fixed, you may want to use AT (above). Bits 1 and 2 of the new mode byte in the TCAP should be sensed before positioning to last Column in a row to avoid screen wrap/scroll problems. Example: EXT GOTOXY ; declare the routine ... ; ..intervening code LD HL,10*256+3 ; load coords (row 10, col 3) CALL GOTOXY ; try to position the cursor JR NZ,MOVOK ; ..jump if successful ... ; else try something else Routine: SETATR Function: Set coded attributes Entry: A = attribute code (0..7) Exit: A = 0FFh, zero flag clear (NZ) if attribute is available A = 0, zero flag set (Z) if attribute is not available Affected: AF Usage: Attribute codes are: 0 = normal (all attributes off) 1 = blink 2 = reverse video 3 = blink and reverse video 4 = underscore 5 = blink and underscore 6 = underscore and reverse video 7 = blink, underscore, and reverse video Routine: SETATT Function: Set attributes Entry: H = first value L = second value Exit: A <> 0, zero flag clear (NZ) if function is available A = 0, zero flag set (Z) if function is not available Affected: AF Usage: Uses the same parser as GOTOXY, so values may be passed to it as they are to the cursor movement string. Refer to ZCPR3: The Manual for CM string programming and to your particular terminal manual for attribute values. Also, see SETATR descrip tion above. You may not need SETATT at all. Routine: DELLIN Function: Delete the currently addressed line Entry: None Exit: A <> 0, zero flag clear (NZ) if action completed A = 0, zero set (Z) if function not defined Affected: AF Usage: Enhances screen editor functions under ZCPR3 with appropriate TERMCAP definitions. Example: See INSLIN below. Routine: INSLIN Function: Insert a new line at the current cursor position Entry: None Exit: A <> 0, zero flag clear (NZ) if action completed A = 0, zero set (Z) if function not defined Affected: AF Usage: Enhances screen editor functions under ZCPR3 with appropriate TERMCAP definitions. Example: EXT DELLIN,INSLIN ; declare the routines ... ; ..pos'n cursor to ... ; ..desired line CALL DELLIN ; kill it! JR Z,NOTDONE ; ..jump if not defined ... ; ..position to new line pos'n CALL INSLIN ; new line here, ; ..push others down JR Z,NOINSL ; ..jump if not defined ... ; else continue on Routine: ISCUR Function: Test character for cursor movement key Entry: A = character to test Exit: A = 1..4 (1=up, 2=down, 3=right, 4=left), zero clear (NZ) if character is cursor key from TCAP or WordStar cursor key A = character, zero set (Z) if not cursor key Affected: AF Usage: Determines if a character is a command to move the cursor up, down, right, or left. Both single character commands from the extended TCAP, as well as WordStar ^E, ^X, ^D, and ^S are checked. Example: EXT ISCUR,CIN ; declare some routines ... ; ..preceding code CALL CIN ; get char from keyboard CALL ISCUR ; is it a cursor key? JR Z,NOCUR ; ..jump if not a cursor key Routine: VVERS Function: Return the VLIB version number Entry: None Exit: HL = VLIB version number (H=major, L=minor) Affected: HL Usage: Most often called for debugging or documentation purposes to include the VLIB library version num ber linked in programs. INITIALIZATION: Routine: VIDINIT Function: Initialize the VLIB routines to a specified TCAP Entry: HL = address of a Z3 formatted TCAP Exit: None; but VIDPTR global initialized to TCAP and VLIB set Affected: None Usage: Provides the ability to use a TCAP other than that provided in the ZCPR3 environment. For added safety in programming, you should also set the Z3LIB variable ENVPTR to an address pointing to an ENV construct which provides terminal parameters to some routines. Example: EXT VIDINIT ; declare the routine ... ; ..program initialization LD HL,(Z3EADR) ; load ENV address LD DE,80H ; offset to TCAP portion ADD HL,DE CALL VIDINIT ; ..and initialize VLIB ... ; carry on with program Routine: Z3VINIT Function: Initialize Z3LIB and VLIB routines for use Entry: HL = address of a ZCPR3 environment descriptor Exit: None Affected: None Usage: Combines the functions of the Z3LIB routine Z3INIT and VIDINIT covered above. It assumes that the TCAP begins 80h (128) bytes after the specified environment pointer passed in HL. Example: EXT Z3VINIT ; declare the routine ... ; ..initial program code LD HL,(Z3EADR) ; get the environment address CALL Z3VINIT ; ..set ENVPTR and init VLIB ... ; carry on! PRINT ROUTINES: Routine: GXYMSG Function: Position cursor and print text with highlighting Entry: None; address of XY coordinates followed by text on stack top Exit: None; execution resumes after text terminating NUL Affected: None Usage: Prints a text message at a pre-defined location on the terminal screen. It is analagous to position ing the cursor with AT followed by a string print with VPRINT. Standout and standend attributes are recognized with binary 1 and 2 respectively. There is no checking of terminal limits in the environment. Example: EXT GXYMSG ; declare the routine ... ; ..intervening code CALL GXYMSG ; print as... DEFB 2,15 ; position to row 2, column 15 DEFB 1,'Hi',2 ; ..and print this message DEFB ' There!',0 ; ...highlighting "Hi" ... ; execution resumes here Routine: VPRINT Function: Print NUL-terminated inline text with highlighting Entry: None; the string starting address in on stack top Exit: None; execution resumes after string terminator Affected: None Usage: Prints a text string from inline code with high lighting ability by enabling STNDOUT mode with a binary 1, and resuming normal print via STNDEND with a binary 2. This is VLIB's version of the SYSLIB routine PRINT. Example: EXT VPRINT ; declare the routine ... ; ..intervening code CALL VPRINT ; print the following line DEFB 2,'Hi',1 ; ..hilighting "Hi" and DEFB ' There',0 ; ...the remainder in normal ... ; execution resumes here Routine: VPSTR Function: Print a NUL-terminated message with highlighting Entry: HL = address of NUL-terminated string to print Exit: HL = points to byte after terminating NUL A = 0, zero flag set (Z) Affected: AF, HL Usage: Prints text messages with highlighting capabili ties provided by STNDOUT/STNDEND from locations other than the executing code. It is the VLIB corollary of PSTR in SYSLIB. STANDOUT MODE: Routine: STNDOUT Function: Begin standout mode. Entry: None Exit: A <> 0 zero flag reset (NZ) if standout mode entered A = 0, zero flag set (Z) if not available Affected: AF Usage: For terminals with reverse video, this routine will start that mode. For those with dim or re duced video, use TINIT to set the terminal to that mode for normal print, and STNDOUT to place in normal mode. DINIT should then reverse on exit. This mode is used to provide visual attributes for better man-machine interface. Caution: Do not reposition the cursor or issue carriage returns or line feeds while the standout mode is in effect since unknown effects can occur on some types of terminals. Use STNDEND to disable this mode. Routine: STNDEND Function: End standout mode, return to normal screen display Entry: None Exit: A <> 0 zero flag reset (NZ) if standout mode ended A = 0, zero set (Z) if function not available Affected: AF Usage: Reverses the mode set by STNDOUT above. See notes for STNDOUT. TERMINAL INITIALIZATION AND DE-INITIALIZATION: Routine: TINIT Function: Initialize terminal for use with VLIB routines Entry: None Exit: None Affected: None Usage: When writing programs based on VLIB routines, TINIT should be called early in the program flow. If you are using video attributes to provide high lighting with STNDOUT/STNDEND and your terminal only provides a dim or reduced-intensity attri bute, TINIT should set the normal mode to the dim or reduced mode, and STNDOUT used for normal in tensity print. The corresponding DINIT should be used to restore normal mode just priot to program exit. Routine: DINIT Function: De-initialize the terminal; return to normal Entry: None Exit: None Affected: None Usage: Normally used to restore terminal default condi tions upon program termination. See usage notes for TINIT above. Example: EXT TINIT,DINIT ; declare the routines ... ; ..initial program code CALL TINIT ; initialize the terminal ... ; ..main program code CALL DINIT ; do just before exiting pgm JP EXIT ; ..and return to normal GRAPHICS (January 22, 1990): These extensions to VLIB incorpo rate many of the interfaces of the original Echelon/Dennis Wright GRXLIB and GRWLIB, and provide additional functionality for easi er interfacing. They require the extended TCAP definitions in order to work. INITIALIZATION: Routine: GZ3INIT Function: Initialize Z3LIB and VLIB, return TCAP flags Entry: HL = pointer to Z3 environment descriptor Exit: A = bitmap of capabilities, zero set on results: b0 = 1 if delete/insert line present, 0 if absent b1 = 1 if clear to EOS present, 0 if absent b2 = 1 if graphics on/off present, 0 if absent b3 = 1 if 13 graphics characters exist, 0 if any absent Affected: AF Usage: Calls Z3VINIT and therefore may be substituted for it to set the Z3LIB ENVPTR and initialize VLIB routines. Flag bits are returned to show whether the TCAP extended functions are present. Routine: GRXON Function: Place terminal in graphics mode Entry: None Exit: A <> 0, zero flag clear (NZ) if operation successful A = 0, zero flag set (Z) if not implemented Affected: AF Usage: Controls the graphics capabilities of the terminal as defined in the extended TCAP. If this routine is not implemented, any calls to graphic routines will print the defined strings in normal alphanu meric mode. Example: See GRXOFF below. Routine: GRXOFF Function: Return terminal to alphanumeric mode Entry: None Exit: A <> 0, zero flag clear (NZ) if operation successful A = 0, zero flag set (Z) if not implemented Affected: AF Usage: Turns off the graphics capabilites of your termi nal as defined in the extended TCAP. Example: EXT GRXON,GRXOFF ; define the routines ... ; ..do VIDINIT/Z3VINIT up here CALL GRXON ; put terminal in graphics mode JR Z,NOGRAF ; .jump if no graphics mode ... ; ..else print in graphics CALL GRXOFF ; return to alphanumeric mode Routine: CURON, CUROFF Function: Turn display of cursor on or off Entry: None Exit: A <> 0, zero flag clear (NZ) if operation successful A = 0, zero flag set (Z) if not implemented Affected: AF Usage: These routines allow inhibiting the cursor during graphic displays to avoid the distraction of the cursor jumping around the screen. Turning the cursor off will supposedly also speed up some terminal operations. CUROFF turns off the cursor, while CURON turns it back on. BLOCK GRAPHICS: Routines: DRFULL, DRHASH Function: Print a graphics block character Entry: None Exit: A <> 0, zero flag clear (NZ) if character printed A = 0, zero flag set (Z) if not implemented Affected: AF Usage: These routines are used by several of the added routines (for example, the line draw routines) to print full-block graphics characters to the screen. DRFULL prints a full graphics block char acter; DRHASH prints a hashed or shaded graphics block character. Example: EXT DRFULL,DRHASH ; declare the routines ... ; ..other code including Z3INIT CALL DRFULL ; print full block graphics CALL DRHASH ; ..and hashed (shaded) block ... ; carry on! CORNERS AND INTERSECTIONS: Routines: ULEFT, URIGHT, LLEFT, LRIGHT Function: Print corner graphics character -- ULEFT upper- left, URIGHT upper-right, LLEFT lower-left, LRIGHT lower-right Entry: None Exit: A <> 0, zero flag clear (NZ) if character printed A = 0, zero flag set (Z) if not implemented Affected: AF Usage: Prints the respective corner graphics characters. Used in the box drawing routine described below. If you have no graphics capability, use characters in parentheses in TCAP strings. Routines: LTISEC, RTISEC, UISEC, LISEC, ISEC Function: Print intersection graphics character -- LTISEC left, RTISEC right, UISEC upper, LISEC lower, ISEC intersection Entry: None Exit: A <> 0, zero flag clear (NZ) if character printed A = 0, zero flag set (Z) if not implemented Affected: AF Usage: As with the corner routines, these print the re spective graphics character for their function. Define the TCAP string for these functions to be the ASCII character in parentheses if you have no graphics capability. Example: EXT LTISEC,RTISEC,UISEC,LISEC,ISEC ; declare routines ... ; ..preceding code CALL LTISEC ; (or RTISEC, etc) HORIZONTAL AND VERTICAL BARS: Routine: DRHBAR Function: Print heavy horizontal bar with the graphics full or hashed block character from inline code Entry: None; the top of stack points to parameters Exit: None; execution resumes after the parameters Affected: None Usage: Used where fixed parameters exist. For variable bar parameters, use GHBAR which executes the same from parameters passed in registers. Parameters for DRHBAR are: call drhbar defb Type ; 1 = Full Block, 2 = Hashed Block defb Row ; 1 = Top Row on screen defb Column ; 1 = Left Most Column on screen defb Length ; Number of characters to print defb Direc ; 0 = Left-to-Right, 1 = R-to-L When bars are specified as right-to-left, the left margin is validated for exceeding the left margin, and only the valid portion is printed. Actual printing is always left-to-right. Example: EXT DRHBAR ; declare the routine ... ; ..preceding code CALL DRHBAR ; draw heavy bar at: DEFB 1,2,10,20,0 ; full, row 2, col 10, len 20 ; ..print left-to-right ... ; execution resumes here Routines: DRHORZ, ERAHORZ Function: Print or erase horizontal line from inline parame ters Entry: None; the top of stack points to parameters Exit: None; execution resumes after the parameters Affected: None Usage: DRHORZ draws a thin graphics horizontal line, and ERAHORZ erases a line by overwriting it with spaces. They are used where fixed parameters exist. For variable bar parameters, use GHBAR and ERAHBAR which execute the same from parameters passed in registers. Parameters are: call drhorz [or erahorz] defb Row ; 1 = top row on screen defb Column ; 1 = left most column on screen defb Length ; number of characters to print defb Direc ; 0 = left-to-right, 1 = right-to-left When lines are specified as right-to-left, the left margin is validated for exceeding the left margin, and only the valid portion is printed. Actual printing is always left-to-right. Example: EXT DRHORZ,ERAHORZ ; declare the routines ... ; ..preceding code CALL DRHORZ ; draw horizontal line at: DEFB 2,10,20,0 ; row 2, col 10, length 20 ; ..print left-to-right ... ; execution resumes here CALL ERAHORZ ; erase the horizontal line at: DEFB 5,60,20,1 ; row 5, col 60, length 20 ; ..from right-to-left Routine: GHBAR Function: Print a graphics horizontal bar/line from parame ters in registers Entry: A = bar type (0=line, 1=full block, 2=hashed block) B = length of bar C = print direction (0=left-to-right,1=right-to-left) H = starting row (1=top of screen) L = starting column (1=leftmost column) Exit: None; registers are meaningless, the bar is printed Affected: AF, BC, HL Usage: Used where horizontal bar parameters are calculat ed by a program, or not known at assembly time. Example (see also note in DRHORZ example): EXT GHBAR ; declare the routine ... ; ..preceding code LD A,2 ; print bar w/hashed block char LD HL,10*256+25 ; .start at row 10, column 25 LD BC,15*256+0 ; ..length of 15, left-to-right CALL GHBAR ; print it graphically Routine: ERAHBAR Function: Erase horizontal bar from register parameters Entry: B = length of bar C = print direction (0=left-to-right,1=right-to-left) H = starting row (1=top of screen) L = starting column (1=leftmost column) Exit: None; registers are meaningless, the bar is erased Affected: AF, BC, HL Usage: Erases a horizontal bar by overwriting with spaces where parameters are calculated by a program, or are not known at assembly time. Example (see also note in ERAHORZ example): EXT ERAHBAR ; declare the routine ... ; ..preceding code LD HL,8*256+50 ; .start at row 8, column 50 LD BC,40*256+1 ; ..length of 40, right-to-left CALL ERAHBAR ; erase it Routine: DRVBAR Function: Draw heavy vertical bar from parameters passed on stack Entry: None; parameters are addressed by top of stack Exit: None; execution resumes after parameters, bar is printed Affected: None Usage: Used when a heavy fixed-location bar is needed, or bar location and size are known at assembly time. Bar characters may be full or hashed block, either single or double width. See GVBAR for the same functions from parameters passed in registers. Parameters are: call drvbar ; call routine passing params addr defb Type ; 1=solid single-wide, 2=solid ; double-wide, 3=hashed single- ; wide, 4=hashed double-wide defb Row ; starting row (1=top row) defb Column ; starting column (1=leftmost col) defb Length ; number of columns in bar defb Dir ; 0=top-to-bottom, 1=bottom-to-top When a bar is drawn from bottom-to-top, checks are made for exceeding the top of screen (row 1). The length is adjusted if so to print only the part on screen. Bars are always printed top-to-bottom. Example: EXT DRVBAR ; declare the routine ... ; ..preceding code CALL DRVBAR ; draw vertical bar as: DEFB 2,20,10,5,0 ; solid single-width, row 20, ; ..col 10, 5 long, ; ..top-to-bottom ... ; execution resumes here Routines: DRVERT, ERAVERT Function: Print or erase graphics vertical line from inline parameters Entry: None; the top of stack points to parameters Exit: None; execution resumes after the parameters Affected: None Usage: DRVERT prints a vertical line and ERAVERT erases a vertical line from inline parameters. These rou tines are used where fixed parameters exist. For variable bar parameters use GVBAR and ERAVBAR, which execute the same from parameters passed in registers. Parameters are: call drvert [or eravert] defb Row ; 1=top row on screen defb Column ; 1=leftmost column on screen defb Length ; number of characters to print defb Direc ; 0=top-to-bottom, 1=bottom-to-top When a bar is drawn from bottom-to-top, checks are made for exceeding the top of screen (row 1). The length is adjusted if so to print only the part on screen. Bars are always printed top-to-bottom. Example: EXT DRVERT,ERAVERT ; declare the routines ... ; ..preceding code CALL DRVERT ; draw vertical line at: DEFB 2,10,15,0 ; row 2, col 10, length 15 ; ..print top-to-bottom ... ; execution resumes here CALL ERAVERT ; erase the vertical line at: DEFB 22,60,20,1 ; row 22, col 60, length 20 ; ..from bottom-to-top Routine: GVBAR Function: Print graphics vertical bar/line from register parameters Entry: A = bar type (0=line, 1=single full block, 2=dou ble full block, 3=single hash block, 4=double hash block) B = length of bar (number of characters) C = print direction (0=top-to-bottom,1=bottom-to-top) H = starting row (1=top of screen) L = starting column (1=leftmost column) Exit: None; registers are meaningless, the bar is printed Affected: AF, BC, HL Usage: Prints calculated vertical bars from programs where parameters are not known at assembly time. Example (see note in DRVERT example): EXT GVBAR ; declare the routine ... ; ..preceding code LD A,2 ; double bar w/full block char LD HL,22*256+60 ; .start at row 22, column 60 LD BC,15*256+1 ; ..length of 15, bottom-to-top CALL GVBAR ; print it graphically Routine: ERAVBAR Function: Erase vertical bar from register parameters Entry: B = length of bar (number of characters) C = print direction (0=top-to-bottom, 1=bottom-to- top) H = starting row (1=top of screen) L = starting column (1=leftmost column) Exit: None; registers are meaningless, the bar is erased Affected: AF, BC, HL Usage: Erases a vertical bar by overwriting with spaces where parameters are calculated by a program, or are not known at assembly time. Do twice for double-width bar. Example (see note in ERAVERT example): EXT ERAVBAR ; declare the routine ... ; ..preceding code LD HL,8*256+10 ; .start at row 8, column 10 LD BC,15*256+0 ; ..length of 15, top-to-bottom CALL ERAVBAR ; erase it BOX DRAWING ROUTINES: Routines: DRFBOX, DRBOX, ERABOX Function: Draw and erase graphics character box from inline parameters Entry: None; the top of stack addresses box parameters Exit: None; execution resumes at byte following the parameters Affected: None Usage: DRFBOX draws graphics boxes framed with full block characters, DRBOX draws graphics boxes framed with normal graphics line and corner characters, and ERABOX erases a box. Boxes are drawn from top- left to bottom right, and erased by overwriting with spaces. Parameters are: call drfbox ; (or drbox or erabox) defb Row ; starting row (1 = top row) defb Column ; starting column defb Height ; height of box in character rows defb Width ; width of box in character positions Example: EXT DRFBOX,DRBOX,ERABOX ; declare routines ... ; ..preceding code CALL DRBOX ; draw a normal box DEFB 5,5,10,20 ; row 5, col 5, 10 spaces high ; ..and 20 spaces wide CALL DRFBOX ; draw box framed w/solid blks DEFB 10,30,6,25 ; row 10, col 30, 6 spaces high ; ..and 25 wide CALL ERABOX ; erase the first box DEFB 5,5,10,20 ... ; ..and continue Routines: GFBOX, GBOX, GERBOX Function: Draw or erase graphics character box from register parameters Entry: B = width of box in character spaces C = height of box in lines H = starting row (top left corner, 1=top row) L = starting column (top left corner, 1=leftmost column) Exit: None; registers indeterminate, box drawn Affected: AF, BC, HL Usage: GFBOX draws graphics box framed with solid block characters, GBOX draws graphic box framed with line and corner graphics characters, GERBOX erases box by overwriting with spaces. These routines implement the same functions as the previous box routines, but derive their parameters from CPU registers. Use these routines for calculated values or for parameters not known at assembly. Example: EXT GFBOX,GBOX,GERBOX ; declare the routines ... ; ..preceding code LD BC,30*256+10 ; 30 spaces wide, 10 high LD HL,10*256+20 ; ..at row 10, col 20 CALL GBOX ; draw it! Routine: CHKBOX Function: Check and adjust box parameters Entry: B = width of box in character spaces C = height of box in lines H = starting row (top left corner, 1=top row) L = starting column (top left corner, 1=leftmost column) Exit: A <> 0, zero clear (NZ) if box drawable, parame ters set A = 0, zero flag clear (Z) if box not drawable Affected: AF, and maybe BC and HL if parameters are adjusted Usage: This routine is used internally to adjust box dimensions to screen size reflected in the CRT data in the Z3 environment. Starting row or col umn exceeding the maximum height or width will cause the error status. It may be used after setting registers for a GRBOX or GRFBOX call to save the actual box parameters which will be drawn. Example: EXT CHKBOX,GBOX ; declare the routines ... ; ..set up for box draw CALL CHKBOX ; validate the dimen/location JR Z,NOGOOD ; ..jump if can't draw this one LD (HITWID),BC ; else save width/height LD (ROWCOL),HL ; ..and row/col start loc'n CALL GBOX ; draw this box ... PULL-DOWN MENUS: Routine: SETPDM Function: Set select menu and item menu bar for pull-down menu from inline data Entry: None; top of stack points to menu data area Exit: A <> 0, zero flag clear (NZ) if pull-down menu OK A = 0, zero set (Z) if error or not supported Affected: AF Usage: SETPDM uses inline parameters and establishes a single menu selection, and set information for the pull-down item selection bar. The number of menu selections is determined by screen width, and up to ten selections may be supported. Menu data descriptions are ASCII text strings with binary values of one to ten (only 1-5 currently used) to denote special features and fields. The menu data area is structured as follows: Menu number (byte) in the range of 1..10 Menu name (string) terminated by binary 1 Item selection strings terminated by binary 3's Optional fields may be interspersed with selection strings: Sub-header strings terminated by binary 2's Separator lines indicated by binary 4 (byte) Blank lines indicated by binary 5 (byte) Example: EXT SETPDM ; declare the routine ... ; ..call PDMINI up here CALL SETPDM DEFB 1 ; menu number (1..10) DEFB 'MenuName',1 ; name on menu bar DEFB 'Subheader',2 ; optional subheader(s) DEFB 4 ; optional separator line DEFB 'Item 1',3 ; first item name DEFB 5 ; optional blank line DEFB 'Item 2',3 ; second item name DEFB 0 ; end of menu item list ... ; ..execution resumes here Routine: SETPDR Function: Set select menu and item menu bar for pull-down menu from register data Entry: HL = pointer to menu data area Exit: A <> 0, zero flag clear (NZ) if pull-down menu OK A = 0, zero set (Z) if error or not supported HL = address of byte after terminating NUL Affected: AF, HL Usage: SETPDR uses a separate data area pointed to by HL and establishes a single menu selection, and set information for the pull-down item selection bar. The number of menu selections is determined by screen width, and up to ten selections may be supported. Menu data descriptions are ASCII text strings with binary values of one to ten (only 1-5 currently used) to denote special features and fields. The menu data area is structured as follows: Menu number (byte) in the range of 1..10 Menu name (string) terminated by binary 1 Item selection strings terminated by binary 3's Optional fields may be interspersed with selection strings: Sub-header strings terminated by binary 2's Separator lines indicated by binary 4 (byte) Blank lines indicated by binary 5 (byte) Example: See SETPDM above. Routine: CLRPDM Function: Clear a pull-down menu from the menu selection bar Entry: A = menu number to clear (0 = clear all) Exit: A <> 0, zero flag clear (NZ) if operation successful A = 0, zero flag set (Z) if entry not found Affected: AF Usage: Deletes an entry from the menu bar and moves all subsequent entries to the left. Logical entry numbers stay the same as when loaded, but this function refers to the physical positioning on the menu bar. Example: EXT CLRPDM ; declare the variable ... ; ..establish pull-down menus LD A,4 ; remove the 4th entry CALL CLRPDM ; ..in the bar JR NZ,REMOK ; jump if removal OK ... Routine: SELPDM Function: Enter pull-down menu and return menu/item selec tions Entry: None Exit: A = 0, zero flag set (Z) if pull-down menu escape key pressed A <> 0, zero clear (NZ) if menu item selected H = menu number selected L = item selection number selected Affected: AF, HL Usage: This routine forms the heart of the pull-down menu system. When entered, control will not return to the program until either the pull-down menu escape character is pressed, or a valid menu and item are selected. By evaluating the returned values, specific actions may be taken such as selecting programs to run, items to list, etc. Routine: MCLS Function: Clear terminal screen except for pull-down menu bar Entry: None Exit: A <> 0, zero flag reset (NZ) if screen cleared OK A = 0 zero flag set (Z) if CLREOS not implemented Affected: AF Usage: Clears the screen from line 2 to the end-of- screen, to preserve pull-down menu selection bar on line 1. Routine: PDMINI Function: Initialize pull-down menu functions Entry: None Exit: None; internal menu variables are initialized Affected: None Usage: This routine must be called before the pull-down menu system is used. It clears needed variables and sets the default pull-down menu escape charac ter to ESC (1Bh). Example: EXT PDMINI ; declare the routine ... ; ..preliminary code sections CALL PDMINI ; initialize pull-down menus ... ; ..now set menus, etc Routine: ISPDM Function: Check character for pull-down menu escape character Entry: A = character to check Exit: A = character Zero clear (NZ) if it is the escape character Zero flag set (Z) if not the escape character Affected: Flags Usage: This routine is used in the pull-down menu selec tion code to sense for the escape character, and may be used in a similar mode in other programs. Set the desired character with SPDMCHR. Example: EXT ISPDM,CIN ; declare some routines ... ; ..preceding code CALL CIN ; get a character from console CALL ISPDM ; is it the escape char? JR NZ,HAVIT ; ..jump if so ... ; else loop or whatever.. Routine: SPDMCHR Function: Change the value of the pull-down menu escape character Entry: A = new character to use as pull-down menu escape character Exit: None; the character is set (normally ESC-1Bh, or ^\-1Ch) Affected: None Usage: Changes the pull-down menu escape character from the initial value of ESC (1Bh). Normal values are either ESC (1Bh) or ^\ (1Ch). READING THE TERMINAL SCREEN: Routine: GETCUR Function: Get the current cursor position from the terminal Entry: None Exit: A = 0FFh, zero flag clear (NZ) if successful HL = current cursor position (if NZ) A = 0, zero flag set (Z) if function is not available Affected: AF, HL Usage: Returns cursor position as used by GOTOXY routine (H = row, L = column). Example: EXT GETCUR,GOTOXY ; declare routines ... ; ..intervening code CALL GETCUR ; get cursor position JR Z,NOTAVAIL ; ..jump if not available LD (CURPOS),HL ; store position for later ... ; ..your screen routines LD HL,(CURPOS) ; get back stored position CALL GOTOXY ; and restore cursor ; to where it was Routine: GETLIN Function: Read a line from the terminal screen Entry: Cursor positioned at end of line Exit: A = 0FFh, zero flag clear (NZ) if successful HL = address of null-terminated string from terminal (if NZ) A = 0, zero flag set (Z) if function is not available Affected: AF, HL Usage: Reads line containing cursor from the first column to (and including) the current cursor column, so position the cursor first. Example: EXT GOTOXY,GETLIN ; declare routines ... ; ..intervening code LD H,1 ; row 1 LD L,80 ; column 80 CALL GOTOXY ; position the cursor CALL GETLIN ; get the line JR Z,NOTAVAIL ; ..jump if not available