home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 5 / ctrom5b.zip / ctrom5b / PROGRAM / DIVERSEN / TIPI2A / TIPI.DOC < prev    next >
Text File  |  1994-11-27  |  138KB  |  4,541 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.                                   __
  32.                                  /  \            ______
  33.                     /\          /    \          /      \
  34.                    /  \        /      \        /        \
  35.                   /    \      /\/\/\/\/\      /\/\/\/\/\/\
  36.                  /\/\/\/\    /          \    /            \
  37.                 /        \  /            \  /              \
  38.                /          \/              \/                \
  39.               /           /                \                 \
  40.              /           /                                    \
  41.             /     X     /  ########  ####  #####   ####        \
  42.            /     / \       ########  ####  ######  ####         \
  43.           /     /   \         ##      ##   ##  ##   ##           \
  44.          /     /  +  \        ##      ##   ######   ##            \
  45.         /     /   +   \       ##      ##   #####    ##             \
  46.        /     /    +    \      ##     ####  ##      ####             \
  47.       /      \___(_)___/      ##     ####  ##      ####              \
  48.  
  49.  
  50.  
  51.  
  52.       "A  most  important,  but also a most elusive, aspect of any tool is
  53.       its influence on the habits of those who  train  themselves  in  its
  54.       use.   If  this tool is a programming language, this influence is --
  55.       whether we like it or not -- an influence on our thinking habits."
  56.  
  57.       -- Edsger W.  Dijkstra "A Discipline of Programming"
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                Table of Contents
  64.  
  65.  
  66.  
  67.       1. The Preliminaries  . . . . . . . . . . . . . . . . . . . . . .  1
  68.         1.1 Legal Stuff . . . . . . . . . . . . . . . . . . . . . . . .  1
  69.         1.2 About the Author  . . . . . . . . . . . . . . . . . . . . .  1
  70.         1.3 Shareware . . . . . . . . . . . . . . . . . . . . . . . . .  1
  71.         1.4 What Registration Buys You  . . . . . . . . . . . . . . . .  2
  72.         1.5 The Great TIPI Code Contest . . . . . . . . . . . . . . . .  3
  73.           1.5.1 What You Can Win  . . . . . . . . . . . . . . . . . . .  4
  74.         1.6 The Order Form for TIPI 2.0a  . . . . . . . . . . . . . . .  5
  75.         1.7 TIPI Feedback . . . . . . . . . . . . . . . . . . . . . . .  6
  76.  
  77.       2. A Description of TIPI  . . . . . . . . . . . . . . . . . . . .  7
  78.         2.1 Introducing TIPI  . . . . . . . . . . . . . . . . . . . . .  7
  79.         2.2 The Origin of TIPI  . . . . . . . . . . . . . . . . . . . .  7
  80.         2.3 The Influences  . . . . . . . . . . . . . . . . . . . . . .  8
  81.         2.4 The Name  . . . . . . . . . . . . . . . . . . . . . . . . .  8
  82.         2.5 TIPI Qualities  . . . . . . . . . . . . . . . . . . . . . .  8
  83.  
  84.       3. Getting Started  . . . . . . . . . . . . . . . . . . . . . . . 10
  85.         3.1 Installing TIPI . . . . . . . . . . . . . . . . . . . . . . 10
  86.           3.1.1 A Note for HP Users . . . . . . . . . . . . . . . . . . 10
  87.         3.2 The TIPI Programmer's Workbench . . . . . . . . . . . . . . 11
  88.         3.3 The Sample Programs . . . . . . . . . . . . . . . . . . . . 15
  89.  
  90.       4. TIPI Programming . . . . . . . . . . . . . . . . . . . . . . . 16
  91.         4.1 Your First TIPI Program . . . . . . . . . . . . . . . . . . 16
  92.         4.2 The Basic Principle . . . . . . . . . . . . . . . . . . . . 17
  93.         4.3 Defining New Instructions . . . . . . . . . . . . . . . . . 17
  94.  
  95.       5. Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
  96.         5.1 A Description of TIPI Stacks  . . . . . . . . . . . . . . . 18
  97.         5.2 Stack Diagrams  . . . . . . . . . . . . . . . . . . . . . . 19
  98.         5.3 Why You Should Use Stacks . . . . . . . . . . . . . . . . . 19
  99.  
  100.       6. TIPI Math  . . . . . . . . . . . . . . . . . . . . . . . . . . 20
  101.         6.1 RPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
  102.         6.2 Integer Math  . . . . . . . . . . . . . . . . . . . . . . . 21
  103.  
  104.       7. Variables  . . . . . . . . . . . . . . . . . . . . . . . . . . 22
  105.  
  106.       8. The TIPI Debugger  . . . . . . . . . . . . . . . . . . . . . . 25
  107.  
  108.       9. Common mistakes of new TIPI Programmers  . . . . . . . . . . . 29
  109.  
  110.       10. Notes and Limits  . . . . . . . . . . . . . . . . . . . . . . 30
  111.  
  112.       11. Control Instructions  . . . . . . . . . . . . . . . . . . . . 31
  113.         11.1 BEGIN  . . . . . . . . . . . . . . . . . . . . . . . . . . 31
  114.  
  115.  
  116.                                        i
  117.  
  118.       Contents                                                          ii
  119.  
  120.  
  121.         11.2 CASE . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
  122.         11.3 CASE$  . . . . . . . . . . . . . . . . . . . . . . . . . . 31
  123.         11.4 DEFAULT  . . . . . . . . . . . . . . . . . . . . . . . . . 32
  124.         11.5 DEFAULT$ . . . . . . . . . . . . . . . . . . . . . . . . . 32
  125.         11.6 DO . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
  126.         11.7 ELSE . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
  127.         11.8 ENDCASE  . . . . . . . . . . . . . . . . . . . . . . . . . 33
  128.         11.9 ENDCASE$ . . . . . . . . . . . . . . . . . . . . . . . . . 33
  129.         11.10 ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . 33
  130.         11.11 ENDOF . . . . . . . . . . . . . . . . . . . . . . . . . . 33
  131.         11.12 ENDOF$  . . . . . . . . . . . . . . . . . . . . . . . . . 33
  132.         11.13 IF  . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
  133.         11.14 INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . 34
  134.         11.15 LEAVE . . . . . . . . . . . . . . . . . . . . . . . . . . 34
  135.         11.16 LOOP  . . . . . . . . . . . . . . . . . . . . . . . . . . 34
  136.         11.17 OF  . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
  137.         11.18 OF$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
  138.         11.19 UNTIL . . . . . . . . . . . . . . . . . . . . . . . . . . 35
  139.         11.20 WEND  . . . . . . . . . . . . . . . . . . . . . . . . . . 35
  140.         11.21 WHILE . . . . . . . . . . . . . . . . . . . . . . . . . . 36
  141.  
  142.       12. Data Instructions . . . . . . . . . . . . . . . . . . . . . . 37
  143.         12.1 FETCH  . . . . . . . . . . . . . . . . . . . . . . . . . . 37
  144.         12.2 STORE  . . . . . . . . . . . . . . . . . . . . . . . . . . 37
  145.  
  146.       13. Debugging Instructions  . . . . . . . . . . . . . . . . . . . 38
  147.         13.1 TRACECOL . . . . . . . . . . . . . . . . . . . . . . . . . 38
  148.         13.2 TRACEOFF . . . . . . . . . . . . . . . . . . . . . . . . . 38
  149.         13.3 TRACEON  . . . . . . . . . . . . . . . . . . . . . . . . . 38
  150.         13.4 TRACEROW . . . . . . . . . . . . . . . . . . . . . . . . . 39
  151.         13.5 TRACEVAR . . . . . . . . . . . . . . . . . . . . . . . . . 39
  152.  
  153.       14. Defining Instructions . . . . . . . . . . . . . . . . . . . . 40
  154.         14.1 DEFARRAY . . . . . . . . . . . . . . . . . . . . . . . . . 40
  155.         14.2 DEFINE . . . . . . . . . . . . . . . . . . . . . . . . . . 40
  156.         14.3 DEFSTR . . . . . . . . . . . . . . . . . . . . . . . . . . 41
  157.         14.4 DEFSTRARRAY  . . . . . . . . . . . . . . . . . . . . . . . 41
  158.         14.5 DEFTABLE . . . . . . . . . . . . . . . . . . . . . . . . . 41
  159.         14.6 DEFVAR . . . . . . . . . . . . . . . . . . . . . . . . . . 42
  160.         14.7 ENDDEF . . . . . . . . . . . . . . . . . . . . . . . . . . 42
  161.         14.8 ENDTABLE . . . . . . . . . . . . . . . . . . . . . . . . . 42
  162.  
  163.       15. DOS Instructions  . . . . . . . . . . . . . . . . . . . . . . 43
  164.         15.1 CALL . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
  165.         15.2 CHDIR  . . . . . . . . . . . . . . . . . . . . . . . . . . 43
  166.         15.3 COMMAND$ . . . . . . . . . . . . . . . . . . . . . . . . . 43
  167.         15.4 ENV$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
  168.         15.5 FIRSTFILE  . . . . . . . . . . . . . . . . . . . . . . . . 44
  169.         15.6 GETDIR . . . . . . . . . . . . . . . . . . . . . . . . . . 44
  170.         15.7 KILL . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
  171.         15.8 MAKEDIR  . . . . . . . . . . . . . . . . . . . . . . . . . 45
  172.         15.9 NEXTFILE . . . . . . . . . . . . . . . . . . . . . . . . . 45
  173.         15.10 REMDIR  . . . . . . . . . . . . . . . . . . . . . . . . . 45
  174.         15.11 RENAME  . . . . . . . . . . . . . . . . . . . . . . . . . 45
  175.  
  176.  
  177.       Contents                                                         iii
  178.  
  179.  
  180.       16. Graphics Instructions . . . . . . . . . . . . . . . . . . . . 46
  181.         16.1 DRAWLINE . . . . . . . . . . . . . . . . . . . . . . . . . 46
  182.         16.2 DRAWRECT . . . . . . . . . . . . . . . . . . . . . . . . . 46
  183.         16.3 GETFONT  . . . . . . . . . . . . . . . . . . . . . . . . . 46
  184.         16.4 GETPOINT . . . . . . . . . . . . . . . . . . . . . . . . . 47
  185.         16.5 MOVEPEN  . . . . . . . . . . . . . . . . . . . . . . . . . 47
  186.         16.6 PLOTICON . . . . . . . . . . . . . . . . . . . . . . . . . 47
  187.         16.7 PLOTPOINT  . . . . . . . . . . . . . . . . . . . . . . . . 48
  188.         16.8 PLOTTEXT . . . . . . . . . . . . . . . . . . . . . . . . . 48
  189.         16.9 SCREEN . . . . . . . . . . . . . . . . . . . . . . . . . . 48
  190.         16.10 SCROLL  . . . . . . . . . . . . . . . . . . . . . . . . . 49
  191.         16.11 SETCLIP . . . . . . . . . . . . . . . . . . . . . . . . . 49
  192.         16.12 SETFONT . . . . . . . . . . . . . . . . . . . . . . . . . 49
  193.         16.13 SETLINETYPE . . . . . . . . . . . . . . . . . . . . . . . 49
  194.         16.14 SETLOGORG . . . . . . . . . . . . . . . . . . . . . . . . 50
  195.         16.15 SETPENCOLOR . . . . . . . . . . . . . . . . . . . . . . . 50
  196.         16.16 SETREPRULE  . . . . . . . . . . . . . . . . . . . . . . . 50
  197.         16.17 SETVMODE  . . . . . . . . . . . . . . . . . . . . . . . . 51
  198.         16.18 ZOOM  . . . . . . . . . . . . . . . . . . . . . . . . . . 51
  199.  
  200.       17. I/O Instructions  . . . . . . . . . . . . . . . . . . . . . . 52
  201.         17.1 BEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
  202.         17.2 BLOAD  . . . . . . . . . . . . . . . . . . . . . . . . . . 52
  203.         17.3 BSAVE  . . . . . . . . . . . . . . . . . . . . . . . . . . 52
  204.         17.4 CLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . 53
  205.         17.5 CLS  . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
  206.         17.6 COLOR  . . . . . . . . . . . . . . . . . . . . . . . . . . 53
  207.         17.7 COLOR? . . . . . . . . . . . . . . . . . . . . . . . . . . 53
  208.         17.8 COLUMN . . . . . . . . . . . . . . . . . . . . . . . . . . 54
  209.         17.9 COMSTAT  . . . . . . . . . . . . . . . . . . . . . . . . . 54
  210.         17.10 CONSOLE . . . . . . . . . . . . . . . . . . . . . . . . . 54
  211.         17.11 CR  . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
  212.         17.12 CURRENT . . . . . . . . . . . . . . . . . . . . . . . . . 55
  213.         17.13 CURSOR  . . . . . . . . . . . . . . . . . . . . . . . . . 55
  214.         17.14 DEFSEG  . . . . . . . . . . . . . . . . . . . . . . . . . 55
  215.         17.15 EOF . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
  216.         17.16 EXTENDED  . . . . . . . . . . . . . . . . . . . . . . . . 56
  217.         17.17 FILEPOS . . . . . . . . . . . . . . . . . . . . . . . . . 56
  218.         17.18 GETBYTE . . . . . . . . . . . . . . . . . . . . . . . . . 56
  219.         17.19 GETNUM  . . . . . . . . . . . . . . . . . . . . . . . . . 57
  220.         17.20 GETPORT . . . . . . . . . . . . . . . . . . . . . . . . . 57
  221.         17.21 GETVOL  . . . . . . . . . . . . . . . . . . . . . . . . . 57
  222.         17.22 GET$  . . . . . . . . . . . . . . . . . . . . . . . . . . 57
  223.         17.23 INKEY$  . . . . . . . . . . . . . . . . . . . . . . . . . 58
  224.         17.24 INPORT  . . . . . . . . . . . . . . . . . . . . . . . . . 58
  225.         17.25 ISINPUT . . . . . . . . . . . . . . . . . . . . . . . . . 58
  226.         17.26 ISOUTPUT  . . . . . . . . . . . . . . . . . . . . . . . . 58
  227.         17.27 KEY . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
  228.         17.28 LF  . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
  229.         17.29 LOCATE  . . . . . . . . . . . . . . . . . . . . . . . . . 59
  230.         17.30 MOUSE . . . . . . . . . . . . . . . . . . . . . . . . . . 59
  231.         17.31 OPEN  . . . . . . . . . . . . . . . . . . . . . . . . . . 59
  232.         17.32 OPENCOM . . . . . . . . . . . . . . . . . . . . . . . . . 60
  233.         17.33 OUTPORT . . . . . . . . . . . . . . . . . . . . . . . . . 60
  234.         17.34 PEEK  . . . . . . . . . . . . . . . . . . . . . . . . . . 60
  235.  
  236.       Contents                                                          iv
  237.  
  238.  
  239.         17.35 POKE  . . . . . . . . . . . . . . . . . . . . . . . . . . 61
  240.         17.36 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . 61
  241.         17.37 PRINTCHR  . . . . . . . . . . . . . . . . . . . . . . . . 61
  242.         17.38 PRINTER . . . . . . . . . . . . . . . . . . . . . . . . . 61
  243.         17.39 PRINT$  . . . . . . . . . . . . . . . . . . . . . . . . . 62
  244.         17.40 PUTBYTE . . . . . . . . . . . . . . . . . . . . . . . . . 62
  245.         17.41 PUTPORT . . . . . . . . . . . . . . . . . . . . . . . . . 62
  246.         17.42 ROW . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
  247.         17.43 SETVOL  . . . . . . . . . . . . . . . . . . . . . . . . . 62
  248.         17.44 SOUND . . . . . . . . . . . . . . . . . . . . . . . . . . 63
  249.         17.45 VARPTR  . . . . . . . . . . . . . . . . . . . . . . . . . 63
  250.         17.46 | . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
  251.  
  252.       18. Math Instructions . . . . . . . . . . . . . . . . . . . . . . 64
  253.         18.1 ABS  . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
  254.         18.2 MAX  . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
  255.         18.3 MIN  . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
  256.         18.4 MOD  . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
  257.         18.5 *  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
  258.         18.6 +  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
  259.         18.7 -  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
  260.         18.8 /  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
  261.         18.9 <  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
  262.         18.10 = . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
  263.         18.11 > . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
  264.  
  265.       19. Miscellaneous Instructions  . . . . . . . . . . . . . . . . . 67
  266.         19.1 BIT? . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
  267.         19.2 BYE  . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
  268.         19.3 ERROR  . . . . . . . . . . . . . . . . . . . . . . . . . . 67
  269.         19.4 EVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
  270.         19.5 FALSE  . . . . . . . . . . . . . . . . . . . . . . . . . . 68
  271.         19.6 MACHINE? . . . . . . . . . . . . . . . . . . . . . . . . . 68
  272.         19.7 NOT  . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
  273.         19.8 OFF  . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
  274.         19.9 RANDOM . . . . . . . . . . . . . . . . . . . . . . . . . . 69
  275.         19.10 RANDOMIZE . . . . . . . . . . . . . . . . . . . . . . . . 69
  276.         19.11 TICKS . . . . . . . . . . . . . . . . . . . . . . . . . . 69
  277.         19.12 TIMEOUT . . . . . . . . . . . . . . . . . . . . . . . . . 70
  278.         19.13 TRUE  . . . . . . . . . . . . . . . . . . . . . . . . . . 70
  279.         19.14 VERSION . . . . . . . . . . . . . . . . . . . . . . . . . 70
  280.         19.15 # . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
  281.         19.16 ( . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
  282.         19.17 ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
  283.  
  284.       20. Stack Instructions  . . . . . . . . . . . . . . . . . . . . . 72
  285.         20.1 DEPTH  . . . . . . . . . . . . . . . . . . . . . . . . . . 72
  286.         20.2 DEPTH$ . . . . . . . . . . . . . . . . . . . . . . . . . . 72
  287.         20.3 DROP . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
  288.         20.4 DROP$  . . . . . . . . . . . . . . . . . . . . . . . . . . 73
  289.         20.5 DUP  . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
  290.         20.6 DUP$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
  291.         20.7 OVER . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
  292.         20.8 OVER$  . . . . . . . . . . . . . . . . . . . . . . . . . . 73
  293.         20.9 PICK . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
  294.  
  295.       Contents                                                           v
  296.  
  297.  
  298.         20.10 PICK$ . . . . . . . . . . . . . . . . . . . . . . . . . . 74
  299.         20.11 POP . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
  300.         20.12 PUSH  . . . . . . . . . . . . . . . . . . . . . . . . . . 74
  301.         20.13 ROT . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
  302.         20.14 ROT$  . . . . . . . . . . . . . . . . . . . . . . . . . . 75
  303.         20.15 SWAP  . . . . . . . . . . . . . . . . . . . . . . . . . . 75
  304.         20.16 SWAP$ . . . . . . . . . . . . . . . . . . . . . . . . . . 75
  305.  
  306.       21. String Instructions . . . . . . . . . . . . . . . . . . . . . 76
  307.         21.1 ASC  . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
  308.         21.2 CHR$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
  309.         21.3 DATE$  . . . . . . . . . . . . . . . . . . . . . . . . . . 76
  310.         21.4 INSTR  . . . . . . . . . . . . . . . . . . . . . . . . . . 77
  311.         21.5 LCASE$ . . . . . . . . . . . . . . . . . . . . . . . . . . 77
  312.         21.6 LEFT$  . . . . . . . . . . . . . . . . . . . . . . . . . . 77
  313.         21.7 LEN  . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
  314.         21.8 LTRIM$ . . . . . . . . . . . . . . . . . . . . . . . . . . 78
  315.         21.9 MID$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
  316.         21.10 PARSE$  . . . . . . . . . . . . . . . . . . . . . . . . . 78
  317.         21.11 REPLACE$  . . . . . . . . . . . . . . . . . . . . . . . . 78
  318.         21.12 RIGHT$  . . . . . . . . . . . . . . . . . . . . . . . . . 78
  319.         21.13 RTRIM$  . . . . . . . . . . . . . . . . . . . . . . . . . 79
  320.         21.14 STR$  . . . . . . . . . . . . . . . . . . . . . . . . . . 79
  321.         21.15 TIME$ . . . . . . . . . . . . . . . . . . . . . . . . . . 79
  322.         21.16 UCASE$  . . . . . . . . . . . . . . . . . . . . . . . . . 79
  323.         21.17 VAL . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
  324.         21.18 " . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
  325.         21.19 +$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
  326.         21.20 =$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
  327.  
  328.       Index of TIPI Instructions  . . . . . . . . . . . . . . . . . . . 81
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.                                    Chapter 1
  336.  
  337.                                The Preliminaries
  338.  
  339.  
  340.  
  341.  
  342.  
  343.       1.1 Legal Stuff
  344.  
  345.       DISCLAIMER: This software is provided "as is"  without  warranty  of
  346.       any kind, either expressed or implied.
  347.  
  348.       Your  registration  fee entitles you to distribute TIPI.EXE together
  349.       with any TIPI programs you write as  well  as  any  EXEs  you  build
  350.       using  TIPI's MakeEXE option.  If you profit from working with TIPI,
  351.       please register it.  Thanks!
  352.  
  353.       TIPI.EXE,  this  manual,  the  various  sample  programs   and   the
  354.       utilities  included  here  are  copyright  (c)  1993,1994 by Kent P.
  355.       Peterson.  All Rights Reserved.
  356.  
  357.  
  358.       1.2 About the Author
  359.  
  360.       I'm Kent Peterson and I wrote TIPI and  this  manual.   I  currently
  361.       live  in  Issaquah,  Washington  with my wife, two sons, a cat and a
  362.       mess of computers.  When I grow up I'd like to be an  eighth-century
  363.       Taoist  hermit.   For  now  I spend my days as a programming manager
  364.       for a computer gaming company.   I  spend  my  nights  and  weekends
  365.       hacking small computers and drinking way too much coffee.
  366.  
  367.  
  368.       1.3 Shareware
  369.  
  370.       TIPI  2.0a  is  provided as shareware.  Under the shareware concept,
  371.       you can test a program before you buy it.  If you find  TIPI  useful
  372.       and valuable to you, please send in the $35 registration fee.
  373.  
  374.       Please  distribute  this  software  widely.   Shareware  works  when
  375.       people make copies of disks, upload code to the nets and  pass  good
  376.       ideas  on  to  others.   I  do  request  that  you do not alter this
  377.       software or documentation.
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.                                        1
  388.  
  389.       Chapter 1. The Preliminaries                                       2
  390.  
  391.  
  392.       1.4 What Registration Buys You
  393.  
  394.       Peace of  Mind  --  When  you  register  TIPI,  you  will  have  the
  395.           satisfaction  of knowing that you are helping make the shareware
  396.           system work.  Instead of feeling guilty each time you use  TIPI,
  397.           you  will feel great knowing you paid a fair price for something
  398.           you value.
  399.  
  400.       A Future for TIPI -- Your registration lets me know  TIPI  is  being
  401.           used  and  that  there still is a place for independent software
  402.           development.  Late at night when I want to chuck  it  all,  I'll
  403.           remember that you sent me a check and I'll keep on coding.
  404.  
  405.       Free  EXEs  --  The TIPI Programmer's Workbench can make stand-alone
  406.           EXEs from your TIPI programs.  An unregistered copy of TIPI  can
  407.           create  these  EXEs, but they will contain a shareware reminder.
  408.           When you register TIPI, you will receive code  that  will  allow
  409.           you to create EXEs without the shareware reminder.
  410.  
  411.       Tech  Support -- If you have a problem with TIPI, want clarification
  412.           about how some instruction works or need some clue about how  to
  413.           crack  a  particular  problem, it's good to have someone to ask.
  414.           If you're a registered TIPI owner, you can ask me via Email  and
  415.           I  will  do  my  best  to  respond.  If you are not a registered
  416.           owner,  you  can  still  ask  me  questions  but  you  stand   a
  417.           popsicle's chance in Hades of getting an answer.
  418.  
  419.       More  TIPI  Code  --  Registered  TIPI  users  will  be  sent a disk
  420.           containing many  more  examples  of  TIPI  code.   Some  of  the
  421.           programs  will  be written by me and the rest will be written by
  422.           your fellow TIPI programmers.  This disk will  contain  programs
  423.           written  for the Great TIPI Code Contest and will be sent out in
  424.           April of 1995.
  425.  
  426.       Chapter 1. The Preliminaries                                       3
  427.  
  428.  
  429.       1.5 The Great TIPI Code Contest
  430.  
  431.       "The Street finds its own uses for things -- uses the  manufacturers
  432.       never imagined." -- William Gibson
  433.  
  434.       OK,  here's  the  deal.   Between now and March 5th, 1995 (that's my
  435.       birthday),  I'll  be  accepting  entries  in  the  GREAT  TIPI  CODE
  436.       CONTEST.  The rules are simple:
  437.  
  438.         . The  contest  is  open to ANY user of TIPI (even if those of you
  439.           who haven't gotten around to registering it yet!)
  440.  
  441.         . You entry must consist of a TIPI program you have  written  that
  442.           you  think  is  interesting,  practical,  fun, neat, cool or (at
  443.           least) worth more than the disk space it occupies.
  444.  
  445.         . You may enter as many programs as you like and you may enter  as
  446.           many times as you like.
  447.  
  448.         . Entries  must  be  submitted either via Email or on MSDOS floppy
  449.           disks.
  450.  
  451.         . Your disks will not be returned, nor will your  Email  costs  be
  452.           reimbursed.
  453.  
  454.       Email may be sent to either
  455.  
  456.               Internet    peterson@halcyon.com
  457.  
  458.                     or
  459.  
  460.               Compuserve  72310,2174
  461.  
  462.       Disks may be mailed to
  463.  
  464.               Kent Peterson
  465.               GREAT TIPI CODE CONTEST
  466.               360 NW Dogwood Street A-201
  467.               Issaquah, WA 98027 USA
  468.  
  469.       Copyrights  to  all  code entered into this contest will remain with
  470.       you, but any code entered may  be  distributed  to  registered  TIPI
  471.       users.
  472.  
  473.       Chapter 1. The Preliminaries                                       4
  474.  
  475.  
  476.       1.5.1 What You Can Win
  477.  
  478.       The  author  of  the  niftiest program (as judged by myself, my wife
  479.       and some of my nerdy friends) will win
  480.  
  481.       FREE CHOCOLATE!!!  -- One  box  of  delicious  chocolates  from  the
  482.           world famous Boehm's Chocolates in Issaquah, Washington.
  483.  
  484.       A  KEEN TROPHY!!!  -- A genuine TIPI Code Contest trophy to show off
  485.           to all your friends.
  486.  
  487.       A TRIP TO ISSAQUAH!!!  -- A some  expense  paid  trip  to  beautiful
  488.           Issaquah,  Washington.   The  some  expenses covered include the
  489.           two dollar cost  of  a  metro  bus  trip  from  Seattle,  WA  to
  490.           Issaquah.   If  your  costs are more than that, you have to pick
  491.           up the balance of the tab.
  492.  
  493.       ESPRESSO AND WITTY CONVERSATION!!!  -- If you make it  to  Issaquah,
  494.           I  will  buy  you  an  Espresso  drink  of your choice at one of
  495.           Issaquah's many Espresso bars and we'll hang out.  If  you  want
  496.           to just take the drink and split, that's fine too.
  497.  
  498.       In  April  of  1995, anyone who has REGISTERED TIPI by March 5, 1995
  499.       will receive a disk containing some new  TIPI  programs  written  by
  500.       myself,  the  winning  entry  from  the  contest  and  whatever cool
  501.       runners-up there were.
  502.  
  503.       Chapter 1. The Preliminaries                                       5
  504.  
  505.  
  506.       1.6 The Order Form for TIPI 2.0a
  507.  
  508.       To Register TIPI, please fill out a copy of this page  and  send  it
  509.       with you payment to:
  510.  
  511.  
  512.       Kent Peterson
  513.       360 NW Dogwood #A-201
  514.       Issaquah, WA  98027-3272
  515.  
  516.  
  517.       Ship to:
  518.  
  519.  
  520.       _________________________________________
  521.  
  522.       _________________________________________
  523.  
  524.       _________________________________________
  525.  
  526.       _________________________________________
  527.  
  528.       _________________________________________
  529.  
  530.  
  531.       Please send:
  532.  
  533.  
  534.       Qty   Description                                        Total
  535.  
  536.  
  537.       ____ TIPI Program Disk                @ $35.00 ea    $ ________
  538.            (Includes registered copy of program,
  539.             and manual on disk)
  540.  
  541.       ____ TIPI Printed Manual              @ $10.00 ea    $ ________
  542.            (Limit one per registered copy of TIPI)
  543.  
  544.            Sales Tax                                       $ ________
  545.            (Washington state residents please add 8.2% sales tax)
  546.  
  547.            Shipping & Handling                             $     5.00
  548.  
  549.                                   Total                    $ ________
  550.  
  551.  
  552.  
  553.            DISK SIZE (CHECK ONE):        5 1/4" [ ]     3 1/2" [ ]
  554.  
  555.  
  556.  
  557.       Chapter 1. The Preliminaries                                       6
  558.  
  559.  
  560.       1.7 TIPI Feedback
  561.  
  562.       I'm  always  looking  for ways to improve TIPI.  And the best source
  563.       of ideas for improvements is from TIPI  users  themselves.   So,  if
  564.       you  feel so inclined, take a moment and write down your suggestions
  565.       below and send them to me.  I appreciate your feedback!
  566.  
  567.  
  568.       Do you own a palmtop?  [ ] Yes    [ ] No
  569.  
  570.       Do you use TIPI on     [ ] a palmtop   [ ] a desktop  [ ] both
  571.  
  572.       List the top three things you would like added to TIPI:
  573.  
  574.       1) _________________________________________________________
  575.  
  576.       2) _________________________________________________________
  577.  
  578.       3) _________________________________________________________
  579.  
  580.       In the future, I may port TIPI to another operating system.
  581.       Should I
  582.  
  583.                 [ ] work on a Windows version
  584.                 [ ] work on a Macintosh version
  585.                 [ ] work on an OS/2 version
  586.                 [ ] work on a GEOS version
  587.                 [ ] work on a Unix version
  588.                 [ ] keep working on the DOS version
  589.  
  590.       Please use the remaining space to provide feedback on TIPI features
  591.       you like or dislike, or to list new features you'd like to see added
  592.       to TIPI. (attach additional sheets if you'd like):
  593.  
  594.       ______________________________________________________________
  595.  
  596.       ______________________________________________________________
  597.  
  598.       ______________________________________________________________
  599.  
  600.       ______________________________________________________________
  601.  
  602.       ______________________________________________________________
  603.  
  604.       ______________________________________________________________
  605.  
  606.  
  607.       You can also send questions/comments via Internet or Compuserve
  608.  
  609.                      Internet        peterson@halcyon.com
  610.  
  611.                      Compuserve      72310,2174
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.                                    Chapter 2
  619.  
  620.                              A Description of TIPI
  621.  
  622.  
  623.  
  624.  
  625.  
  626.       2.1 Introducing TIPI
  627.  
  628.       TIPI (pronounced "tepee" like the  nomadic  dwelling)  is  a  small,
  629.       structured  programming  language  for  MS-DOS  computers.  The TIPI
  630.       interpreter takes  up  about  12K  bytes  of  disk  space  and  TIPI
  631.       programs  are  similarly  small.   TIPI requires about 100K bytes of
  632.       RAM to run and is thus well-suited for  palmtop  computers  such  as
  633.       the Poquet PC, the HP-95LX or the HP100LX.
  634.  
  635.       TIPI   contains   over   170  instructions  and  control  structures
  636.       including Do..Loop, While..Wend and Begin..Until Loops.   TIPI  also
  637.       includes  If..Then..Else  and  Case  statements  and  an  integrated
  638.       debugger.  TIPI is an extensible language, so  programmers  may  add
  639.       to the language as they see fit.
  640.  
  641.  
  642.       2.2 The Origin of TIPI
  643.  
  644.       I  created  TIPI  specifically  for  programming  palmtop  computers
  645.       although it may also be used for creating programs  for  desktop  or
  646.       laptop  PCs.   I wrote the original version of TIPI (1.0) in 1993 so
  647.       I would have a small, elegant programming system for programming  my
  648.       Atari  Portfolio  and  other  small  DOS  machines.  Shortly after I
  649.       released the language as shareware in the fall  of  1993  it  became
  650.       obvious  that  the  majority  of  people using TIPI were running the
  651.       language on Hewlett-Packard 95LX and  100LX  palmtop  computers.   I
  652.       decided  to  get  myself  one  of these nifty little HP machines and
  653.       concentrate on optimizing the language for use on the HPs.  I'm  now
  654.       the  proud  and happy owner of an HP100LX and TIPI 2.0a now sports a
  655.       bunch of new instructions that take advantage  of  of  some  of  the
  656.       advanced features of the HPs.
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.                                        7
  671.  
  672.       Chapter 2. A Description of TIPI                                   8
  673.  
  674.  
  675.       2.3 The Influences
  676.  
  677.       TIPI  is  a  fairly  new language, but it incorporates elements from
  678.       various  earlier  languages.   TIPI  owes  a  tremendous  amount  to
  679.       Charles  Moore  and his language Forth.  While TIPI is not Forth, it
  680.       is definitely Forth-like and Forth-inspired.
  681.  
  682.       Whatever readability TIPI has is owed  to  John  Kemeny  and  Thomas
  683.       Kurtz.   These  two  gentlemen created a language for the rest of us
  684.       and called it BASIC.
  685.  
  686.       Other languages (including C, Pascal and AWK)  also  influenced  the
  687.       development  of TIPI.  In fact it's fair to say that TIPI is nothing
  688.       more than my collection of  neat  ideas  I've  stolen  from  various
  689.       places.   Oh  well,  Newton wrote about standing on the shoulders of
  690.       giants and that's not a bad way to work.
  691.  
  692.  
  693.       2.4 The Name
  694.  
  695.       The name TIPI is  an  acronym  standing  for  "Threaded  Instruction
  696.       Processing  Interpreter".   While  interpreted  programs tend to run
  697.       slower  than  compiled  programs,  interpreters  do  not  require  a
  698.       separate  compile  and  link  stage and thus programs can be quickly
  699.       tested and changed.   Also,  interpreters  can  be  very  small,  as
  700.       evidenced by TIPI's tiny size.
  701.  
  702.  
  703.       2.5 TIPI Qualities
  704.  
  705.       TIPI was created to be:
  706.  
  707.       Efficient  -- TIPI is based on a multi-stack interpreter.  This lets
  708.           numeric and string data pass quickly  and  consistently  between
  709.           instructions,  greatly  reducing  the  need for complex internal
  710.           parsers and temporary variables.
  711.  
  712.       Structured -- TIPI is very modular.  All TIPI instructions have  one
  713.           entry  and one exit point.  All instructions are clearly defined
  714.           and perform most of their interaction  via  stacks.   TIPI  does
  715.           not have the spaghetti-generating GOTO instruction.
  716.  
  717.       Small  --  TIPI  is  not a language for creating huge programs.  The
  718.           basic philosophy of TIPI is that problems should be broken  into
  719.           small,  discrete,  easily  understood  components.   In threaded
  720.           languages, performance degrades as the threads  get  longer  and
  721.           longer  threads  are  what  you get when you write big programs.
  722.           To keep TIPI reasonably fast, the TIPI  interpreter  is  limited
  723.           to processing programs of 32K or less.
  724.  
  725.       Clear  --  A  program  is  more than a set of instructions telling a
  726.           computer how to  solve  a  particular  problem,  it  is  also  a
  727.           document   precisely   describing   a  set  of  problem  solving
  728.           procedures.  A programming language needs to  be  comprehensible
  729.           to  the  computer  the  program  will  run  on  and clear to the
  730.  
  731.       Chapter 2. A Description of TIPI                                   9
  732.  
  733.  
  734.           programmers who write the code and future  programmers  who  may
  735.           have  to  modify  it.   With TIPI, every effort has been made to
  736.           make the language consistent and easy to read.
  737.  
  738.       Extensible -- Rather than having a complex system of  libraries  and
  739.           includes,  TIPI lets you use a text editor to copy commonly used
  740.           instruction definitions into your  code.   This  means  you  can
  741.           define  your  own  instructions  in  TIPI,  so  you  can add the
  742.           features you've always wanted in a language.
  743.  
  744.           A good way to think  about  this  is  to  think  about  how  the
  745.           English  language is extended by the addition of jargon.  Here's
  746.           an example.  Suppose you didn't  know  what  RAM  is.   You  ask
  747.           someone  and  they  tell you "RAM means Random Access Memory" or
  748.           "RAM is memory  that  forgets  everything  when  you  shut  your
  749.           computer  off".   Let's  say that one of these definitions makes
  750.           sense to you and you remember it.  From now  on  when  you  talk
  751.           about  computers, you can use the word RAM because you know what
  752.           it means in terms of things  you  already  knew.   You  use  the
  753.           jargon  as  a  quick  and  easy  shorthand  for  something  more
  754.           complicated.  You have just extended your vocabulary to  include
  755.           the word RAM.
  756.  
  757.           Where  English  has  words,  TIPI has instructions.  In the same
  758.           way that you add jargon to your English vocabulary  by  defining
  759.           a  new  word in terms of words you already know, you extend TIPI
  760.           by defining new instructions in terms of existing instructions.
  761.  
  762.           Here is a small chunk of TIPI code defining  a  new  instruction
  763.           called  WAIT  which  causes program execution to pause until the
  764.           user presses a key:
  765.  
  766.                  define wait
  767.                   begin key until
  768.                  enddef
  769.  
  770.           Once you have defined WAIT, you can  use  the  WAIT  instruction
  771.           anywhere in your code.
  772.  
  773.       TIPI  contains  over 170 built-in instructions for the programmer to
  774.       use  as  building  blocks.   These  instructions  fall  into  eleven
  775.       categories  and  are  described  fully in the later chapters of this
  776.       manual.
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.                                    Chapter 3
  784.  
  785.                                 Getting Started
  786.  
  787.  
  788.  
  789.  
  790.  
  791.       3.1 Installing TIPI
  792.  
  793.       TIPI 2.0a is distributed as  a  single  compressed  ZIP  file  named
  794.       TIPI2A.ZIP.   Using  PKUNZIP  or  an  equivalent ZIP file extraction
  795.       utility,  extract  the  contents  of  this  file  to  an  empty  DOS
  796.       directory  or  onto  a  floppy.   Of course, if you are reading this
  797.       file, you have probably already done this.
  798.  
  799.       To install  TIPI  on  a  palmtop  computer,  you  really  only  need
  800.       TIPI.EXE  and  whatever  TIPI  programs you care to run.  To get the
  801.       full use of TIPI, however, I  suggest  that  you  install  the  TIPI
  802.       Programmer's Workbench, described on the next page.
  803.  
  804.       3.1.1 A Note for HP Users
  805.  
  806.       TIPI  comes  with  some  files  that  are useful to owners of HP 100
  807.       series palmtops.  The first of these is T.ICN.  This is an  HP  Icon
  808.       file  and  may be used to add the TIPI Programmer's Workbench to the
  809.       HP desktop.  Another file is TIPI.GDB.  This is an HP database  file
  810.       containing  summaries  of  all  of  the  TIPI instructions.  You may
  811.       chose to use this instead of the standard help files  included  with
  812.       the workbench.
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.                                        10
  836.  
  837.       Chapter 3. Getting Started                                        11
  838.  
  839.  
  840.       3.2 The TIPI Programmer's Workbench
  841.  
  842.       The  TIPI  Programmer's  Workbench  is a tiny integrated environment
  843.       for TIPI development.  The  workbench  lets  you  create,  edit  and
  844.       debug TIPI programs.
  845.  
  846.       The  workbench defaults to running as a character-based application,
  847.       but users of the HP100LX or HP200LX have the option of  running  the
  848.       workbench  with  a  Graphical User Interface (GUI) that has the look
  849.       and feel of the built-in HP icon menus.
  850.  
  851.       The files that make up the workbench are:
  852.  
  853.       CHARTIPI.BAT  --  Run  this  to  set  TIPI  to  use  the   character
  854.           workbench.
  855.  
  856.       GUITIPI.BAT -- Run this to set TIPI to use the GUI workbench.
  857.  
  858.       CHARTIPI.DAT -- Data for the character workbench.
  859.  
  860.       GUITIPI.DAT -- Data for the GUI workbench.
  861.  
  862.       T.BAT -- The bat file that runs the workbench.
  863.  
  864.       T.TPI -- The character workbench TIPI program.
  865.  
  866.       TIPIGUI.TPI -- The GUI workbench TIPI program.
  867.  
  868.       T.ICN -- The TIPI icon.
  869.  
  870.       COMMAND.ICN -- The command icon.
  871.  
  872.       DOC.ICN -- The document icon.
  873.  
  874.       DOS.ICN -- The DOS icon.
  875.  
  876.       FACTORY.ICN -- The factory icon.
  877.  
  878.       LOOKUP.ICN -- The lookup icon.
  879.  
  880.       RUN.ICN -- The run icon.
  881.  
  882.       TIPI.EXE -- The TIPI interpreter.
  883.  
  884.       TIPI.GDB -- An HP database file describing the TIPI instructions.
  885.  
  886.       TIPICORE.BIN -- The binary image used to build EXEs.
  887.  
  888.       REGISTER.DAT -- The TIPI registration code.
  889.  
  890.       E.COM  --  Dr.   David Nye's wonderful freeware text editor.  I have
  891.           made one modification to this program  to  make  it  easier  for
  892.           palmtop  users  --  the  cursor is now a full size block all the
  893.           time.  Also note that this editor is not  designed  for  editing
  894.           large  files.   It  is  fine for TIPI programs (which are 32K or
  895.  
  896.       Chapter 3. Getting Started                                        12
  897.  
  898.  
  899.           less), but if you try to load large file  (like  this  document,
  900.           for example), it will choke.
  901.  
  902.       E.DOC -- The documentation for E.COM
  903.  
  904.       HELPTIPI.BAT -- The TIPI help system.
  905.  
  906.       HELPTIPI.TPI -- The main help file.
  907.  
  908.       HELPCONT.TPI -- The help file for control instructions.
  909.  
  910.       HELPDATA.TPI -- The help file for data instructions.
  911.  
  912.       HELPDBUG.TPI -- The help file for debugging instructions.
  913.  
  914.       HELPDFIN.TPI -- The help file for defining instructions.
  915.  
  916.       HELPDOS.TPI -- The help file for DOS instructions.
  917.  
  918.       HELPGRAF.TPI -- The help file for graphics instructions.
  919.  
  920.       HELPIO.TPI -- The help file for I/O instructions.
  921.  
  922.       HELPMATH.TPI -- The help file for math instructions.
  923.  
  924.       HELPMISC.TPI -- The help file for misc instructions.
  925.  
  926.       HELPSTAK.TPI -- The help file for stack instructions.
  927.  
  928.       HELPSTRS.TPI -- The help file for string instructions.
  929.  
  930.       All  of  these  files  are  included  with  this release, along with
  931.       various sample programs to get you started in TIPI  programming.   I
  932.       am  a  firm  believer  in  learning by example, so the I've included
  933.       various programs that you can run, study,  learn  from  and  modify.
  934.       In  addition,  the  TIPI Programmer's Workbench is composed entirely
  935.       of BAT files and TIPI programs, so you may modify it  to  suit  your
  936.       preferences once you become familiar with TIPI.
  937.  
  938.       To  get  familiar  with  the workbench, start the workbench with the
  939.       sample program HANGMAN.TPI.  You do this by typing:
  940.  
  941.       T HANGMAN
  942.  
  943.       Chapter 3. Getting Started                                        13
  944.  
  945.  
  946.       You will see a screen that looks like this:
  947.  
  948.  
  949.                +----------------------------------------------------+
  950.                |       TIPI Programmer's Workbench                  |
  951.                |                                                    |
  952.                |              Version 2.0a                          |
  953.                |                                                    |
  954.                |                                                    |
  955.                |  [E]dit                       X                    |
  956.                |  [C]hange Program            / \                   |
  957.                |  [S]et Command Line         /   \                  |
  958.                |  [R]un Program             /  +  \                 |
  959.                |  [M]ake EXE               /   +   \                |
  960.                |  [L]ookup                 \__( )__/                |
  961.                |  [D]OS Command                                     |
  962.                |                                                    |
  963.                |  Program Name: HANGMAN.TPI                         |
  964.                |  Command Line:                                     |
  965.                |                                                    |
  966.                +----------------------------------------------------+
  967.  
  968.       Note: The GUI workbench doesn't look quite like this,  but  I  can't
  969.       illustrate  it here.  It has all the same functions, however, so the
  970.       rest of this document applies to the GUI workbench as  well  as  the
  971.       character workbench.
  972.  
  973.       On  this screen you may select one of the options by pressing one of
  974.       the keys in brackets (E,C,S,R,M,L or D) or you may press  the  [ESC]
  975.       key to leave the workbench.
  976.  
  977.       [E]  --  will  load  the  current program (in this case HANGMAN.TPI)
  978.           into the editor, where you can look at the code or modify it  as
  979.           you  wish.   TIPI  ships  with  Dr.  David Nye's freeware editor
  980.           "E", but if you have  a  favorite  DOS  ASCII  editor,  you  can
  981.           modify the file T.TPI to use that editor instead.
  982.  
  983.       [C]  -- lets you change to another program.  [C] will display a list
  984.           of the current TIPI files and let you  choose  one  of  them  to
  985.           work on.
  986.  
  987.       [S]  --  is used to set the command line that will be used when your
  988.           program is run.  This option  lets  you  set  any  command  line
  989.           arguments that you may want to pass to your program.
  990.  
  991.       [R] -- will run the current program.
  992.  
  993.       [M]  -- will make an EXE file from the current TIPI program.  If you
  994.           have  a  registered  copy  of  TIPI,  this  EXE  will  be  fully
  995.           functional  with no annoying shareware message.  If your copy of
  996.           TIPI is  unregistered,  any  EXEs  it  creates  will  display  a
  997.           registration  reminder  before  they  execute.   They will still
  998.           work fine, but this should give you incentive to register.
  999.  
  1000.       Chapter 3. Getting Started                                        14
  1001.  
  1002.  
  1003.       [L] -- will let you lookup the  specific  details  of  each  of  the
  1004.           built-in  TIPI  instructions.   [L]ookup will take you to a menu
  1005.           listing each of the various groups of instructions.   This  menu
  1006.           will  take  you  to  submenus which in turn will take you to the
  1007.           details of each instruction.  Pressing the key listed in the  []
  1008.           will  take  you  to  that option, while pressing [ESC] will back
  1009.           you up one level.  This format should let you find  the  details
  1010.           you need.
  1011.  
  1012.       [D]  --  will  let you run any DOS command you like.  This is useful
  1013.           for copying files, making backups or testing EXEs you have  just
  1014.           made.
  1015.  
  1016.       [ESC] -- leaves the workbench.
  1017.  
  1018.       Chapter 3. Getting Started                                        15
  1019.  
  1020.  
  1021.       3.3 The Sample Programs
  1022.  
  1023.       The TIPI sample programs are:
  1024.  
  1025.       ANYBASE.TPI  --  A  program to convert integers from any number base
  1026.           to any other base.
  1027.  
  1028.       ASCII.TPI -- A program can tell  you  the  ASCII  and  keycodes  for
  1029.           keystrokes and characters.
  1030.  
  1031.       BENCH.TPI  --  A  simple benchmark program to tell you how fast your
  1032.           PC runs TIPI.
  1033.  
  1034.       BIRTHDAY.TPI -- A program to play a familiar song.
  1035.  
  1036.       BUGDEMO.TPI -- A program to  demonstrate  some  of  the  HP  palmtop
  1037.           graphics.   Note  --  This program also uses the files AAV1.ICN,
  1038.           AAV2.ICN, BUG.ICN and BUG2.ICN.
  1039.  
  1040.       CAL.TPI -- A program that displays  the  calendar  for  the  current
  1041.           month.
  1042.  
  1043.       DEMO.TPI -- A simple demo program.
  1044.  
  1045.       DIRTEST.TPI    --   A   program   demonstrating   TIPI's   directory
  1046.           instructions.
  1047.  
  1048.       ENVTEST.TPI -- A program demonstrating how TIPI  can  read  the  DOS
  1049.           environment.
  1050.  
  1051.       ERROR.TPI -- A program to demonstrate the use of the TIPI debugger.
  1052.  
  1053.       ERROR2.TPI   --  A  more  complicated  example  to  demonstrate  the
  1054.           debugger.
  1055.  
  1056.       HAIKU.TPI -- A program to generate bad haiku poems.
  1057.  
  1058.       HANGMAN.TPI -- The game of Hangman.  Note -- this program also  uses
  1059.           the file HANGWORD.TXT.
  1060.  
  1061.       HELLO.TPI  --  A  TIPI  version  of  the world famous "Hello World!"
  1062.           program.
  1063.  
  1064.       MOUSE.TPI  --  A  program  to  demonstrate  the  use  of  the  MOUSE
  1065.           instruction.
  1066.  
  1067.       PPUZZLE.TPI -- A puzzle kind of like a Rubik's Cube.
  1068.  
  1069.       POWERS.TPI -- A program to introduce the extensibility of TIPI.
  1070.  
  1071.       TIPIREG.TPI  -- A program that lets you enter your registration code
  1072.           to create a registered version of TIPI.
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.                                    Chapter 4
  1080.  
  1081.                                 TIPI Programming
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.       4.1 Your First TIPI Program
  1088.  
  1089.       Here is a simple little TIPI program:
  1090.  
  1091.  
  1092.           # HELLO.TPI by Kent Peterson
  1093.  
  1094.           | Hello World!
  1095.  
  1096.           begin
  1097.            key
  1098.           until
  1099.  
  1100.  
  1101.       OK, This isn't too bad.  It's only five  lines  long  (not  counting
  1102.       blank  lines)  so  we can take the time to explain this program line
  1103.       by line.
  1104.  
  1105.       The first line is a comment.  A comment is a line  that  is  put  in
  1106.       for  a  human  to  read  and  is  ignored by the computer.  In TIPI,
  1107.       anything after the # symbol on a line is ignored by the computer.
  1108.  
  1109.       The second line prints the message "Hello  World!"  on  the  screen.
  1110.       The  |  symbol  tells TIPI to take the rest of the line and print it
  1111.       out.
  1112.  
  1113.       The last three lines form a loop  that  will  wait  until  the  user
  1114.       presses  a  key.   BEGIN  starts the loop.  The KEY instruction will
  1115.       return the keycode of whatever key is pressed or zero if no  key  is
  1116.       pressed.   UNTIL will branch back to the BEGIN if the stack value is
  1117.       zero, otherwise execution continues after the UNTIL.   In  the  case
  1118.       of  this  program,  the are no more instructions after the UNTIL, so
  1119.       the program ends.
  1120.  
  1121.       You can run this program by loading it into the workbench by typing
  1122.  
  1123.            t hello
  1124.  
  1125.       at the DOS prompt.  Pressing [R] will run the program and  you  will
  1126.       see  that  the program DOS in fact print out "Hello World!" and wait
  1127.       for you to press a key.
  1128.  
  1129.  
  1130.  
  1131.                                        16
  1132.  
  1133.       Chapter 4. TIPI Programming                                       17
  1134.  
  1135.  
  1136.       4.2 The Basic Principle
  1137.  
  1138.       The main idea in TIPI programming is to break your problem  up  into
  1139.       little  chunks  and  create  instructions to solve the sub-problems.
  1140.       In this way, you not only create a program to solve this  particular
  1141.       problem,   but  a  language  that  is  useful  for  solving  similar
  1142.       problems.
  1143.  
  1144.  
  1145.       4.3 Defining New Instructions
  1146.  
  1147.       Most languages make you conform  to  the  way  the  language  works.
  1148.       With  TIPI, you mold the language to the problem at hand and the way
  1149.       you work.  The sample programs are filled with examples of  ways  to
  1150.       extend the language, but here is a simple sample:
  1151.  
  1152.               # POWERS.TPI
  1153.               # by Kent Peterson
  1154.  
  1155.               # This is a simple program to demonstrate
  1156.               # how easy it is to add new instructions
  1157.               # to TIPI.
  1158.  
  1159.               define square ( n -- n*n )
  1160.               # Squares a number
  1161.                dup *
  1162.               enddef
  1163.  
  1164.               define cube ( n -- n*n*n )
  1165.               # Cubes a number
  1166.                dup square *
  1167.               enddef
  1168.  
  1169.               define quad ( n -- n*n*n*n )
  1170.               # raises a number to the fourth power
  1171.                square dup *
  1172.               enddef
  1173.  
  1174.               "Enter a number" print$
  1175.               getnum
  1176.               dup square print cr
  1177.               dup cube   print cr
  1178.                   quad   print cr
  1179.               begin key until
  1180.  
  1181.       Notice  that  the  definition "square" is used in the definitions of
  1182.       "cube" and "quad".  Once you define an instruction in your  program,
  1183.       you  can  use  it  just like a built-in TIPI instruction.  When your
  1184.       code executes, TIPI will jump back to where the new instruction  was
  1185.       defined.   If  you  are  running  the  debugger,  you can watch this
  1186.       happen.
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.                                    Chapter 5
  1194.  
  1195.                                      Stacks
  1196.  
  1197.  
  1198.  
  1199.  
  1200.       "If one is master of one thing and understands one thing  well,  one
  1201.       has  at  the  same  time,  insight  into  and  understanding of many
  1202.       things." -- Vincent Van Gogh
  1203.  
  1204.  
  1205.       5.1 A Description of TIPI Stacks
  1206.  
  1207.       Programs need to keep track of  various  details  as  they  execute.
  1208.       These  details  may  be  the  results  of calculations, the names of
  1209.       files, information supplied by the user, etc.
  1210.  
  1211.       Most  traditional  computer  languages  use  "variables"  to   store
  1212.       information.   Variables  are named areas of computer memory and are
  1213.       referenced by name.  TIPI allows  you  to  create  and  use  various
  1214.       kinds  of  variables but most TIPI programming relies on a couple of
  1215.       efficient mechanisms called "stacks".
  1216.  
  1217.       A stack is simply a pile of information.   You  add  information  to
  1218.       the  top  of  the  stack,  one  piece at a time.  When it is time to
  1219.       remove information from the pile, you take information from the  top
  1220.       of the stack, one piece at a time.
  1221.  
  1222.       TIPI has three stacks, which are described below.
  1223.  
  1224.       The  Data Stack -- This stack is the most commonly used.  It is used
  1225.           for storing numbers, the results of  calculations,  and  logical
  1226.           values.
  1227.  
  1228.       The  String  Stack  --  This stack stores strings of character data.
  1229.           In TIPI a string can be up to 80 characters long.
  1230.  
  1231.       The Return Stack -- This stack is used internally by TIPI.   It  may
  1232.           also  be  used  for temporary data storage by using the PUSH and
  1233.           POP instructions
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.                                        18
  1246.  
  1247.       Chapter 5. Stacks                                                 19
  1248.  
  1249.  
  1250.       5.2 Stack Diagrams
  1251.  
  1252.       The bulk of this manual consists of  descriptions  of  each  of  the
  1253.       hundred-odd  built-in TIPI instructions.  These descriptions consist
  1254.       of the name of the instruction, a STACK DIAGRAM which explains  what
  1255.       the  instruction  does to the Data and String stacks, and a sentence
  1256.       or two describing what the instruction does.  Here is an example:
  1257.  
  1258.  
  1259.           MID$                         <-- This is the name of the
  1260.                                            instruction.
  1261.           Data        s l --           <-- These are the stack
  1262.           String      a$  -- b$        <-- diagrams
  1263.  
  1264.           Returns b$, a string of l    <-- This is the description
  1265.           characters starting at
  1266.           position s from a$.
  1267.  
  1268.       What the stack diagrams do is describe  what  the  data  and  string
  1269.       stacks  look  like  before  the instruction executes and right after
  1270.       the instruction executes.  In these diagrams the "--" separates  the
  1271.       "before"  from  the  "after"  and  the top of the stack is the right
  1272.       most entry.  Thus
  1273.  
  1274.           6 2 "TIPI is not BASIC" MID$
  1275.  
  1276.       would extract 2 characters starting at position 6 in  "TIPI  is  not
  1277.       BASIC".   The  result  would  be  the string "is" left on the string
  1278.       stack.
  1279.  
  1280.  
  1281.       5.3 Why You Should Use Stacks
  1282.  
  1283.       One of the best reasons for using the stacks  instead  of  variables
  1284.       is  speed.   Working  with  data on the stack is quicker than always
  1285.       storing and fetching data to and from a variable.
  1286.  
  1287.       Another good reason is convenience.  All of  the  TIPI  instructions
  1288.       are  constructed  to use the stacks.  If you use a lot of variables,
  1289.       you will find yourself doing a lot of unneeded data manipulation.
  1290.  
  1291.       Once you get used to using stacks, you will see that  they  help  an
  1292.       awful  lot  in  making  your  code  modular.   When you define a new
  1293.       instuction, if it only uses stack values, you don't  have  to  worry
  1294.       about bugs cropping up from unintentional changes to variables.
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.                                    Chapter 6
  1302.  
  1303.                                    TIPI Math
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.       6.1 RPN
  1310.  
  1311.       While  many  of  the  instructions in TIPI look very much like BASIC
  1312.       statements, TIPI is in fact quite different  from  BASIC.   Probably
  1313.       the  greatest  difference  between  TIPI  and BASIC is the fact that
  1314.       TIPI uses a syntax known as RPN.   RPN  stands  for  Reverse  Polish
  1315.       Notation  (no,  it's not an ethnic slur.  It refers to the nation of
  1316.       origin of Jan Lukaciewicz, the mathematicians  who  originated  this
  1317.       notation.)
  1318.  
  1319.       RPN  is  used  in  many  Hewlett-Packard calculators, in the display
  1320.       language PostScript, in some CPUs, in Forth and  now  in  TIPI.   To
  1321.       most people, RPN looks backwards, but RPN has many advantages.
  1322.  
  1323.       To  add two plus two in BASIC and print out the result, your program
  1324.       would look something like this:
  1325.  
  1326.               X=2+2
  1327.               PRINT X
  1328.  
  1329.       To do the same thing in TIPI, your program would look like this:
  1330.  
  1331.               2 2 + print
  1332.  
  1333.       It may seem weird, but once you get used  to  RPN,  it  really  does
  1334.       make  things  easier.  For example, when you want to do more complex
  1335.       math, you have to  use  parentheses  in  BASIC  to  make  sure  that
  1336.       everything gets done in just the order you want, like this:
  1337.  
  1338.               X=(6+3)*4/3
  1339.               PRINT X
  1340.  
  1341.       In TIPI you do it like this
  1342.  
  1343.               6 3 + 4 * 3 / print
  1344.               ( parentheses mark comments in TIPI )
  1345.               ( just like they do in English. )
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.                                        20
  1354.  
  1355.       Chapter 6. TIPI Math                                              21
  1356.  
  1357.  
  1358.       6.2 Integer Math
  1359.  
  1360.       TIPI  does all it's math in integer values.  That means you can work
  1361.       with numbers like 6,  -584,  47789329  and  0  but  you  can't  have
  1362.       3.14159  or  6.02^23.   Forth  purists  will tell you that you don't
  1363.       need floating point math.  I'll tell you that TIPI doesn't  have  it
  1364.       because  it  would make TIPI too big and too slow for what I wanted.
  1365.       And the Forth guys are basically right.  I have seen  3-D  animation
  1366.       engines  written  using  only  integer  math and two friends of mine
  1367.       have coded an entire hockey game (including player physics  and  AI)
  1368.       using only integer math.
  1369.  
  1370.       The  TIPI  data  stack  and all its math instructions work with long
  1371.       (32 bit) signed values.  This means that TIPI  can  handle  integers
  1372.       from  -2,147,483,648  to  2,147,483,647.   This is a very wide range
  1373.       and with some creative scaling, you should be able to handle  almost
  1374.       any  problem  that  you  might  have  thought would require floating
  1375.       point math.  If I get a huge number  of  registrations  and  a  huge
  1376.       number  of  requests  for  floating  point math, a future version of
  1377.       TIPI may include floating point.
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.                                    Chapter 7
  1385.  
  1386.                                    Variables
  1387.  
  1388.  
  1389.  
  1390.  
  1391.       In addition to the data and string  stacks,  TIPI  lets  you  create
  1392.       integer  variables,  integer  arrays and strings.  To use a variable
  1393.       in your program you must first define it.   TIPI  also  has  a  data
  1394.       structure  called  a  TABLE.  The proper use of variables and tables
  1395.       are  illustrated  in  the  program  VARSAMPLE  listed  below.   More
  1396.       information  can be found in the manual sections describing Defining
  1397.       Instructions and Data Instructions.
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.                                        22
  1437.  
  1438.       Chapter 7. Variables                                              23
  1439.  
  1440.  
  1441.  
  1442.           # VARSAMPLE.TPI
  1443.           # by Kent Peterson
  1444.           # This program demonstrates the three
  1445.           # types of variables in TIPI along with
  1446.           # the table data structure.
  1447.  
  1448.           defvar price
  1449.           3 defarray zipcode
  1450.  
  1451.           defstr Man$
  1452.  
  1453.           deftable kid$           # This sets the
  1454.            "Bart" "Lisa" "Maggie" # table kid$ to
  1455.           endtable                # to hold the names
  1456.                                   # of three kids.
  1457.  
  1458.           100 price store         # This stores 100 in
  1459.                                   # the variable price.
  1460.  
  1461.           10605 1 zipcode store   # This stores
  1462.           60609 2 zipcode store   # different zipcodes
  1463.           90210 3 zipcode store   # in each of the
  1464.                                   # three zipcode
  1465.                                   # slots.
  1466.  
  1467.           "Homer" Man$ store      # This stores the
  1468.                                   # word "Homer" in
  1469.                                   # the variable Man$.
  1470.  
  1471.           # Now let's use these variables
  1472.           # and the table
  1473.  
  1474.           "Hi, I'm " print$
  1475.           Man$ fetch print$       # You have to fetch
  1476.                                   # the contents of
  1477.                                   # a variable before
  1478.                                   # you can print it out.
  1479.           "." print$ cr
  1480.  
  1481.  
  1482.           "My kids are named "
  1483.           print$
  1484.           1 kid$ print$           # Tables are initialized
  1485.                                   # when they are defined
  1486.                                   # and they auto-fetch.
  1487.                                   # DO NOT USE A FETCH
  1488.                                   # with a table.
  1489.           ", " print$
  1490.           2 kid$ print$
  1491.           " and " print$
  1492.           3 kid$ print$
  1493.           "." print$ cr cr
  1494.  
  1495.           "My car cost $" print$
  1496.  
  1497.       Chapter 7. Variables                                              24
  1498.  
  1499.  
  1500.           price fetch print
  1501.           "." print$ cr cr
  1502.  
  1503.           "My zipcode is " print$
  1504.           1 zipcode fetch print   # Array values
  1505.                                   # are fetched and
  1506.                                   # and stored using
  1507.                                   # their names and
  1508.                                   # their index values.
  1509.           " but I wish it was "
  1510.           print$
  1511.           3 zipcode fetch print
  1512.           "." print$ cr
  1513.  
  1514.  
  1515.           begin key until     # This sequence of
  1516.                               # instructions waits
  1517.                               # until you press
  1518.                               # a key.
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.                                    Chapter 8
  1527.  
  1528.                                The TIPI Debugger
  1529.  
  1530.  
  1531.  
  1532.  
  1533.       It would be great if we all could write perfect programs  and  never
  1534.       had  programs  bugs.   Unfortunately, that's not the way programming
  1535.       works.   Because  programs  can  have  bugs,  TIPI  has  a  built-in
  1536.       debugger.   The  debugger  is  actually a program tracer and it will
  1537.       help you track down bugs and give you a view of  what  is  happening
  1538.       as TIPI runs your program.
  1539.  
  1540.       First  off,  let's  run  ERROR.TPI  a  sample  program that contains
  1541.       (gasp) a BUG.  Start the TIPI Programmer's Workbench by typing:
  1542.  
  1543.       T ERROR
  1544.  
  1545.       and pick [R]un from the menu.
  1546.  
  1547.       BAM!  TIPI will display this error message:
  1548.  
  1549.               ERROR!        1
  1550.               Too few stack values with
  1551.               +
  1552.  
  1553.       Pressing any key will show you  the  debugger  screen,  which  looks
  1554.       like this:
  1555.  
  1556.                          +- Data Depth  1 -+- String Depth  0-+
  1557.                          |                2|              ----|
  1558.                          |             ----|              ----|
  1559.                          |             ----|              ----|
  1560.                          |             ----|              ----|
  1561.                          |+                                   |
  1562.                          |3 =                                 |
  1563.                          +------------------------------------+
  1564.  
  1565.       This  is  what's  known  in  the  programming biz as a "post-mortem"
  1566.       dump.  This means that you program is dead and you can't  really  do
  1567.       anything  to  fix it right now.  This screen is just giving you more
  1568.       info about what went wrong.  In this case what went  wrong  was  the
  1569.       program  tried  to  add with only one value on the stack.  The error
  1570.       message told you that, and the debugger came up  to  show  you  just
  1571.       what  you  had  on the stacks.  The debugger displays the data stack
  1572.       on the left, the string stack on the right and the instruction  just
  1573.       executed  below  the data stack.  Below that are the instructions it
  1574.       was about to execute.  In a post-mortem dump, pressing any key  will
  1575.       return you to the Workbench.
  1576.  
  1577.  
  1578.                                        25
  1579.  
  1580.       Chapter 8. The TIPI Debugger                                      26
  1581.  
  1582.  
  1583.       Now  let's  use  the  editor  to  change the program to fix the bug.
  1584.       Here is the program:
  1585.  
  1586.               # ERROR.TPI
  1587.  
  1588.               # This simple program has a
  1589.               # bug in it to show you how
  1590.               # to use the TIPI debugger
  1591.  
  1592.               3 + 2 =
  1593.               "The sum is " print$ print
  1594.  
  1595.       The problem may be fixed by changing the program to read:
  1596.  
  1597.               # ERROR.TPI
  1598.  
  1599.               # This simple program had a
  1600.               # bug in it to show you how
  1601.               # to use the TIPI debugger
  1602.  
  1603.               3 2 +
  1604.               "The sum is " print$ print
  1605.  
  1606.       By moving the "+" after the 2 and getting rid of the  unneeded  "=",
  1607.       the  program is fixed.  Running the program again will show that all
  1608.       is well and our program can perform  the  amazing  (well  maybe  not
  1609.       amazing!) feat of adding two integers.
  1610.  
  1611.       But  wait,  what  if  we wanted to see more of what's going on?  You
  1612.       can do this by invoking the debugger at any point in  your  code  by
  1613.       simply  adding  the  instruction  "TRACEON".   For  example,  if you
  1614.       change our little program to look like this:
  1615.  
  1616.               # ERROR.TPI
  1617.  
  1618.               # This simple program had a
  1619.               # bug in it to show you how
  1620.               # to use the TIPI debugger
  1621.               traceon
  1622.               3 2 +
  1623.               "The sum is " print$ print
  1624.  
  1625.       The debugger will  be  displayed  from  the  start.   You  may  step
  1626.       through  the  program by pressing the [SPACEBAR].  You will see each
  1627.       instuction execute and you can watch what it  does  to  the  stacks.
  1628.       By  watching  a program in this way, you can usually track down bugs
  1629.       in just a few minutes.
  1630.  
  1631.       While tracing a program, the following keys are active:
  1632.  
  1633.       [SPACEBAR] Steps to the next instruction.
  1634.  
  1635.       [ESC] Quits the debugger until another TRACEON command is executed.
  1636.  
  1637.       Chapter 8. The TIPI Debugger                                      27
  1638.  
  1639.  
  1640.       [END] Ends the program.
  1641.  
  1642.       In addition to TRACEON there are instructions for turning the  trace
  1643.       window  off,  placing  the  trace window elsewhere on the screen and
  1644.       for tracing  the  contents  of  variables.   The  following  program
  1645.       illustrates the use of these instructions.
  1646.  
  1647.       This  program  also has a bug that we will track down using the TIPI
  1648.       debugger.
  1649.  
  1650.  
  1651.           # ERROR2.TPI by Kent Peterson 10/1/94
  1652.           # This is another program used to demonstrate the TIPI debugger
  1653.  
  1654.           defvar henry
  1655.           defvar waldo
  1656.  
  1657.           henry tracevar
  1658.           waldo tracevar
  1659.  
  1660.           40 tracecol
  1661.           # traceon
  1662.  
  1663.           300 henry store
  1664.           henry 50 + waldo store
  1665.           waldo print
  1666.  
  1667.       Now the bug in this program is that it doesn't do what  we  want  it
  1668.       to  do.   The goal of the program is to store the value 300 in henry
  1669.       and then store fifty more than the value of  henry  in  waldo.   The
  1670.       result should be 350, but the program will instead display 2.
  1671.  
  1672.       The  problem  is  this  program confuses the name of a variable with
  1673.       its contents.  In the second to the last line, 50 is added to  henry
  1674.       and  not to the contents of henry.  TIPI tracks each variable with a
  1675.       number and since henry is the first variable  in  our  program,  its
  1676.       number  is  one.   Thus  the  second  to  the last line stores 51 in
  1677.       waldo, instead of 350.
  1678.  
  1679.       But wait, why then does the  last  line  print  out  the  number  2?
  1680.       Because  the  last  line  makes  the  same  mistake,  it  confuses a
  1681.       variable with its contents.  To see what's going  on  remove  the  #
  1682.       instuction  from  in  front of the traceon instruction and rerun the
  1683.       program.
  1684.  
  1685.       Now you will see the debugging window, but it  will  look  different
  1686.       than  it  did  in our last example.  For one thing, it is located at
  1687.       the middle of the screen instead of the left edge.   That's  because
  1688.       the  line  that  says  "40  tracecol"  tells TIPI to place it there.
  1689.       Also the tracewindow is displaying henry and waldo because  we  have
  1690.       told TIPI to use those two variables as TRACEVARs.
  1691.  
  1692.       As  you  step  through the program, you will see the values of henry
  1693.       and waldo change along with the stack  values.   You  will  see  the
  1694.       problem and then you can end the debugger.
  1695.  
  1696.       Chapter 8. The TIPI Debugger                                      28
  1697.  
  1698.  
  1699.       If you change the program to read
  1700.  
  1701.  
  1702.           # ERROR2.TPI by Kent Peterson 10/1/94
  1703.           # This is another program used to demonstrate the TIPI debugger
  1704.  
  1705.           defvar henry
  1706.           defvar waldo
  1707.  
  1708.           henry tracevar
  1709.           waldo tracevar
  1710.  
  1711.           40 tracecol
  1712.           traceon
  1713.  
  1714.           300 henry store
  1715.           henry fetch 50 + waldo store
  1716.           waldo fetch print
  1717.  
  1718.       you  will see that the program behaves properly.  Once a program has
  1719.       been completely  debugged,  all  of  the  tracing  commands  can  be
  1720.       removed.   In  fact,  If  you wish to use TIPI's MAKEEXE option, the
  1721.       tracing commands MUST be removed because tracing  is  not  supported
  1722.       by the MAKEEXE option.
  1723.  
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.                                    Chapter 9
  1730.  
  1731.                     Common mistakes of new TIPI Programmers
  1732.  
  1733.  
  1734.  
  1735.  
  1736.         . The  number  one  mistake  would have to be stack errors.  Study
  1737.           the samples and learn RPN.  IT IS WORTH IT.  Your code won't  be
  1738.           cluttered  with  parentheses and the instructions will flow in a
  1739.           logical order.  The debugger will help a lot.
  1740.  
  1741.         . Another common mistake is confusing the name of a variable  with
  1742.           the  contents of a variable.  If you have a variable named FRED,
  1743.           FRED is just it's name.  FRED FETCH is how  you  fetch  a  value
  1744.           and FRED STORE is how you store a value.
  1745.  
  1746.         . Forgetting  to  end a DEFINE.  When TIPI sees a DEFINE, it looks
  1747.           for the matching ENDDEF.  If you don't have a match  ENDDEF  (or
  1748.           you misspell it) TIPI gets very confused.
  1749.  
  1750.         . Forgetting  to  leave white space around TIPI instructions.  The
  1751.           one that is most commonly screwed up is the "(".  In  TIPI  make
  1752.           your comments
  1753.  
  1754.                   ( Look like this. )
  1755.                    (Not like this.)
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.  
  1781.                                        29
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.                                    Chapter 10
  1789.  
  1790.                                 Notes and Limits
  1791.  
  1792.  
  1793.  
  1794.  
  1795.       "When  they  feel  cheated because I just ignore all those bells and
  1796.       whistles, I can only answer: "Are you  quite  sure  that  all  those
  1797.       bells   and   whistles,  all  those  wonderful  facilities  of  your
  1798.       so-called "powerful" programming languages belong  to  the  solution
  1799.       set  rather  than  to  the problem set?"." -- Edsger W.  Dijkstra "A
  1800.       Discipline of Programming"
  1801.  
  1802.         . TIPI is case insensitive.  This means that MAX, max and Max  all
  1803.           refer to the same instruction.
  1804.  
  1805.         . TIPI  uses  vectored  I/O.   This  means  that  all  of  the I/O
  1806.           commands can be directed to/from files, the  console,  printers,
  1807.           etc.  See the commands ISINPUT and ISOUTPUT for details.
  1808.  
  1809.         . Strings are limited to a maximum of 80 characters.
  1810.  
  1811.         . The maximum depths for the data and return stacks are 80.
  1812.  
  1813.         . The maximum depth of the string stack is 32.
  1814.  
  1815.         . The maximum number of named variables is 100.
  1816.  
  1817.         . The maximum number of array elements is a total of 1000.
  1818.  
  1819.         . The maximum number of trace variables is 10.
  1820.  
  1821.         . The maximum number of user-defined instructions is 100.
  1822.  
  1823.         . The maximum size of a TIPI source (.TPI) file is 32K.
  1824.  
  1825.         . TIPI  always  searches  it's  internal  dictionary  first,  then
  1826.           searches for new instructions in the order in  which  they  were
  1827.           defined.
  1828.  
  1829.         . An instruction must be defined before it is used.
  1830.  
  1831.         . IF...ELSE...ENDIF constructs may be nested but
  1832.           CASE...OF...ENDOF   and   CASE$...OF$...ENDOF$   should  NOT  be
  1833.           nested.  If you feel you must nest CASE  statements,  place  the
  1834.           internal CASEs in their own DEFINEs.
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.                                        30
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.                                    Chapter 11
  1848.  
  1849.                               Control Instructions
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.       11.1 BEGIN
  1856.  
  1857.  
  1858.           Data Stack:   --
  1859.  
  1860.           String Stack: --
  1861.  
  1862.       Starts  a  BEGIN UNTIL loop.  When TIPI encounters an UNTIL, it will
  1863.       branch back to the BEGIN if the value on the data stack is FALSE.
  1864.  
  1865.       -----------------------------------------------------------
  1866.  
  1867.  
  1868.       11.2 CASE
  1869.  
  1870.  
  1871.           Data Stack:   --
  1872.  
  1873.           String Stack: --
  1874.  
  1875.       Begins a CASE structure.
  1876.  
  1877.       -----------------------------------------------------------
  1878.  
  1879.  
  1880.       11.3 CASE$
  1881.  
  1882.  
  1883.           Data Stack:   --
  1884.  
  1885.           String Stack: --
  1886.  
  1887.       Begins a CASE$ structure.
  1888.  
  1889.       -----------------------------------------------------------
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.                                        31
  1900.  
  1901.       Chapter 11. Control Instructions                                  32
  1902.  
  1903.  
  1904.       11.4 DEFAULT
  1905.  
  1906.  
  1907.           Data Stack:    n --
  1908.  
  1909.           String Stack:    --
  1910.  
  1911.       Used within a CASE structure to cover any cases not  dealt  with  by
  1912.       previous OF clauses.
  1913.  
  1914.       -----------------------------------------------------------
  1915.  
  1916.  
  1917.       11.5 DEFAULT$
  1918.  
  1919.  
  1920.           Data Stack:        --
  1921.  
  1922.           String Stack:   a$ --
  1923.  
  1924.       Used  within  a CASE$ structure to cover any cases not dealt with by
  1925.       previous OF$ clauses.
  1926.  
  1927.       -----------------------------------------------------------
  1928.  
  1929.  
  1930.       11.6 DO
  1931.  
  1932.  
  1933.           Data Stack:     N --
  1934.  
  1935.           String Stack:     --
  1936.  
  1937.       Begins a DO loop.  Processing continues until a LOOP instruction  is
  1938.       encountered.  The loop will be executed N times.
  1939.  
  1940.       -----------------------------------------------------------
  1941.  
  1942.  
  1943.       11.7 ELSE
  1944.  
  1945.  
  1946.           Data Stack:     --
  1947.  
  1948.           String Stack:   --
  1949.  
  1950.       Used within IF ELSE ENDIF constructs.
  1951.  
  1952.       -----------------------------------------------------------
  1953.  
  1954.       Chapter 11. Control Instructions                                  33
  1955.  
  1956.  
  1957.       11.8 ENDCASE
  1958.  
  1959.  
  1960.           Data Stack:     --
  1961.  
  1962.           String Stack:   --
  1963.  
  1964.       Ends a CASE structure.
  1965.  
  1966.       -----------------------------------------------------------
  1967.  
  1968.  
  1969.       11.9 ENDCASE$
  1970.  
  1971.  
  1972.           Data Stack:     --
  1973.           String Stack:   --
  1974.  
  1975.       Ends a CASE$ structure.
  1976.  
  1977.       -----------------------------------------------------------
  1978.  
  1979.  
  1980.       11.10 ENDIF
  1981.  
  1982.  
  1983.           Data Stack:     --
  1984.           String Stack:   --
  1985.  
  1986.       Ends an IF ELSE ENDIF construct.
  1987.  
  1988.       -----------------------------------------------------------
  1989.  
  1990.  
  1991.       11.11 ENDOF
  1992.  
  1993.  
  1994.           Data Stack:     --
  1995.           String Stack:   --
  1996.  
  1997.       Ends an OF clause in a CASE structure.
  1998.  
  1999.       -----------------------------------------------------------
  2000.  
  2001.  
  2002.       11.12 ENDOF$
  2003.  
  2004.  
  2005.           Data Stack:     --
  2006.           String Stack:   --
  2007.  
  2008.       Ends an OF$ clause in a CASE$ structure.
  2009.  
  2010.       -----------------------------------------------------------
  2011.  
  2012.       Chapter 11. Control Instructions                                  34
  2013.  
  2014.  
  2015.       11.13 IF
  2016.  
  2017.  
  2018.           Data Stack:     n --
  2019.           String Stack:     --
  2020.  
  2021.       If  n is non-zero, instructions up to the next ELSE or ENDIF will be
  2022.       executed.  If n is zero, instructions up to the next ELSE  or  ENDIF
  2023.       will be skipped.
  2024.  
  2025.       -----------------------------------------------------------
  2026.  
  2027.  
  2028.       11.14 INDEX
  2029.  
  2030.  
  2031.           Data Stack:      -- index
  2032.           String Stack:    --
  2033.  
  2034.       Copies the current DO LOOP index value to the data stack.
  2035.  
  2036.       -----------------------------------------------------------
  2037.  
  2038.  
  2039.       11.15 LEAVE
  2040.  
  2041.  
  2042.           Data Stack:      --
  2043.           String Stack:    --
  2044.  
  2045.       Sets  the  current  INDEX value to one, thus ensuring the current DO
  2046.       LOOP will be ended on this itteration.
  2047.  
  2048.       -----------------------------------------------------------
  2049.  
  2050.  
  2051.       11.16 LOOP
  2052.  
  2053.  
  2054.           Data Stack:      --
  2055.           String Stack:    --
  2056.  
  2057.       Closes a DO LOOP construct.  Decrements INDEX and loops back to  the
  2058.       DO if INDEX > 0, otherwise exits the loop.
  2059.  
  2060.       -----------------------------------------------------------
  2061.  
  2062.       Chapter 11. Control Instructions                                  35
  2063.  
  2064.  
  2065.       11.17 OF
  2066.  
  2067.  
  2068.           Data Stack:      m n --
  2069.           String Stack:        --
  2070.  
  2071.       Must  be  used  within  a  CASE  structure.  If m is equal to n, the
  2072.       instructions following the OF will be executed  until  an  ENDOF  is
  2073.       encountered.
  2074.  
  2075.       -----------------------------------------------------------
  2076.  
  2077.  
  2078.       11.18 OF$
  2079.  
  2080.  
  2081.           Data Stack:            --
  2082.           String Stack:    a$ b$ --
  2083.  
  2084.       Must  be  used  within a CASE$ structure.  If a$ is equal to b$, the
  2085.       instructions following the OF$ will be executed until an  ENDOF$  is
  2086.       encountered.
  2087.  
  2088.       -----------------------------------------------------------
  2089.  
  2090.  
  2091.       11.19 UNTIL
  2092.  
  2093.  
  2094.           Data Stack:          N --
  2095.           String Stack:          --
  2096.  
  2097.       Branches back to BEGIN if N is FALSE, otherwise continues.
  2098.  
  2099.       -----------------------------------------------------------
  2100.  
  2101.  
  2102.       11.20 WEND
  2103.  
  2104.  
  2105.           Data Stack:            --
  2106.           String Stack:          --
  2107.  
  2108.       WEND branches back to a previous WHILE.
  2109.  
  2110.       -----------------------------------------------------------
  2111.  
  2112.       Chapter 11. Control Instructions                                  36
  2113.  
  2114.  
  2115.       11.21 WHILE
  2116.  
  2117.  
  2118.           Data Stack:          n --
  2119.           String Stack:          --
  2120.  
  2121.       If  n  is  not equal to zero, instructions between the WHILE and the
  2122.       WEND will be executed.  WEND will branch back to the  WHILE.   If  n
  2123.       is  equal  to  zero,  execution  branches  to  then next instruction
  2124.       following the next WEND.
  2125.  
  2126.       -----------------------------------------------------------
  2127.  
  2128.  
  2129.  
  2130.  
  2131.  
  2132.  
  2133.                                    Chapter 12
  2134.  
  2135.                                Data Instructions
  2136.  
  2137.  
  2138.  
  2139.  
  2140.  
  2141.       12.1 FETCH
  2142.  
  2143.  
  2144.           Data Stack:         v -- x (if numeric)
  2145.           String Stack:         -- x$ (if string)
  2146.  
  2147.       Returns the contents of variable v.   The  type  of  v  (numeric  or
  2148.       string)  determines  if  the  contents of the fetch is placed on the
  2149.       data or the string stack.
  2150.  
  2151.       -----------------------------------------------------------
  2152.  
  2153.  
  2154.       12.2 STORE
  2155.  
  2156.  
  2157.           Data Stack:         n v -- (if numeric)    v -- (if string)
  2158.           String Stack:           --                s$ --
  2159.  
  2160.       Stores a value into a variable.  The type of v (numeric  or  string)
  2161.       determines  if  the  contents of the store is taken from the data or
  2162.       the string stack.
  2163.  
  2164.       -----------------------------------------------------------
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.  
  2184.  
  2185.                                        37
  2186.  
  2187.  
  2188.  
  2189.  
  2190.  
  2191.  
  2192.                                    Chapter 13
  2193.  
  2194.                              Debugging Instructions
  2195.  
  2196.  
  2197.  
  2198.  
  2199.  
  2200.       13.1 TRACECOL
  2201.  
  2202.  
  2203.           Data Stack:         col --
  2204.           String Stack:           --
  2205.  
  2206.       Sets the column that the trace window will be shown on.
  2207.  
  2208.       -----------------------------------------------------------
  2209.  
  2210.  
  2211.       13.2 TRACEOFF
  2212.  
  2213.  
  2214.           Data Stack:             --
  2215.           String Stack:           --
  2216.  
  2217.       Turns instruction tracing off.
  2218.  
  2219.       -----------------------------------------------------------
  2220.  
  2221.  
  2222.       13.3 TRACEON
  2223.  
  2224.  
  2225.           Data Stack:             --
  2226.           String Stack:           --
  2227.  
  2228.       Turns instruction tracing on.  When instruction tracing is on,  TIPI
  2229.       displays  an  informational window showing the stacks, any TRACEVARs
  2230.       and the instructions being executed.
  2231.  
  2232.       -----------------------------------------------------------
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.                                        38
  2245.  
  2246.       Chapter 13. Debugging Instructions                                39
  2247.  
  2248.  
  2249.       13.4 TRACEROW
  2250.  
  2251.  
  2252.           Data Stack:            row --
  2253.           String Stack:              --
  2254.  
  2255.       Sets the row that the trace window will be shown on.
  2256.  
  2257.       -----------------------------------------------------------
  2258.  
  2259.  
  2260.       13.5 TRACEVAR
  2261.  
  2262.  
  2263.           Data Stack:            var --
  2264.           String Stack:              --
  2265.  
  2266.       Adds a var to the trace window.
  2267.  
  2268.       -----------------------------------------------------------
  2269.  
  2270.  
  2271.  
  2272.  
  2273.  
  2274.  
  2275.                                    Chapter 14
  2276.  
  2277.                              Defining Instructions
  2278.  
  2279.  
  2280.  
  2281.  
  2282.  
  2283.       14.1 DEFARRAY
  2284.  
  2285.  
  2286.           Data Stack:          N --
  2287.           String Stack:          --
  2288.  
  2289.       Creates an integer array of N elements.  The word after DEFARRAY  is
  2290.       used  as  the name of the array.  For example, 10 DEFARRAY BOB would
  2291.       create a 10 element array named BOB.   When  using  STORE  or  FETCH
  2292.       with  ARRAY variables, you must precede the ARRAY name with a number
  2293.       indicating the element to which you are referring.  For  example,  3
  2294.       BOB  FETCH  will  fetch  the  contents  of the third element of BOB,
  2295.       while 77 5 BOB STORE will will store 77  in  the  fifth  element  of
  2296.       BOB.   TIPI  has  enough array space for a total of up to 1000 array
  2297.       elements in a TIPI program.  TIPI also has a limit of  100  distinct
  2298.       named variables per program.
  2299.  
  2300.       -----------------------------------------------------------
  2301.  
  2302.  
  2303.       14.2 DEFINE
  2304.  
  2305.  
  2306.           Data Stack:             --
  2307.           String Stack:           --
  2308.  
  2309.       DEFINE  is used to define new TIPI instructions.  The word following
  2310.       DEFINE is the name of the  new  TIPI  instruction.   Following  this
  2311.       will  be  a  sequence  of  TIPI  instructions  followed  by the word
  2312.       ENDDEF.  Once a new TIPI instructions has been defined,  it  may  be
  2313.       used  just like any of the built-in TIPI instructions.  For example,
  2314.       DEFINE SQUARED DUP * ENDDEF DEFINE CUBED DUP SQUARED *  ENDDEF  will
  2315.       create  two  new  TIPI  instructions,  SQUARED  and CUBED which will
  2316.       respectively square and cube a value on the stack.  Up  to  100  new
  2317.       TIPI instructions may be defined in a TIPI program.
  2318.  
  2319.       -----------------------------------------------------------
  2320.  
  2321.  
  2322.  
  2323.  
  2324.  
  2325.  
  2326.  
  2327.                                        40
  2328.  
  2329.       Chapter 14. Defining Instructions                                 41
  2330.  
  2331.  
  2332.       14.3 DEFSTR
  2333.  
  2334.  
  2335.           Data Stack:             --
  2336.           String Stack:           --
  2337.  
  2338.       Creates  a  new  string  variable.  The word after DEFSTR is used as
  2339.       the name of the string.  For example DEFSTR MARY will create  a  new
  2340.       string  variable  called  MARY.   STORE  and FETCH are used to place
  2341.       values into variables and retrieve them respectively.
  2342.  
  2343.       -----------------------------------------------------------
  2344.  
  2345.  
  2346.       14.4 DEFSTRARRAY
  2347.  
  2348.  
  2349.           Data Stack:          N --
  2350.           String Stack:          --
  2351.  
  2352.       Creates a string array of N elements.  The  word  after  DEFSTRARRAY
  2353.       is  used  as  the  name  of  the array.  For example, 10 DEFSTRARRAY
  2354.       WALLY$ would create a 10 element string array  named  WALLY$.   When
  2355.       using  STORE  or  FETCH  with  ARRAY variables, you must precede the
  2356.       ARRAY name with a number indicating the element  to  which  you  are
  2357.       referring.   For  example, 3 WALLY$ FETCH will fetch the contents of
  2358.       the third element of WALLY$,  while  "Hello"  5  WALLY$  STORE  will
  2359.       store  "Hello"  in  the  fifth  element  of WALLY$.  TIPI has enough
  2360.       string array space for a total of up to 100  string  array  elements
  2361.       in  a  TIPI  program.   TIPI  also has a limit of 100 distinct named
  2362.       variables per program.
  2363.  
  2364.       -----------------------------------------------------------
  2365.  
  2366.  
  2367.       14.5 DEFTABLE
  2368.  
  2369.  
  2370.           Data Stack:             --
  2371.           String Stack:           --
  2372.  
  2373.       Creates a new data table.  The word after DEFTABLE is  used  as  the
  2374.       name  of  the  table.   For example, DEFTABLE FRED will create a new
  2375.       table called FRED.  Following the name will be a series  of  numbers
  2376.       or  TIPI instructions followed by the instruction ENDTABLE.  After a
  2377.       table has  been  defined,  any  instruction  in  the  table  may  be
  2378.       executed  by  preceding  the  table  name  with  the  number  of the
  2379.       instruction to execute.  For  example,  4  FRED  would  execute  the
  2380.       fourth instruction in FRED.
  2381.  
  2382.       -----------------------------------------------------------
  2383.  
  2384.       Chapter 14. Defining Instructions                                 42
  2385.  
  2386.  
  2387.       14.6 DEFVAR
  2388.  
  2389.  
  2390.           Data Stack:            --
  2391.           String Stack:          --
  2392.  
  2393.       Creates  a  new  numeric variable.  The word after DEFVAR is used as
  2394.       the name of the variable.  For example, DEFVAR HERB  will  create  a
  2395.       new  variable called HERB.  STORE and FETCH are used to place values
  2396.       into variables and retrieve them respectively.
  2397.  
  2398.       -----------------------------------------------------------
  2399.  
  2400.  
  2401.       14.7 ENDDEF
  2402.  
  2403.  
  2404.           Data Stack:            --
  2405.           String Stack:          --
  2406.  
  2407.       Ends an instruction definition.
  2408.  
  2409.       -----------------------------------------------------------
  2410.  
  2411.  
  2412.       14.8 ENDTABLE
  2413.  
  2414.  
  2415.           Data Stack:            --
  2416.           String Stack:          --
  2417.  
  2418.       Ends a table structure.
  2419.  
  2420.       -----------------------------------------------------------
  2421.  
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.                                    Chapter 15
  2428.  
  2429.                                 DOS Instructions
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.       15.1 CALL
  2436.  
  2437.  
  2438.           Data Stack:                               --
  2439.           String Stack:             program$ param$ --
  2440.  
  2441.       Calls a DOS program (program$) with the parameter given  in  param$.
  2442.       Sets  ERROR  to 255 if the call is unsuccessful.  Otherwise ERROR is
  2443.       set to zero unless the called DOS  program  returns  its  own  error
  2444.       code.  Call COMMAND.COM to run batch files.
  2445.  
  2446.       -----------------------------------------------------------
  2447.  
  2448.  
  2449.       15.2 CHDIR
  2450.  
  2451.  
  2452.           Data Stack:                --
  2453.           String Stack:         dir$ --
  2454.  
  2455.       Changes  the  current  DOS directory to the one specified by the top
  2456.       string on the string stack.
  2457.  
  2458.       -----------------------------------------------------------
  2459.  
  2460.  
  2461.       15.3 COMMAND$
  2462.  
  2463.  
  2464.           Data Stack:           --
  2465.           String Stack:         -- Command$
  2466.  
  2467.       Places a string on the string stack consisting of what followed  the
  2468.       word TIPI on the DOS command line when TIPI was invoked.
  2469.  
  2470.       -----------------------------------------------------------
  2471.  
  2472.  
  2473.  
  2474.  
  2475.  
  2476.  
  2477.  
  2478.  
  2479.                                        43
  2480.  
  2481.       Chapter 15. DOS Instructions                                      44
  2482.  
  2483.  
  2484.       15.4 ENV$
  2485.  
  2486.  
  2487.           Data Stack:          N --
  2488.           String Stack:          -- E$
  2489.  
  2490.       ENV$  retrieves  DOS environment strings.  N identifies which string
  2491.       to retrieve.  If the string is not found,  a  null  string  ("")  is
  2492.       returned.   If  the environment string is longer than 80 characters,
  2493.       TIPI will only return the first 80 characters in the string.
  2494.  
  2495.       -----------------------------------------------------------
  2496.  
  2497.  
  2498.       15.5 FIRSTFILE
  2499.  
  2500.  
  2501.           Data Stack:                   --
  2502.           String Stack:       filespec$ -- fname$
  2503.  
  2504.       Finds the first file that matches filespec$.  Filespec$ follows  the
  2505.       standard  DOS wildcard rules (ie the filespec can contain "*" or "?"
  2506.       characters).
  2507.  
  2508.       -----------------------------------------------------------
  2509.  
  2510.  
  2511.       15.6 GETDIR
  2512.  
  2513.  
  2514.           Data Stack:          num --
  2515.           String Stack:            -- dir$
  2516.  
  2517.       GETDIR is used to get the  current  directory.   If  num  =  0  then
  2518.       GETDIR  returns  the  directory  of  the current drive.  If num is 1
  2519.       GETDIR uses the A drive, 2 uses the  B  drive  etc.   The  directory
  2520.       returned  does NOT contain the drive letter or the first "\".  Thus,
  2521.       if the current directory  is  the  root  directory,  0  GETDIR  will
  2522.       return a null string ("").
  2523.  
  2524.       -----------------------------------------------------------
  2525.  
  2526.  
  2527.       15.7 KILL
  2528.  
  2529.  
  2530.           Data Stack:                   --
  2531.           String Stack:       filespec$ --
  2532.  
  2533.       Kills the specified file.
  2534.  
  2535.       -----------------------------------------------------------
  2536.  
  2537.       Chapter 15. DOS Instructions                                      45
  2538.  
  2539.  
  2540.       15.8 MAKEDIR
  2541.  
  2542.  
  2543.           Data Stack:                   --
  2544.           String Stack:        dirspec$ --
  2545.  
  2546.       Makes  the  directory  specified in dirspec$.  If there is an error,
  2547.       the system variable ERROR will be set.
  2548.  
  2549.       -----------------------------------------------------------
  2550.  
  2551.  
  2552.       15.9 NEXTFILE
  2553.  
  2554.  
  2555.           Data Stack:            --
  2556.           String Stack:          -- file$
  2557.  
  2558.       Returns the next file that matches the filespec set  by  a  previous
  2559.       FIRSTFILE  command.   If  there  are  no  more  files  matching  the
  2560.       filespec, the null string ("") is returned.
  2561.  
  2562.       -----------------------------------------------------------
  2563.  
  2564.  
  2565.       15.10 REMDIR
  2566.  
  2567.  
  2568.           Data Stack:               --
  2569.           String Stack:        dir$ --
  2570.  
  2571.       Removes the directory dir$.  The directory should  be  empty  before
  2572.       you  delete  it.  If REMDIR fails, the system variable ERROR will be
  2573.       set.
  2574.  
  2575.       -----------------------------------------------------------
  2576.  
  2577.  
  2578.       15.11 RENAME
  2579.  
  2580.  
  2581.           Data Stack:                            --
  2582.           String Stack:        oldname$ newname$ --
  2583.  
  2584.       Renames a file.
  2585.  
  2586.       -----------------------------------------------------------
  2587.  
  2588.  
  2589.  
  2590.  
  2591.  
  2592.  
  2593.                                    Chapter 16
  2594.  
  2595.                              Graphics Instructions
  2596.  
  2597.  
  2598.  
  2599.  
  2600.  
  2601.       16.1 DRAWLINE
  2602.  
  2603.  
  2604.           Data Stack:          row col --
  2605.           String Stack:                --
  2606.  
  2607.       Draws a line from the current pen location to row, col.
  2608.  
  2609.       HP only.
  2610.  
  2611.       -----------------------------------------------------------
  2612.  
  2613.  
  2614.       16.2 DRAWRECT
  2615.  
  2616.  
  2617.           Data Stack:        fill row col --
  2618.           String Stack:                   --
  2619.  
  2620.       Draws a rectangle from the current pen location  to  row,  col.   If
  2621.       fill  is 1 the rectangle is drawn filled.  If not the rectangle will
  2622.       be drawn unfilled.
  2623.  
  2624.       HP only.
  2625.  
  2626.       -----------------------------------------------------------
  2627.  
  2628.  
  2629.       16.3 GETFONT
  2630.  
  2631.  
  2632.           Data Stack:           height width -- HiFontID LoFontID
  2633.           String Stack:                      --
  2634.  
  2635.       Returns the font ID of a font whose characters are  height  *  width
  2636.       pixels.
  2637.  
  2638.       HP only.
  2639.  
  2640.       -----------------------------------------------------------
  2641.  
  2642.  
  2643.  
  2644.  
  2645.                                        46
  2646.  
  2647.       Chapter 16. Graphics Instructions                                 47
  2648.  
  2649.  
  2650.       16.4 GETPOINT
  2651.  
  2652.  
  2653.           Data Stack:                row col -- color
  2654.           String Stack:                      --
  2655.  
  2656.       Returns the color of the point at row, col.
  2657.  
  2658.       HP only.
  2659.  
  2660.       -----------------------------------------------------------
  2661.  
  2662.  
  2663.       16.5 MOVEPEN
  2664.  
  2665.  
  2666.           Data Stack:                row col --
  2667.           String Stack:                      --
  2668.  
  2669.       Moves the pen to row col.
  2670.  
  2671.       HP only.
  2672.  
  2673.       -----------------------------------------------------------
  2674.  
  2675.  
  2676.       16.6 PLOTICON
  2677.  
  2678.  
  2679.           Data Stack:            rule row col --
  2680.           String Stack:                 icon$ --
  2681.  
  2682.       Plots  an  HP  icon  (.icn)  file  at location row, col according to
  2683.       rule.  The screen should have been set to a graphics  mode  and  row
  2684.       and  col  are given in pixels.  Row and col are the locations of the
  2685.       top left corner of the icon and rule should be set according to  the
  2686.       following table.
  2687.  
  2688.  
  2689.           0 FORCE
  2690.           1 AND
  2691.           2 OR
  2692.           3 XOR
  2693.           4 Invert the image and then FORCE
  2694.           5 Invert the image and then AND
  2695.           6 Invert the image and then OR
  2696.           7 Invert the image and then XOR
  2697.  
  2698.       HP only.
  2699.  
  2700.       -----------------------------------------------------------
  2701.  
  2702.       Chapter 16. Graphics Instructions                                 48
  2703.  
  2704.  
  2705.       16.7 PLOTPOINT
  2706.  
  2707.  
  2708.           Data Stack:                  row col --
  2709.           String Stack:                        --
  2710.  
  2711.       Plots a point at row, col.
  2712.  
  2713.       HP only.
  2714.  
  2715.       -----------------------------------------------------------
  2716.  
  2717.  
  2718.       16.8 PLOTTEXT
  2719.  
  2720.  
  2721.           Data Stack:             Rflag Row Col --
  2722.           String Stack:                   Text$ --
  2723.  
  2724.       Plots  Text$  at  Row, Col in the current font.  If Rflag is 0, text
  2725.       is plotted  horizontally.   If  Rflag  is  1,  text  is  rotated  90
  2726.       degrees.
  2727.  
  2728.       HP only.
  2729.  
  2730.       -----------------------------------------------------------
  2731.  
  2732.  
  2733.       16.9 SCREEN
  2734.  
  2735.  
  2736.           Data Stack:               Mode --
  2737.           String Stack:                  --
  2738.  
  2739.       Sets  the  screen  mode  of  a  PC according to Mode.  The following
  2740.       table gives values for mode.
  2741.  
  2742.  
  2743.           Mode  Graphics Res.   Text Res.   Adapters
  2744.           ----  -------------   ---------   --------
  2745.            0    None            25*80*16    Any
  2746.            1    200*320*4       25*40*4     CGA/EGA/VGA
  2747.            2    200*640*2       25*80*2     CGA/EGA/VGA
  2748.            7    200*320*16      25*40*16    EGA/VGA
  2749.            9    350*640*16      25*80*16    EGA/VGA
  2750.            13   200*320*256     25*40*16    VGA
  2751.  
  2752.       -----------------------------------------------------------
  2753.  
  2754.       Chapter 16. Graphics Instructions                                 49
  2755.  
  2756.  
  2757.       16.10 SCROLL
  2758.  
  2759.  
  2760.           Data Stack:        Dir Row Col Color Distance --
  2761.           String Stack:                                 --
  2762.  
  2763.       Scrolls a rectangular region of the screen.  The region  is  defined
  2764.       from  the  current pen position to Row, Col.  Distance is the number
  2765.       of pixels to scroll.  Dir controls the direction of the  scroll  and
  2766.       Color controls whether bits scrolled "in" are set or cleared.
  2767.  
  2768.       HP only.
  2769.  
  2770.       -----------------------------------------------------------
  2771.  
  2772.  
  2773.       16.11 SETCLIP
  2774.  
  2775.  
  2776.           Data Stack:       MinRow MinCol MaxRow MaxCol --
  2777.           String Stack:                                 --
  2778.  
  2779.       Sets the graphics clipping region.
  2780.  
  2781.       HP only.
  2782.  
  2783.       -----------------------------------------------------------
  2784.  
  2785.  
  2786.       16.12 SETFONT
  2787.  
  2788.  
  2789.           Data Stack:       HiFontID LoFontID --
  2790.           String Stack:                       --
  2791.  
  2792.       Sets a font for use in graphics modes.
  2793.  
  2794.       HP only.
  2795.  
  2796.       -----------------------------------------------------------
  2797.  
  2798.  
  2799.       16.13 SETLINETYPE
  2800.  
  2801.  
  2802.           Data Stack:             Type --
  2803.           String Stack:                --
  2804.  
  2805.       Sets a line type for graphics plotting.
  2806.  
  2807.       HP only.
  2808.  
  2809.       -----------------------------------------------------------
  2810.  
  2811.       Chapter 16. Graphics Instructions                                 50
  2812.  
  2813.  
  2814.       16.14 SETLOGORG
  2815.  
  2816.  
  2817.           Data Stack:            Row Col --
  2818.           String Stack:                  --
  2819.  
  2820.       Sets  the  logical  origin to Row, Col.  The logical coordinates are
  2821.       set  off  the  actual  physical  screen.   Any   future   coordinate
  2822.       operations  are  given  relative  to  the logical origin.  SETLOGORG
  2823.       resets the CLIP REGION to the entire physical screen.
  2824.  
  2825.       HP only.
  2826.  
  2827.       -----------------------------------------------------------
  2828.  
  2829.  
  2830.       16.15 SETPENCOLOR
  2831.  
  2832.  
  2833.           Data Stack:              Color --
  2834.           String Stack:                  --
  2835.  
  2836.       Sets the pen color for graphics drawing commands.
  2837.  
  2838.       HP only.
  2839.  
  2840.       -----------------------------------------------------------
  2841.  
  2842.  
  2843.       16.16 SETREPRULE
  2844.  
  2845.  
  2846.           Data Stack:               Rule --
  2847.           String Stack:                  --
  2848.  
  2849.       Sets the  graphics  replacement  rule  according  to  the  following
  2850.       table:
  2851.  
  2852.  
  2853.              0 = FORCE
  2854.              1 = AND
  2855.              2 = OR
  2856.              3 = XOR
  2857.              8 = FORCETEXT
  2858.  
  2859.       HP only.
  2860.  
  2861.       -----------------------------------------------------------
  2862.  
  2863.       Chapter 16. Graphics Instructions                                 51
  2864.  
  2865.  
  2866.       16.17 SETVMODE
  2867.  
  2868.  
  2869.           Data Stack:              Mode --
  2870.           String Stack:                 --
  2871.  
  2872.       Sets  the  current  video  mode  to alpha or graphics and clears the
  2873.       display.  Mode should be set according to the following table:
  2874.  
  2875.  
  2876.              3  = CGA alpha mode
  2877.              6  = CGA graphics mode 640*200
  2878.              7  = HP95LX alpha
  2879.              32 = HP95LX graphics
  2880.  
  2881.       HP only.
  2882.  
  2883.       -----------------------------------------------------------
  2884.  
  2885.  
  2886.       16.18 ZOOM
  2887.  
  2888.  
  2889.           Data Stack:             Z --
  2890.           String Stack:             --
  2891.  
  2892.       Changes the zoom mode of the HP100LX.  Z should be set according  to
  2893.       the following table:
  2894.  
  2895.  
  2896.              2   = 80*25 BW
  2897.              3   = 80*25 Color
  2898.              7   = 40*16 BW Zoomed
  2899.              33  = 80*25 BW
  2900.              128 = 64*18 BW Zoomed
  2901.              129 = 64*18 Color Zoomed
  2902.              130 = 40*25 BW Zoomed
  2903.              131 = 40*25 Color Zoomed
  2904.              132 = 40*16 BW Zoomed
  2905.              133 = 40*16 Color Zoomed
  2906.  
  2907.       HP only.
  2908.  
  2909.       -----------------------------------------------------------
  2910.  
  2911.  
  2912.  
  2913.  
  2914.  
  2915.  
  2916.                                    Chapter 17
  2917.  
  2918.                                 I/O Instructions
  2919.  
  2920.  
  2921.  
  2922.  
  2923.  
  2924.       17.1 BEEP
  2925.  
  2926.  
  2927.           Data Stack:            --
  2928.           String Stack:          --
  2929.  
  2930.       Produces a short beep.
  2931.  
  2932.       -----------------------------------------------------------
  2933.  
  2934.  
  2935.       17.2 BLOAD
  2936.  
  2937.  
  2938.           Data Stack:           addr count --
  2939.           String Stack:              file$ --
  2940.  
  2941.       Loads  count  bytes  of data to addr from file$.  Addr is an address
  2942.       in the current segment.
  2943.  
  2944.       -----------------------------------------------------------
  2945.  
  2946.  
  2947.       17.3 BSAVE
  2948.  
  2949.  
  2950.           Data Stack:            addr count --
  2951.           String Stack:               file$ --
  2952.  
  2953.       Saves count bytes from addr to file$.  Addr is  an  address  in  the
  2954.       current segment.
  2955.  
  2956.       -----------------------------------------------------------
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.  
  2967.  
  2968.                                        52
  2969.  
  2970.       Chapter 17. I/O Instructions                                      53
  2971.  
  2972.  
  2973.       17.4 CLOSE
  2974.  
  2975.  
  2976.           Data Stack:          N --
  2977.           String Stack:          --
  2978.  
  2979.       Closes file N.  N should be either a 1 or a 2.
  2980.  
  2981.       -----------------------------------------------------------
  2982.  
  2983.  
  2984.       17.5 CLS
  2985.  
  2986.  
  2987.           Data Stack:            --
  2988.           String Stack:          --
  2989.  
  2990.       Clears the screen and places the cursor in the upper left corner.
  2991.  
  2992.       -----------------------------------------------------------
  2993.  
  2994.  
  2995.       17.6 COLOR
  2996.  
  2997.  
  2998.           Data Stack:        Foreground Background --
  2999.           String Stack:                            --
  3000.  
  3001.       Sets  the  foreground  and  background  colors  of  the  screen  for
  3002.       subsequent prints.  Colors are as follows:
  3003.  
  3004.            0 -- Black        8 -- Dark Gray
  3005.            1 -- Blue         9 -- Light Blue
  3006.            2 -- Green       10 -- Light Green
  3007.            3 -- Cyan        11 -- Light Cyan
  3008.            4 -- Red         12 -- Light Red
  3009.            5 -- Magenta     13 -- Light Magenta
  3010.            6 -- Brown       14 -- Yellow
  3011.            7 -- Gray        15 -- White
  3012.  
  3013.       Note -- Background colors 8 to 15 result in blinking text.
  3014.  
  3015.       -----------------------------------------------------------
  3016.  
  3017.  
  3018.       17.7 COLOR?
  3019.  
  3020.  
  3021.           Data Stack:              -- flag
  3022.           String Stack:            --
  3023.  
  3024.       Returns TRUE if a color card is  detected,  FALSE  if  a  monochrome
  3025.       card is detected.
  3026.  
  3027.       Chapter 17. I/O Instructions                                      54
  3028.  
  3029.  
  3030.       -----------------------------------------------------------
  3031.  
  3032.  
  3033.       17.8 COLUMN
  3034.  
  3035.  
  3036.           Data Stack:              -- col
  3037.           String Stack:            --
  3038.  
  3039.       Places the column of the current cursor position on the data stack.
  3040.  
  3041.       -----------------------------------------------------------
  3042.  
  3043.  
  3044.       17.9 COMSTAT
  3045.  
  3046.  
  3047.           Data Stack:          port -- status
  3048.           String Stack:             --
  3049.  
  3050.       Returns  the  status  of a com port.  Port should be 1 or 2.  Status
  3051.       bits as follows:
  3052.  
  3053.           Bit 0  -- Delta CTS
  3054.           Bit 1  -- Delta DSR
  3055.           Bit 2  -- RD
  3056.           Bit 3  -- Delta receive line signal detect
  3057.           Bit 4  -- CTS
  3058.           Bit 5  -- DSR
  3059.           Bit 6  -- Ring Indicator
  3060.           Bit 7  -- Received line signal detect
  3061.           Bit 8  -- Data Ready,
  3062.           Bit 9  -- Overrun error
  3063.           Bit 10 -- Parity Error
  3064.           Bit 11 -- Framing error
  3065.           Bit 12 -- Break detect error
  3066.           Bit 13 -- Transfer holding register empty
  3067.           Bit 14 -- Transfer shift register empty
  3068.           Bit 15 -- Time-out error.
  3069.  
  3070.       -----------------------------------------------------------
  3071.  
  3072.  
  3073.       17.10 CONSOLE
  3074.  
  3075.  
  3076.           Data Stack:                 -- 0
  3077.           String Stack:               --
  3078.  
  3079.       Places the constant 0 on the data stack.   The  CONSOLE  instruction
  3080.       is  used  for clarity.  For example, the sequence CONSOLE ISINPUT is
  3081.       much clearer than 0 ISINPUT.
  3082.  
  3083.       -----------------------------------------------------------
  3084.  
  3085.       Chapter 17. I/O Instructions                                      55
  3086.  
  3087.  
  3088.       17.11 CR
  3089.  
  3090.  
  3091.           Data Stack:                 --
  3092.           String Stack:               --
  3093.  
  3094.       Sends a carriage return to the current output device.
  3095.  
  3096.       -----------------------------------------------------------
  3097.  
  3098.  
  3099.       17.12 CURRENT
  3100.  
  3101.  
  3102.           Data Stack:               -- -2
  3103.           String Stack:             --
  3104.  
  3105.       Places the constant -2 on the  data  stack.   CURRENT  is  used  for
  3106.       clarity.   For  example, 1 CURRENT FILEPOS is much clearer than 1 -2
  3107.       FILEPOS.
  3108.  
  3109.       -----------------------------------------------------------
  3110.  
  3111.  
  3112.       17.13 CURSOR
  3113.  
  3114.  
  3115.           Data Stack:           N --
  3116.           String Stack:           --
  3117.  
  3118.       If N is zero, the cursor will be made invisible.  If N is  non-zero,
  3119.       the  cursor  will  be  made  visible.   WARNING!   Don't execute a 1
  3120.       CURSOR unless you have already executed at least one 0 CURSOR.
  3121.  
  3122.       -----------------------------------------------------------
  3123.  
  3124.  
  3125.       17.14 DEFSEG
  3126.  
  3127.  
  3128.           Data Stack:           N --
  3129.           String Stack:           --
  3130.  
  3131.       DEFSEG is used to define the data segment used  in  subsequent  PEEK
  3132.       and  POKE instructions.  If N is -1, the data segment is set back to
  3133.       TIPI's default data segment address.
  3134.  
  3135.       -----------------------------------------------------------
  3136.  
  3137.       Chapter 17. I/O Instructions                                      56
  3138.  
  3139.  
  3140.       17.15 EOF
  3141.  
  3142.  
  3143.           Data Stack:              -- -1
  3144.           String Stack:            --
  3145.  
  3146.       Places the constant -1 on the data stack.  EOF is used for  clarity.
  3147.       For example, 1 EOF FILEPOS is much clearer than 1 -1 FILEPOS.
  3148.  
  3149.       -----------------------------------------------------------
  3150.  
  3151.  
  3152.       17.16 EXTENDED
  3153.  
  3154.  
  3155.           Data Stack:               -- n
  3156.           String Stack:             --
  3157.  
  3158.       Returns  the contents of the system variable EXTENDED.  This is used
  3159.       in conjunction with INKEY$.  EXTENDED will be 0 if  a  "normal"  key
  3160.       is pressed, 1 if an "extended" key is pressed.
  3161.  
  3162.       -----------------------------------------------------------
  3163.  
  3164.  
  3165.       17.17 FILEPOS
  3166.  
  3167.  
  3168.           Data Stack:       filenum action -- loc
  3169.           String Stack:                    --
  3170.  
  3171.       FILEPOS  is  used  to position and read the value of a file pointer.
  3172.       The filenum is a previously opened file number  (1  or  2)  and  the
  3173.       action  is  either  EOF, CURRENT or a specific location.  The number
  3174.       loc returned on the data stack is the location  in  the  file  where
  3175.       the  next  action  will  occur.  EOF moves the pointer to the end of
  3176.       the file, CURRENT keeps it at its current  position  and  any  other
  3177.       number moves the pointer to that location in the file.
  3178.  
  3179.       -----------------------------------------------------------
  3180.  
  3181.  
  3182.       17.18 GETBYTE
  3183.  
  3184.  
  3185.           Data Stack:            filenum -- byte
  3186.           String Stack:                  --
  3187.  
  3188.       Gets  a  single  byte  from a file whose filenumber is filenum.  The
  3189.       file must have been previously opened and filenum must be  either  1
  3190.       or 2.
  3191.  
  3192.       -----------------------------------------------------------
  3193.  
  3194.       Chapter 17. I/O Instructions                                      57
  3195.  
  3196.  
  3197.       17.19 GETNUM
  3198.  
  3199.  
  3200.           Data Stack:              -- n
  3201.           String Stack:            --
  3202.  
  3203.       Gets a number from the current input device.
  3204.  
  3205.       -----------------------------------------------------------
  3206.  
  3207.  
  3208.       17.20 GETPORT
  3209.  
  3210.  
  3211.           Data Stack:           Port -- Byte
  3212.           String Stack:              --
  3213.  
  3214.       Gets  a  Byte  from  a  serial  port.   Port  may  be either 1 or 2,
  3215.       specifying COM1 or COM2.
  3216.  
  3217.       -----------------------------------------------------------
  3218.  
  3219.  
  3220.       17.21 GETVOL
  3221.  
  3222.  
  3223.           Data Stack:                -- Vol
  3224.           String Stack:              --
  3225.  
  3226.       Gets the system sound volume on an HP100LX.  Vol  may  vary  from  0
  3227.       (silent) to 3 (loudest).
  3228.  
  3229.       -----------------------------------------------------------
  3230.  
  3231.  
  3232.       17.22 GET$
  3233.  
  3234.  
  3235.           Data Stack:                --
  3236.           String Stack:              -- string$
  3237.  
  3238.       Gets a string from the current input device.
  3239.  
  3240.       -----------------------------------------------------------
  3241.  
  3242.       Chapter 17. I/O Instructions                                      58
  3243.  
  3244.  
  3245.       17.23 INKEY$
  3246.  
  3247.  
  3248.           Data Stack:                --
  3249.           String Stack:              -- k$
  3250.  
  3251.       Scans  the  keyboard  and returns a one character string.  If no key
  3252.       is pressed, k$ is null (""), otherwise k$  is  the  character  whose
  3253.       key  was  pressed.   If  an  extended  key  was  pressed, the system
  3254.       variable EXTENDED is set to TRUE.
  3255.  
  3256.       -----------------------------------------------------------
  3257.  
  3258.  
  3259.       17.24 INPORT
  3260.  
  3261.  
  3262.           Data Stack:            Port -- Byte
  3263.           String Stack:               --
  3264.  
  3265.       Gets a Byte from a specific hardware port.  This  is  used  to  read
  3266.       joysticks, etc.
  3267.  
  3268.       -----------------------------------------------------------
  3269.  
  3270.  
  3271.       17.25 ISINPUT
  3272.  
  3273.  
  3274.           Data Stack:                n --
  3275.           String Stack:                --
  3276.  
  3277.       Sets  the current input device to n, where n is either file number 1
  3278.       or 2 or the CONSOLE.  The CONSOLE is device 0.
  3279.  
  3280.       -----------------------------------------------------------
  3281.  
  3282.  
  3283.       17.26 ISOUTPUT
  3284.  
  3285.  
  3286.           Data Stack:                n --
  3287.           String Stack:                --
  3288.  
  3289.       Sets the current output device to n, where n is either filenumber  1
  3290.       or  2,  the PRINTER or the CONSOLE.  The CONSOLE is device 0 and the
  3291.       PRINTER is device 3.
  3292.  
  3293.       -----------------------------------------------------------
  3294.  
  3295.       Chapter 17. I/O Instructions                                      59
  3296.  
  3297.  
  3298.       17.27 KEY
  3299.  
  3300.  
  3301.           Data Stack:             -- k
  3302.           String Stack:           --
  3303.  
  3304.       Scans the keyboard and returns a keycode.  If no key is  pressed,  k
  3305.       is 0.
  3306.  
  3307.       -----------------------------------------------------------
  3308.  
  3309.  
  3310.       17.28 LF
  3311.  
  3312.  
  3313.           Data Stack:             --
  3314.           String Stack:           --
  3315.  
  3316.       Sends a line feed to the current output device.
  3317.  
  3318.       -----------------------------------------------------------
  3319.  
  3320.  
  3321.       17.29 LOCATE
  3322.  
  3323.  
  3324.           Data Stack:         row col --
  3325.           String Stack:               --
  3326.  
  3327.       Places the cursor at row, col.
  3328.  
  3329.       -----------------------------------------------------------
  3330.  
  3331.  
  3332.       17.30 MOUSE
  3333.  
  3334.  
  3335.           Data Stack:         AX BX CX DX -- AX BX CX DX
  3336.           String Stack:                   --
  3337.  
  3338.       Calls the low-level mouse interupt.  See MOUSE.TPI for examples.
  3339.  
  3340.       -----------------------------------------------------------
  3341.  
  3342.  
  3343.       17.31 OPEN
  3344.  
  3345.  
  3346.           Data Stack:             N --
  3347.           String Stack:       T$ F$ --
  3348.  
  3349.       Opens  a file.  N is the file number and N may be either a 1 or a 2.
  3350.       T$ is the type of open and T$ may be either "I",  "O",  "A"  or  "R"
  3351.       which  stand  for  Input, Output, Append or Random respectively.  F$
  3352.       is the name of the file to open.
  3353.  
  3354.       Chapter 17. I/O Instructions                                      60
  3355.  
  3356.  
  3357.       -----------------------------------------------------------
  3358.  
  3359.  
  3360.       17.32 OPENCOM
  3361.  
  3362.  
  3363.           Data Stack:        Baud Parity Stop Size Port --
  3364.           String Stack:                                 --
  3365.  
  3366.       Initializes the  serial  port.   Use  settings  from  the  following
  3367.       tables.
  3368.  
  3369.  
  3370.               Baud                      Parity
  3371.           Value  Description        Value  Description
  3372.           ------------------        ------------------
  3373.             0     110 baud            0     None
  3374.             1     150 baud            1     Odd
  3375.             2     300 baud            3     Even
  3376.             3     600 baud
  3377.             4    1200 baud
  3378.             5    2400 baud
  3379.             6    4800 baud
  3380.             7    9600 baud
  3381.  
  3382.       Stop  may  be  1 or 2, Port may be 1 or 2, Size may be either 7 or 8
  3383.       bits.
  3384.  
  3385.       -----------------------------------------------------------
  3386.  
  3387.  
  3388.       17.33 OUTPORT
  3389.  
  3390.  
  3391.           Data Stack:          Byte Port --
  3392.           String Stack:                  --
  3393.  
  3394.       Sends a Byte out to a port.  Port should be in the range 0 to 255.
  3395.  
  3396.       -----------------------------------------------------------
  3397.  
  3398.  
  3399.       17.34 PEEK
  3400.  
  3401.  
  3402.           Data Stack:          Addr -- Byte
  3403.           String Stack:             --
  3404.  
  3405.       Places the contents of Addr on the data stack.  Addr is  an  address
  3406.       in the current segment.  To change the current segment, use DEFSEG.
  3407.  
  3408.       -----------------------------------------------------------
  3409.  
  3410.       Chapter 17. I/O Instructions                                      61
  3411.  
  3412.  
  3413.       17.35 POKE
  3414.  
  3415.  
  3416.           Data Stack:           Addr Byte --
  3417.           String Stack:                   --
  3418.  
  3419.       Pokes  Byte  into  Addr.  Addr is an address in the current segment.
  3420.       To change the current segment, use DEFSEG.
  3421.  
  3422.       -----------------------------------------------------------
  3423.  
  3424.  
  3425.       17.36 PRINT
  3426.  
  3427.  
  3428.           Data Stack:               n --
  3429.           String Stack:               --
  3430.  
  3431.       Prints the number n on the current output device.
  3432.  
  3433.       -----------------------------------------------------------
  3434.  
  3435.  
  3436.       17.37 PRINTCHR
  3437.  
  3438.  
  3439.           Data Stack:                c --
  3440.           String Stack:                --
  3441.  
  3442.       Prints the character whose ASCII code is c  on  the  current  output
  3443.       device.
  3444.  
  3445.       -----------------------------------------------------------
  3446.  
  3447.  
  3448.       17.38 PRINTER
  3449.  
  3450.  
  3451.           Data Stack:               -- 3
  3452.           String Stack:             --
  3453.  
  3454.       Places  the  constant  3 on the data stack.  The PRINTER instruction
  3455.       is used for clarity.  For example, the sequence PRINTER ISOUTPUT  is
  3456.       much clearer than 3 ISOUTPUT.
  3457.  
  3458.       -----------------------------------------------------------
  3459.  
  3460.       Chapter 17. I/O Instructions                                      62
  3461.  
  3462.  
  3463.       17.39 PRINT$
  3464.  
  3465.  
  3466.           Data Stack:              --
  3467.           String Stack:         a$ --
  3468.  
  3469.       Prints the string a$ on the current output device.
  3470.  
  3471.       -----------------------------------------------------------
  3472.  
  3473.  
  3474.       17.40 PUTBYTE
  3475.  
  3476.  
  3477.           Data Stack:          B F --
  3478.           String Stack:            --
  3479.  
  3480.       Outputs byte B to file F.
  3481.  
  3482.       -----------------------------------------------------------
  3483.  
  3484.  
  3485.       17.41 PUTPORT
  3486.  
  3487.  
  3488.           Data Stack:       Byte ComPort --
  3489.           String Stack:                  --
  3490.  
  3491.       Sends a Byte to ComPort 1 or 2
  3492.  
  3493.       -----------------------------------------------------------
  3494.  
  3495.  
  3496.       17.42 ROW
  3497.  
  3498.  
  3499.           Data Stack:             -- row
  3500.           String Stack:           --
  3501.  
  3502.       Places the row of the current cursor position on the data stack.
  3503.  
  3504.       -----------------------------------------------------------
  3505.  
  3506.  
  3507.       17.43 SETVOL
  3508.  
  3509.  
  3510.           Data Stack:           Vol --
  3511.           String Stack:             --
  3512.  
  3513.       Sets  the  sound volume on an HP100LX.  Vol may vary from 0 (silent)
  3514.       to 3 (loudest).
  3515.  
  3516.       HP only.
  3517.  
  3518.       Chapter 17. I/O Instructions                                      63
  3519.  
  3520.  
  3521.       -----------------------------------------------------------
  3522.  
  3523.  
  3524.       17.44 SOUND
  3525.  
  3526.  
  3527.           Data Stack:         freq dur --
  3528.           String Stack:                --
  3529.  
  3530.       Plays a sound of a given freq and dur.  Frequency is  in  Hertz  and
  3531.       duration is in Milliseconds.
  3532.  
  3533.       -----------------------------------------------------------
  3534.  
  3535.  
  3536.       17.45 VARPTR
  3537.  
  3538.  
  3539.           Data Stack:           V -- A
  3540.           String Stack:           --
  3541.  
  3542.       Places  the  address of a variable onto the data stack.  This may be
  3543.       used to PEEK and POKE values directly into a variable.
  3544.  
  3545.       -----------------------------------------------------------
  3546.  
  3547.  
  3548.       17.46 |
  3549.  
  3550.  
  3551.           Data Stack:             --
  3552.           String Stack:           --
  3553.  
  3554.       Prints the rest of the  current  line  out  to  the  current  output
  3555.       device.
  3556.  
  3557.       -----------------------------------------------------------
  3558.  
  3559.  
  3560.  
  3561.  
  3562.  
  3563.  
  3564.                                    Chapter 18
  3565.  
  3566.                                Math Instructions
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.       18.1 ABS
  3573.  
  3574.  
  3575.           Data Stack:          n -- N
  3576.           String Stack:          --
  3577.  
  3578.       Replaces the top value on the data stack with its absolute value.
  3579.  
  3580.       -----------------------------------------------------------
  3581.  
  3582.  
  3583.       18.2 MAX
  3584.  
  3585.  
  3586.           Data Stack:         A B -- MAX
  3587.           String Stack:           --
  3588.  
  3589.       Places the greater of A or B on the data stack.
  3590.  
  3591.       -----------------------------------------------------------
  3592.  
  3593.  
  3594.       18.3 MIN
  3595.  
  3596.  
  3597.           Data Stack:         A B -- MIN
  3598.           String Stack:           --
  3599.  
  3600.       Places the lesser of A or B on the data stack.
  3601.  
  3602.       -----------------------------------------------------------
  3603.  
  3604.  
  3605.  
  3606.  
  3607.  
  3608.  
  3609.  
  3610.  
  3611.  
  3612.  
  3613.  
  3614.  
  3615.  
  3616.                                        64
  3617.  
  3618.       Chapter 18. Math Instructions                                     65
  3619.  
  3620.  
  3621.       18.4 MOD
  3622.  
  3623.  
  3624.           Data Stack:         A B -- C
  3625.           String Stack:           --
  3626.  
  3627.       Returns A modulo B.
  3628.  
  3629.       -----------------------------------------------------------
  3630.  
  3631.  
  3632.       18.5 *
  3633.  
  3634.  
  3635.           Data Stack:         A B -- C
  3636.           String Stack:           --
  3637.  
  3638.       Multiplies A times B.
  3639.  
  3640.       -----------------------------------------------------------
  3641.  
  3642.  
  3643.       18.6 +
  3644.  
  3645.  
  3646.           Data Stack:         A B -- C
  3647.           String Stack:           --
  3648.  
  3649.       Adds A and B.
  3650.  
  3651.       -----------------------------------------------------------
  3652.  
  3653.  
  3654.       18.7 -
  3655.  
  3656.  
  3657.           Data Stack:         A B -- C
  3658.           String Stack:           --
  3659.  
  3660.       Subtracts B from A.
  3661.  
  3662.       -----------------------------------------------------------
  3663.  
  3664.  
  3665.       18.8 /
  3666.  
  3667.  
  3668.           Data Stack:         A B -- C
  3669.           String Stack:           --
  3670.  
  3671.       Divides A by B.
  3672.  
  3673.       -----------------------------------------------------------
  3674.  
  3675.       Chapter 18. Math Instructions                                     66
  3676.  
  3677.  
  3678.       18.9 <
  3679.  
  3680.  
  3681.           Data Stack:         A B -- C
  3682.           String Stack:           --
  3683.  
  3684.       C is TRUE if A is less than B, FALSE otherwise.
  3685.  
  3686.       -----------------------------------------------------------
  3687.  
  3688.  
  3689.       18.10 =
  3690.  
  3691.  
  3692.           Data Stack:          A B -- C
  3693.           String Stack:            --
  3694.  
  3695.       C is TRUE if A equals B, FALSE otherwise.
  3696.  
  3697.       -----------------------------------------------------------
  3698.  
  3699.  
  3700.       18.11 >
  3701.  
  3702.  
  3703.           Data Stack:           A B -- C
  3704.           String Stack:             --
  3705.  
  3706.       C is TRUE if A is greater than B, FALSE otherwise.
  3707.  
  3708.       -----------------------------------------------------------
  3709.  
  3710.  
  3711.  
  3712.  
  3713.  
  3714.  
  3715.                                    Chapter 19
  3716.  
  3717.                            Miscellaneous Instructions
  3718.  
  3719.  
  3720.  
  3721.  
  3722.  
  3723.       19.1 BIT?
  3724.  
  3725.  
  3726.           Data Stack:       number bit -- flag
  3727.           String Stack:                --
  3728.  
  3729.       Returns true if bit is set in number.
  3730.  
  3731.       -----------------------------------------------------------
  3732.  
  3733.  
  3734.       19.2 BYE
  3735.  
  3736.  
  3737.           Data Stack:             n --
  3738.           String Stack:             --
  3739.  
  3740.       Exits  a TIPI program and returns to DOS.  BYE returns the top value
  3741.       from the data stack as an error level to DOS.
  3742.  
  3743.       -----------------------------------------------------------
  3744.  
  3745.  
  3746.       19.3 ERROR
  3747.  
  3748.  
  3749.           Data Stack:                -- n
  3750.           String Stack:              --
  3751.  
  3752.       Places the number of the current error on the data stack.
  3753.  
  3754.       -----------------------------------------------------------
  3755.  
  3756.  
  3757.  
  3758.  
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.                                        67
  3768.  
  3769.       Chapter 19. Miscellaneous Instructions                            68
  3770.  
  3771.  
  3772.       19.4 EVAL
  3773.  
  3774.  
  3775.           Data Stack:                -- ?
  3776.           String Stack:           I$ -- ?
  3777.  
  3778.       Evaluates the instruction I$ from the string stack.
  3779.  
  3780.       -----------------------------------------------------------
  3781.  
  3782.  
  3783.       19.5 FALSE
  3784.  
  3785.  
  3786.           Data Stack:                 -- 0
  3787.           String Stack:               --
  3788.  
  3789.       Places the value of FALSE (0) on the top of the data stack.
  3790.  
  3791.       -----------------------------------------------------------
  3792.  
  3793.  
  3794.       19.6 MACHINE?
  3795.  
  3796.  
  3797.           Data Stack:                  -- n
  3798.           String Stack:                --
  3799.  
  3800.       Returns a  number  identifying  the  computer  TIPI  is  running  on
  3801.       according to the following table.
  3802.  
  3803.  
  3804.           0 = PC
  3805.           1 = HP95LX
  3806.           2 = HP100LX
  3807.  
  3808.       -----------------------------------------------------------
  3809.  
  3810.  
  3811.       19.7 NOT
  3812.  
  3813.  
  3814.           Data Stack:            n -- m
  3815.           String Stack:            --
  3816.  
  3817.       Negates  the  truth  value  of a flag.  If n is non-zero, m is zero.
  3818.       If n is zero, m is one.
  3819.  
  3820.       -----------------------------------------------------------
  3821.  
  3822.       Chapter 19. Miscellaneous Instructions                            69
  3823.  
  3824.  
  3825.       19.8 OFF
  3826.  
  3827.  
  3828.           Data Stack:              --
  3829.           String Stack:            --
  3830.  
  3831.       Shuts off an HP palmtop computer.  OFF has no effect on a PC.
  3832.  
  3833.       -----------------------------------------------------------
  3834.  
  3835.  
  3836.       19.9 RANDOM
  3837.  
  3838.  
  3839.           Data Stack:             N -- R
  3840.           String Stack:             --
  3841.  
  3842.       Replaces N on the data stack with R, a random integer selected  from
  3843.       the range 1 to N (inclusive).
  3844.  
  3845.       -----------------------------------------------------------
  3846.  
  3847.  
  3848.       19.10 RANDOMIZE
  3849.  
  3850.  
  3851.           Data Stack:               --
  3852.           String Stack:             --
  3853.  
  3854.       Initializes the random number generator.
  3855.  
  3856.       -----------------------------------------------------------
  3857.  
  3858.  
  3859.       19.11 TICKS
  3860.  
  3861.  
  3862.           Data Stack:               -- t
  3863.           String Stack:             --
  3864.  
  3865.       Places  the  current  PC  tick  count on the data stack.  A PC ticks
  3866.       18.2 times per second.
  3867.  
  3868.       -----------------------------------------------------------
  3869.  
  3870.       Chapter 19. Miscellaneous Instructions                            70
  3871.  
  3872.  
  3873.       19.12 TIMEOUT
  3874.  
  3875.  
  3876.           Data Stack:             T --
  3877.           String Stack:             --
  3878.  
  3879.       Controls the auto-timeout feature  of  the  HP  palmtops.   If  T=0,
  3880.       auto-timeout  is  disabled.   If  T  is in the range 1 to 65535, the
  3881.       timout is set to that many ticks (a tick=55 msecs).
  3882.  
  3883.       Notes:
  3884.  
  3885.       1.  The power-up default value for T is 3276 (3 minutes).
  3886.  
  3887.       2.  If the main batteries are low, the maximum  timeout  value  will
  3888.           be one minute.
  3889.  
  3890.       HP only.
  3891.  
  3892.       -----------------------------------------------------------
  3893.  
  3894.  
  3895.       19.13 TRUE
  3896.  
  3897.  
  3898.           Data Stack:             -- 1
  3899.           String Stack:           --
  3900.  
  3901.       Places the constant 1 on the top of the data stack.
  3902.  
  3903.       -----------------------------------------------------------
  3904.  
  3905.  
  3906.       19.14 VERSION
  3907.  
  3908.  
  3909.           Data Stack:              -- N
  3910.           String Stack:            --
  3911.  
  3912.       VERSION  leaves  an  integer N on the data stack.  N is equal to the
  3913.       version number times ten (ie if  N  is  23  then  the  TIPI  version
  3914.       number is 2.3).
  3915.  
  3916.       -----------------------------------------------------------
  3917.  
  3918.       Chapter 19. Miscellaneous Instructions                            71
  3919.  
  3920.  
  3921.       19.15 #
  3922.  
  3923.  
  3924.           Data Stack:              --
  3925.           String Stack:            --
  3926.  
  3927.       Identifies a comment.  Anything after the # on a line is ignored.
  3928.  
  3929.       -----------------------------------------------------------
  3930.  
  3931.  
  3932.       19.16 (
  3933.  
  3934.  
  3935.           Data Stack:              --
  3936.           String Stack:            --
  3937.  
  3938.       Begins a comment.
  3939.  
  3940.       -----------------------------------------------------------
  3941.  
  3942.  
  3943.       19.17 )
  3944.  
  3945.  
  3946.           Data Stack:              --
  3947.           String Stack:            --
  3948.  
  3949.       Ends a comment.
  3950.  
  3951.       -----------------------------------------------------------
  3952.  
  3953.  
  3954.  
  3955.  
  3956.  
  3957.  
  3958.                                    Chapter 20
  3959.  
  3960.                                Stack Instructions
  3961.  
  3962.  
  3963.  
  3964.  
  3965.  
  3966.       20.1 DEPTH
  3967.  
  3968.  
  3969.           Data Stack:             -- N
  3970.           String Stack:           --
  3971.  
  3972.       Places N on the data stack, where N is the depth of the data stack.
  3973.  
  3974.       -----------------------------------------------------------
  3975.  
  3976.  
  3977.       20.2 DEPTH$
  3978.  
  3979.  
  3980.           Data Stack:             -- N
  3981.           String Stack:           --
  3982.  
  3983.       Places  N  on  the  data  stack,  where N is the depth of the string
  3984.       stack.
  3985.  
  3986.       -----------------------------------------------------------
  3987.  
  3988.  
  3989.       20.3 DROP
  3990.  
  3991.  
  3992.           Data Stack:            N --
  3993.           String Stack:            --
  3994.  
  3995.       Removes the top value from the data stack.
  3996.  
  3997.       -----------------------------------------------------------
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.                                        72
  4011.  
  4012.       Chapter 20. Stack Instructions                                    73
  4013.  
  4014.  
  4015.       20.4 DROP$
  4016.  
  4017.  
  4018.           Data Stack:              --
  4019.           String Stack:         A$ --
  4020.  
  4021.       Removes the top value from the string stack.
  4022.  
  4023.       -----------------------------------------------------------
  4024.  
  4025.  
  4026.       20.5 DUP
  4027.  
  4028.  
  4029.           Data Stack:            N -- N N
  4030.           String Stack:            --
  4031.  
  4032.       Duplicates the top value on the data stack.
  4033.  
  4034.       -----------------------------------------------------------
  4035.  
  4036.  
  4037.       20.6 DUP$
  4038.  
  4039.  
  4040.           Data Stack:              --
  4041.           String Stack:         A$ -- A$ A$
  4042.  
  4043.       Duplicates the top value on the string stack.
  4044.  
  4045.       -----------------------------------------------------------
  4046.  
  4047.  
  4048.       20.7 OVER
  4049.  
  4050.  
  4051.           Data Stack:          a b -- a b a
  4052.           String Stack:            --
  4053.  
  4054.       Copies the second item on the data stack to the top.
  4055.  
  4056.       -----------------------------------------------------------
  4057.  
  4058.  
  4059.       20.8 OVER$
  4060.  
  4061.  
  4062.           Data Stack:                  --
  4063.           String Stack:          a$ b$ -- a$ b$ a$
  4064.  
  4065.       Copies the second item on the string stack to the top.
  4066.  
  4067.       -----------------------------------------------------------
  4068.  
  4069.       Chapter 20. Stack Instructions                                    74
  4070.  
  4071.  
  4072.       20.9 PICK
  4073.  
  4074.  
  4075.           Data Stack:                n -- m
  4076.           String Stack:                --
  4077.  
  4078.       Places a copy of the data stack's nth item on the top  of  the  data
  4079.       stack.
  4080.  
  4081.       -----------------------------------------------------------
  4082.  
  4083.  
  4084.       20.10 PICK$
  4085.  
  4086.  
  4087.           Data Stack:                n --
  4088.           String Stack:                -- m$
  4089.  
  4090.       Places  a  copy  of  the  string  stack's nth item on the top of the
  4091.       string stack.
  4092.  
  4093.       -----------------------------------------------------------
  4094.  
  4095.  
  4096.       20.11 POP
  4097.  
  4098.  
  4099.           Data Stack:                  -- n
  4100.           String Stack:                --
  4101.  
  4102.       Pops a value off the return stack.
  4103.  
  4104.       -----------------------------------------------------------
  4105.  
  4106.  
  4107.       20.12 PUSH
  4108.  
  4109.  
  4110.           Data Stack:                n --
  4111.           String Stack:                --
  4112.  
  4113.       Pushes a value to the return stack.
  4114.  
  4115.       -----------------------------------------------------------
  4116.  
  4117.       Chapter 20. Stack Instructions                                    75
  4118.  
  4119.  
  4120.       20.13 ROT
  4121.  
  4122.  
  4123.           Data Stack:             a b c -- b c a
  4124.           String Stack:                 --
  4125.  
  4126.       Rotates the top three values on the data stack.
  4127.  
  4128.       -----------------------------------------------------------
  4129.  
  4130.  
  4131.       20.14 ROT$
  4132.  
  4133.  
  4134.           Data Stack:                       --
  4135.           String Stack:            a$ b$ c$ -- b$ c$ a$
  4136.  
  4137.       Rotates the top three values on the string stack.
  4138.  
  4139.       -----------------------------------------------------------
  4140.  
  4141.  
  4142.       20.15 SWAP
  4143.  
  4144.  
  4145.           Data Stack:              a b -- b a
  4146.           String Stack:                --
  4147.  
  4148.       Swaps the top two values on the data stack.
  4149.  
  4150.       -----------------------------------------------------------
  4151.  
  4152.  
  4153.       20.16 SWAP$
  4154.  
  4155.  
  4156.           Data Stack:                   --
  4157.           String Stack:           a$ b$ -- b$ a$
  4158.  
  4159.       Swaps the top two values on the string stack.
  4160.  
  4161.       -----------------------------------------------------------
  4162.  
  4163.  
  4164.  
  4165.  
  4166.  
  4167.  
  4168.                                    Chapter 21
  4169.  
  4170.                               String Instructions
  4171.  
  4172.  
  4173.  
  4174.  
  4175.  
  4176.       21.1 ASC
  4177.  
  4178.  
  4179.           Data Stack:             -- N
  4180.           String Stack:        A$ -- A$
  4181.  
  4182.       Places a number N on the data stack, where N is the ASCII  value  of
  4183.       the first character of the string on the top of the string stack.
  4184.  
  4185.       -----------------------------------------------------------
  4186.  
  4187.  
  4188.       21.2 CHR$
  4189.  
  4190.  
  4191.           Data Stack:          N --
  4192.           String Stack:          -- M$
  4193.  
  4194.       CHR$  converts  an  integer  N  from  the  data  stack  to  an ASCII
  4195.       character and places the single character string on the top  of  the
  4196.       string stack.
  4197.  
  4198.       -----------------------------------------------------------
  4199.  
  4200.  
  4201.       21.3 DATE$
  4202.  
  4203.  
  4204.           Data Stack:            --
  4205.           String Stack:          -- D$
  4206.  
  4207.       Places   the   current   date  on  the  string  stack  in  the  form
  4208.       "MM-DD-YYYY"
  4209.  
  4210.       -----------------------------------------------------------
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.  
  4220.                                        76
  4221.  
  4222.       Chapter 21. String Instructions                                   77
  4223.  
  4224.  
  4225.       21.4 INSTR
  4226.  
  4227.  
  4228.           Data Stack:                -- n
  4229.           String Stack:        a$ b$ -- a$ b$
  4230.  
  4231.       Searches a$ for the first occurrence of b$.  If b$ is in  a$,  n  is
  4232.       the location where b$ starts in a$.  If b$ is not in a$, n is zero.
  4233.  
  4234.       -----------------------------------------------------------
  4235.  
  4236.  
  4237.       21.5 LCASE$
  4238.  
  4239.  
  4240.           Data Stack:                --
  4241.           String Stack:           A$ -- a$
  4242.  
  4243.       Converts any uppercase characters in A$ to lowercase.
  4244.  
  4245.       -----------------------------------------------------------
  4246.  
  4247.  
  4248.       21.6 LEFT$
  4249.  
  4250.  
  4251.           Data Stack:              n --
  4252.           String Stack:           a$ -- l$
  4253.  
  4254.       Returns  a  string  consisting  of  the n leftmost characters of a$.
  4255.       For example, "This is a test" 7 LEFT$ would return "This is".
  4256.  
  4257.       -----------------------------------------------------------
  4258.  
  4259.  
  4260.       21.7 LEN
  4261.  
  4262.  
  4263.           Data Stack:                -- len
  4264.           String Stack:           a$ -- a$
  4265.  
  4266.       Places the length of a$ on the data stack.
  4267.  
  4268.       -----------------------------------------------------------
  4269.  
  4270.       Chapter 21. String Instructions                                   78
  4271.  
  4272.  
  4273.       21.8 LTRIM$
  4274.  
  4275.  
  4276.           Data Stack:                --
  4277.           String Stack:           a$ -- b$
  4278.  
  4279.       Trims any leading blanks from a$.
  4280.  
  4281.       -----------------------------------------------------------
  4282.  
  4283.  
  4284.       21.9 MID$
  4285.  
  4286.  
  4287.           Data Stack:           st len --
  4288.           String Stack:             a$ -- b$
  4289.  
  4290.       Returns b$, a string of len characters starting at position st  from
  4291.       a$.
  4292.  
  4293.       -----------------------------------------------------------
  4294.  
  4295.  
  4296.       21.10 PARSE$
  4297.  
  4298.  
  4299.           Data Stack:                  --
  4300.           String Stack:          text$ -- newtext$ word$
  4301.  
  4302.       Parses the first word from text$.
  4303.  
  4304.       -----------------------------------------------------------
  4305.  
  4306.  
  4307.       21.11 REPLACE$
  4308.  
  4309.  
  4310.           Data Stack:                          --
  4311.           String Stack:        text$ old$ new$ -- newtext$
  4312.  
  4313.       Replaces any occurrences of old$ in text$ with new$.
  4314.  
  4315.       -----------------------------------------------------------
  4316.  
  4317.  
  4318.       21.12 RIGHT$
  4319.  
  4320.  
  4321.           Data Stack:               n --
  4322.           String Stack:            a$ -- b$
  4323.  
  4324.       Returns  a  string  consisting  of the n rightmost characters of a$.
  4325.       For example, "This is a test" 6 RIGHT$ would return "a test".
  4326.  
  4327.       Chapter 21. String Instructions                                   79
  4328.  
  4329.  
  4330.       -----------------------------------------------------------
  4331.  
  4332.  
  4333.       21.13 RTRIM$
  4334.  
  4335.  
  4336.           Data Stack:                 --
  4337.           String Stack:            a$ -- b$
  4338.  
  4339.       Removes any trailing blanks from a$.
  4340.  
  4341.       -----------------------------------------------------------
  4342.  
  4343.  
  4344.       21.14 STR$
  4345.  
  4346.  
  4347.           Data Stack:              n --
  4348.           String Stack:              -- n$
  4349.  
  4350.       Converts an integer from the data stack to a string.   For  example,
  4351.       123 STR$ would place the string "123" on the string stack.
  4352.  
  4353.       -----------------------------------------------------------
  4354.  
  4355.  
  4356.       21.15 TIME$
  4357.  
  4358.  
  4359.           Data Stack:                 --
  4360.           String Stack:               -- t$
  4361.  
  4362.       Places  the  current  time  (in  the  form "HH:MM:SS") on the string
  4363.       stack.
  4364.  
  4365.       -----------------------------------------------------------
  4366.  
  4367.  
  4368.       21.16 UCASE$
  4369.  
  4370.  
  4371.           Data Stack:                 --
  4372.           String Stack:            a$ -- A$
  4373.  
  4374.       Converts any lowercase letters in a$ to uppercase.
  4375.  
  4376.       -----------------------------------------------------------
  4377.  
  4378.       Chapter 21. String Instructions                                   80
  4379.  
  4380.  
  4381.       21.17 VAL
  4382.  
  4383.  
  4384.           Data Stack:                 -- n
  4385.           String Stack:            s$ --
  4386.  
  4387.       Converts a string to a number.
  4388.  
  4389.       -----------------------------------------------------------
  4390.  
  4391.  
  4392.       21.18 "
  4393.  
  4394.  
  4395.           Data Stack:                 --
  4396.           String Stack:               --
  4397.  
  4398.       Begins and ends a text string.
  4399.  
  4400.       -----------------------------------------------------------
  4401.  
  4402.  
  4403.       21.19 +$
  4404.  
  4405.  
  4406.           Data Stack:                  --
  4407.           String Stack:          a$ b$ -- c$
  4408.  
  4409.       Combines a$ and b$ into one string.
  4410.  
  4411.       -----------------------------------------------------------
  4412.  
  4413.  
  4414.       21.20 =$
  4415.  
  4416.  
  4417.           Data Stack:                  -- C
  4418.           String Stack:          A$ B$ --
  4419.  
  4420.       C is TRUE if A$ equals B$, FALSE otherwise.
  4421.  
  4422.       -----------------------------------------------------------
  4423.  
  4424.       Index of TIPI Instructions                                        81
  4425.  
  4426.  
  4427.       ", 80                               DUP, 73
  4428.       #, 71                               DUP$, 73
  4429.       (, 71                               ELSE, 32
  4430.       ), 71                               ENDCASE, 33
  4431.       *, 65                               ENDCASE$, 33
  4432.       +, 65                               ENDDEF, 42
  4433.       +$, 80                              ENDIF, 33
  4434.       -, 65                               ENDOF, 33
  4435.       /, 65                               ENDOF$, 33
  4436.       <, 66                               ENDTABLE, 42
  4437.       =, 66                               ENV$, 44
  4438.       =$, 80                              EOF, 56
  4439.       >, 66                               ERROR, 67
  4440.       |, 63                               EVAL, 68
  4441.       ABS, 64                             EXTENDED, 56
  4442.       ASC, 76                             FALSE, 68
  4443.       BEEP, 52                            FETCH, 37
  4444.       BEGIN, 31                           FILEPOS, 56
  4445.       BIT?, 67                            FIRSTFILE, 44
  4446.       BLOAD, 52                           GET$, 57
  4447.       BSAVE, 52                           GETBYTE, 56
  4448.       BYE, 67                             GETDIR, 44
  4449.       CALL, 43                            GETFONT, 46
  4450.       CASE, 31                            GETNUM, 57
  4451.       CASE$, 31                           GETPOINT, 47
  4452.       CHDIR, 43                           GETPORT, 57
  4453.       CHR$, 76                            GETVOL, 57
  4454.       CLOSE, 53                           IF, 34
  4455.       CLS, 53                             INDEX, 34
  4456.       COLOR, 53                           INKEY$, 58
  4457.       COLOR?, 53                          INPORT, 58
  4458.       COLUMN, 54                          INSTR, 77
  4459.       COMMAND$, 43                        ISINPUT, 58
  4460.       COMSTAT, 54                         ISOUTPUT, 58
  4461.       CONSOLE, 54                         KEY, 59
  4462.       CR, 55                              KILL, 44
  4463.       CURRENT, 55                         LCASE$, 77
  4464.       CURSOR, 55                          LEAVE, 34
  4465.       DATE$, 76                           LEFT$, 77
  4466.       DEFARRAY, 40                        LEN, 77
  4467.       DEFAULT, 32                         LF, 59
  4468.       DEFAULT$, 32                        LOCATE, 59
  4469.       DEFINE, 40                          LOOP, 34
  4470.       DEFSEG, 55                          LTRIM$, 78
  4471.       DEFSTR, 41                          MACHINE?, 68
  4472.       DEFSTRARRAY, 41                     MAKEDIR, 45
  4473.       DEFTABLE, 41                        MAX, 64
  4474.       DEFVAR, 42                          MID$, 78
  4475.       DEPTH, 72                           MIN, 64
  4476.       DEPTH$, 72                          MOD, 65
  4477.       DO, 32                              MOUSE, 59
  4478.       DRAWLINE, 46                        MOVEPEN, 47
  4479.       DRAWRECT, 46                        NEXTFILE, 45
  4480.       DROP, 72                            NOT, 68
  4481.       DROP$, 73                           OF, 35
  4482.  
  4483.       Index of TIPI Instructions                                        82
  4484.  
  4485.  
  4486.       OF$, 35                             TRACEVAR, 39
  4487.       OFF, 69                             TRUE, 70
  4488.       OPEN, 59                            UCASE$, 79
  4489.       OPENCOM, 60                         UNTIL, 35
  4490.       OUTPORT, 60                         VAL, 80
  4491.       OVER, 73                            VARPTR, 63
  4492.       OVER$, 73                           VERSION, 70
  4493.       PARSE$, 78                          WEND, 35
  4494.       PEEK, 60                            WHILE, 36
  4495.       PICK, 74                            ZOOM, 51
  4496.       PICK$, 74
  4497.       PLOTICON, 47
  4498.       PLOTPOINT, 48
  4499.       PLOTTEXT, 48
  4500.       POKE, 61
  4501.       POP, 74
  4502.       PRINT, 61
  4503.       PRINT$, 62
  4504.       PRINTCHR, 61
  4505.       PRINTER, 61
  4506.       PUSH, 74
  4507.       PUTBYTE, 62
  4508.       PUTPORT, 62
  4509.       RANDOM, 69
  4510.       RANDOMIZE, 69
  4511.       REMDIR, 45
  4512.       RENAME, 45
  4513.       REPLACE$, 78
  4514.       RIGHT$, 78
  4515.       ROT, 75
  4516.       ROT$, 75
  4517.       ROW, 62
  4518.       RTRIM$, 79
  4519.       SCREEN, 48
  4520.       SCROLL, 49
  4521.       SETCLIP, 49
  4522.       SETFONT, 49
  4523.       SETLINETYPE, 49
  4524.       SETLOGORG, 50
  4525.       SETPENCOLOR, 50
  4526.       SETREPRULE, 50
  4527.       SETVMODE, 51
  4528.       SETVOL, 62
  4529.       SOUND, 63
  4530.       STORE, 37
  4531.       STR$, 79
  4532.       SWAP, 75
  4533.       SWAP$, 75
  4534.       TICKS, 69
  4535.       TIME$, 79
  4536.       TIMEOUT, 70
  4537.       TRACECOL, 38
  4538.       TRACEOFF, 38
  4539.       TRACEON, 38
  4540.       TRACEROW, 39
  4541.