;
                                  TCSRC.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               5k (37)   0B17  1.3        Terry Hazen 5/90         Z3COM13

  1- Syntax/Usage  2- TCSRC and VLIB4D  3- Notes                              

   The new extended Z3TCAP defined in VLIB4D includes  two terminal configura-
tion bytes that allow the user to  specify to applications programs how he has 
his terminal configured as well  as several new  terminal control  strings and 
basic line graphics.  Since it is difficult to extensively customize an exist-
ing Z3TCAP.Z3T file by patching alone,  TCSRC  was written  to  help  the user 
customize his Z3TCAP by  creating  a commented source  code  file (MYTERM.Z80) 
from an existing MYTERM.Z3T file for his terminal,  such as one extracted from 
Z3TCAP.TCP by TCSEL, or from the current Z3TCAP located in memory in the ZCPR3
environment.  The new source code file can then be edited,  assembled to a COM
file, renamed to a .Z3T file, and uploaded to the environment using LDR, NZCOM
or JETLDR.
:1

    Syntax   TCSRC [dir:]infile[.z3t] [[dir:]outfile[.z80]]


   Special infile names:
      'Z3ENV' creates source code file from the Z3TCAP in the environment.
      'BLANK' creates blank commented source code file.

   Default outfile is INFILE.Z80 on default directory.  

   Any existing R/W file of the same name will be overwritten.

 Usage - 1/2 

   TCSRC generates Z3TCAP commented  source code  based on the extended Z3TCAP
defined by VLIB4D.   VLIB4D  modifies the sequence of  control strings in  the 
extended Z3TCAP over that  specified by earlier VLIB4 beta  releases to  bring 
all  the  terminal control strings into  a common area  located  prior  to the 
graphics area, reduces the length of the  terminal name to 13 bytes and adds a
byte defining the offset of the graphics area from the start of the Z3TCAP.

   TCSRC expects input files to  be subsets  of the  VLIB4D standard,  such as 
standard Z3TCAP files.   Consult the VLIB4 help files for explanations of each  
of the defined terminal functions  and consult your terminal manual for infor-
mation on the  terminal control  strings  required to  implement  the terminal 
functions for your terminal.
 Usage - 2/2 

   Source code  produced  by TCSRC  from  earlier  extended  Z3TCAP files with 
different extended formats will begin to  be incorrect  when  the  sequence of 
control strings begins to  differ from  the  new VLIB4D standard and will have 
to be corrected with  a text editor.   Lines  of source code defining terminal 
control strings  may simply  be  moved into the correct  order, ignoring  both
comments and labels (except for GOELD,  which  is used  to define the graphics
area offset), as the corrected source code file  can  be  assembled  to  a COM
file and TCSRC can then be  used  again  to quickly generate a new,  correctly
commented source code file.
:2
 Terminal Configuration Bytes - 1/2 

   VLIB4 defines two terminal configuration bytes  at B14 (Z3TCAP+14)  and B15
(Z3TCAP+15) to allow an application program access to terminal characteristics 
not otherwise specified in the Z3TCAP.   Application programs such as WordStar 
and SCAN now  have  access  to information  not  only  about  terminal control 
strings, but about how users have configured their terminals.   Users  can set 
configuration bits indicating, for example, whether or not their terminals are 
set to auto-wrap at the end of  a line or auto-scroll at the end of  a screen, 
whether their terminals use ANSI or  ASCII control sequences, and whether they 
use reverse video  or non-reverse (usually dim) video for their standout mode.  
Not all application programs will check the terminal configuration bytes,  but 
their presence allows  the  user  some  control  over how application programs 
configure his screen display.
 Terminal Configuration Bytes - 2/2 

   SCAN, for example, checks the auto-wrap and auto-scroll bits to see whether 
it can put characters in the last display column on the screen without causing 
additional blank lines to be inserted into the display.   If both  bits are 0, 
the last column is considered  safe,  and the whole screen can be used for the
display.  If either bit is set, the last column is considered reserved and the 
next-to-last column will be  the final column used.   So  if  your terminal is 
configured to  not  automatically  wrap  or  scroll,  you  can  set  the  bits 
accordingly and SCAN  will  use  the  whole screen.   Joe Wright's  WSPAT  for 
WordStar4  uses the  configuration  bytes in a similar way, along with the set
attribute string to create WS4 display screens.
 Screen Display Configuration - 1/2 

   When you start looking at how many ways a given terminal can  be configured 
by  a user and  how that configuration can affect screen displays,  it quickly 
becomes clear that a standard Z3TCAP for a given terminal type is not adequate 
to convey more than basic standard information for that terminal.  It may make 
a difference to  a screen display intensive applications program, for example,
whether a screen is configured  as dark letters  on  a light  screen  or light 
letters on  a dark screen  and whether  reverse video or  a  non-reverse video 
mode, such as dim or bold is used as standout.  For example, if dim is used as 
standout mode on a dark screen,  spaces in standout mode won't show up, but if 
reverse video is used, they will, creating quite a different display.

   If the Z3TCAP for a particular terminal specifies dim as the standout mode, 
but the user prefers to use bold,  reserving  dim  for standard mode, but then 
wishes to exit to a normal video command line, he must customize his Z3TCAP to 
use SO (Start Standout),  SE (End Standout),  TI (Terminal Initialization) and 
TE (Terminal Deinitialization) to  set  his  terminal according to his prefer-
ences.  In  this example, SO would set dim,  SE would set normal, TI would set
dim, and TE would set normal video.
 Screen Display Configuration - 2/2 

   Still another user of the  same terminal type  might  prefer half intensity 
for standout,  and would need to customize  his Z3TCAP accordingly.   So  many 
terminal characteristics may  be user configured,  in fact,  that it is really 
the user's  responsibility  to create  a customized Z3TCAP for his system that 
reflects his own preferences.   TCSRC attempts  to facilitate this  process by
providing the user  a handy tool  to  quickly  create Z3TCAP source code files 
that may be easily edited and used to create his working customized Z3TCAP.
 Extended Z3TCAP Terminal Control Sequences 

   The source code created  by TCSRC includes  the  LD (delete line  at cursor 
position)  and  LI  (insert line at cursor position) sequences  added  in  the 
extended Z3TCAP defined by VLIB4B.  Applications such as WordStar and SCAN can 
use these control sequences to produce better displays.

   For screen display intensive applications such as WordStar 4.0 patch WSPAT, 
Joe Wright added a macro to the Z3TCAP and a routine in VLIB4C to set terminal 
display attributes.   The source code created  by TCSRC includes  the  SA (set 
Attributes) macro and AT (the attribute string).

   The source code created  by TCSRC  also  includes  a  CD (clear screen from 
cursor to end-of-screen) sequence.   While  sequence  is,  in  some  cases,  a 
duplication of part  of the  CL (Home Cursor and Clear Screen) sequence, it is 
now available as a separate control sequence.
 Other New VLIB4 Terminal Control Sequences 

   For use  with  windowing  routines  used  in  pull-down menus, the extended 
Z3TCAP includes a new RC sequence that  reads  the  character  at  the current 
cursor position and  a  RL sequence  that  reads  the entire line up until the 
cursor position into a buffer.  Consult V4LIB.HLP for more information.
 Graphics Extensions 

   VLIB4 adds a new standardized  character  graphics area beginning  at GOELD
(graphics on/off delay).   Graphics extensions include GO/GE (graphics mode on
and off), and CDO/GDE (turn the cursor off and on).
 Graphics Characters 

   Graphics characters now used by VLIB4  are one-byte characters that produce 
lines,  intersections,  corners,  as  well  as full and  hashed  blocks.   For 
terminals without graphics capability, very good results can be obtained using 
the characters '-'  and '|'  for  horizontal (GHL)  and  vertical  (GVL)  line 
characters.   The characters '*' and '#' can be used for full (GFB) and hashed
(GHB) blocks,  the characters  '+'  or  '*' can  be  used  for corners and the 
character '+' for intersections.

   Use TCSRC to add  graphics characters to  your own  Z3TCAP and  try BOX.COM 
from VLIB4D for  a demonstration of  the new line graphics  as  used in  a box 
drawing routine.
:3
 TCSRC Notes 

   a. Version 1.3 updates (05/07/90, Terry Hazen):
      - Adds ability to create blank source code file when infile is specified
        as BLANK.

   b. Version 1.2 updates (02/05/90, Terry Hazen):
      - Revised to reflect changes in  control  string  locations  in  VLIB4D,
        including  replacing the last byte of the name string  (now reduced to
        13 bytes) by GOFF,  the offset from the  start  of  the  Z3TCAP to the 
        start of the graphics area at GOELD.  
      - Adds ability to  generate  source code from the current  Z3TCAP in the 
        environment by specifying 'Z3ENV' as the infile.

   c. Version 1.1 updates (01/26/90, Terry Hazen):
      - Rewritten to do translation and loading in loops.  
      - Fixes missing putud in help requests.  
      - Adds  outfile  specification,  graphics  support  per VLIB4C.   Unless
        otherwise specified, the default outfile (INFILE.Z80) is now placed in
        the default directory.