home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / COMAL3-M.LHA / Comal.DOC < prev    next >
Encoding:
Text File  |  1993-05-05  |  385.4 KB  |  14,984 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.   I. GETTING STARTED . . . . . . . . . . . . . . . . . . . . . . . . .    5
  9.     1 Hardware requierements . . . . . . . . . . . . . . . . . . . . .    5
  10.     2 Software requirements  . . . . . . . . . . . . . . . . . . . . .    5
  11.     3 Creating a backup disk . . . . . . . . . . . . . . . . . . . . .    5
  12.     4 Installing Comal on a floppy disk system . . . . . . . . . . . .    6
  13.     5 Installing Comal on a hard disk system . . . . . . . . . . . . .    6
  14.     6 Starting Comal from Workbench  . . . . . . . . . . . . . . . . .    6
  15.     7 Starting Comal from the Shell (the CLI)  . . . . . . . . . . . .    7
  16.     8 Setting the Comal environment  . . . . . . . . . . . . . . . . .    7
  17.       8.1 Setting the Comal TOOLTYPES  . . . . . . . . . . . . . . . .    8
  18.       8.2 The Preferences program Pref . . . . . . . . . . . . . . . .   11
  19.  
  20.   II. TUTORIAL . . . . . . . . . . . . . . . . . . . . . . . . . . . .   12
  21.     1 Your first Comal programs  . . . . . . . . . . . . . . . . . . .   12
  22.     2 Working with graphics  . . . . . . . . . . . . . . . . . . . . .   13
  23.     3 Repetition . . . . . . . . . . . . . . . . . . . . . . . . . . .   15
  24.     4 Selection  . . . . . . . . . . . . . . . . . . . . . . . . . . .   18
  25.     5 Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . .   20
  26.     6 Making modules . . . . . . . . . . . . . . . . . . . . . . . . .   23
  27.     7 Looking into modules . . . . . . . . . . . . . . . . . . . . . .   26
  28.     8 Making gadgets . . . . . . . . . . . . . . . . . . . . . . . . .   27
  29.     9 Event driven programs  . . . . . . . . . . . . . . . . . . . . .   31
  30.     10 Debugging programs  . . . . . . . . . . . . . . . . . . . . . .   33
  31.  
  32.   III. THE PROGRAMMING ENVIRONMENT . . . . . . . . . . . . . . . . . .   36
  33.     1 The keyboard . . . . . . . . . . . . . . . . . . . . . . . . . .   36
  34.     2 The mouse  . . . . . . . . . . . . . . . . . . . . . . . . . . .   37
  35.     3 The menus  . . . . . . . . . . . . . . . . . . . . . . . . . . .   38
  36.       3.1 The Project menu . . . . . . . . . . . . . . . . . . . . . .   38
  37.       3.2 The Edit menu  . . . . . . . . . . . . . . . . . . . . . . .   39
  38.       3.3 The Search menu  . . . . . . . . . . . . . . . . . . . . . .   40
  39.       3.4 The Macros menu  . . . . . . . . . . . . . . . . . . . . . .   40
  40.       3.5 The Settings menu  . . . . . . . . . . . . . . . . . . . . .   41
  41.       3.6 The Program menu . . . . . . . . . . . . . . . . . . . . . .   42
  42.       3.7 The Trace menu . . . . . . . . . . . . . . . . . . . . . . .   43
  43.  
  44.   IV. DESCRIPTION OF THE Comal LANGUAGE  . . . . . . . . . . . . . . .   45
  45.     1 Data types, variables and expressions  . . . . . . . . . . . . .   45
  46.       1.1 Identifiers  . . . . . . . . . . . . . . . . . . . . . . . .   45
  47.       1.2 Simple data types  . . . . . . . . . . . . . . . . . . . . .   45
  48.         1.2.1 Constants  . . . . . . . . . . . . . . . . . . . . . . .   46
  49.         1.2.2 Expressions  . . . . . . . . . . . . . . . . . . . . . .   47
  50.         1.2.3 Variables  . . . . . . . . . . . . . . . . . . . . . . .   51
  51.       1.3 Structured data types  . . . . . . . . . . . . . . . . . . .   53
  52.         1.3.1 Indexed variables  . . . . . . . . . . . . . . . . . . .   53
  53.         1.3.2 Strucs (records) . . . . . . . . . . . . . . . . . . . .   55
  54.       1.4 Dynamic variables. Pointer variables . . . . . . . . . . . .   56
  55.       1.5 Type definition  . . . . . . . . . . . . . . . . . . . . . .   61
  56.  
  57.  
  58.                                           1
  59.  
  60.  
  61.  
  62.  
  63.  
  64.     2 Program flow control statements  . . . . . . . . . . . . . . . .   63
  65.       2.1 Selection  . . . . . . . . . . . . . . . . . . . . . . . . .   63
  66.         2.1.1 The IF statements  . . . . . . . . . . . . . . . . . . .   63
  67.         2.1.2 The CASE statement . . . . . . . . . . . . . . . . . . .   66
  68.       2.2 Repetition . . . . . . . . . . . . . . . . . . . . . . . . .   67
  69.       2.3 Branching  . . . . . . . . . . . . . . . . . . . . . . . . .   72
  70.         2.3.1 The GOTO statement . . . . . . . . . . . . . . . . . . .   72
  71.         2.3.1 The EXIT statement . . . . . . . . . . . . . . . . . . .   73
  72.     3 Procedures and functions . . . . . . . . . . . . . . . . . . . .   73
  73.       3.1 Procedures . . . . . . . . . . . . . . . . . . . . . . . . .   73
  74.         3.1.1 Procedures without parameters  . . . . . . . . . . . . .   74
  75.         3.1.2 Value parameters . . . . . . . . . . . . . . . . . . . .   75
  76.         3.1.3 Reference parameters . . . . . . . . . . . . . . . . . .   77
  77.         3.1.4 Local procedures . . . . . . . . . . . . . . . . . . . .   78
  78.         3.1.5 Local and global variables. CLOSED procedures  . . . . .   79
  79.       3.2 Functions  . . . . . . . . . . . . . . . . . . . . . . . . .   82
  80.     4 Exception handling . . . . . . . . . . . . . . . . . . . . . . .   83
  81.       4.1 The TRAP statement . . . . . . . . . . . . . . . . . . . . .   83
  82.       4.2 The TRAP ESC statement . . . . . . . . . . . . . . . . . . .   85
  83.     5 IO statements  . . . . . . . . . . . . . . . . . . . . . . . . .   86
  84.       5.1 The PRINT statement  . . . . . . . . . . . . . . . . . . . .   86
  85.       5.2 The INPUT statement  . . . . . . . . . . . . . . . . . . . .   88
  86.       5.3 Redirection of IO  . . . . . . . . . . . . . . . . . . . . .   89
  87.       5.4 System functions performing IO . . . . . . . . . . . . . . .   90
  88.       5.5 Other IO related statements and functions  . . . . . . . . .   90
  89.     6 File statements  . . . . . . . . . . . . . . . . . . . . . . . .   92
  90.       6.1 Sequential binary files  . . . . . . . . . . . . . . . . . .   93
  91.       6.2 Random access binary files . . . . . . . . . . . . . . . . .   95
  92.       6.3 ASCII files  . . . . . . . . . . . . . . . . . . . . . . . .   97
  93.       6.4 File system related functions  . . . . . . . . . . . . . . .   99
  94.       6.5 READ and DATA statements . . . . . . . . . . . . . . . . . .  100
  95.     7 Miscellaneous statements, procedures and functions . . . . . . .  103
  96.       7.1 DOS statements and functions . . . . . . . . . . . . . . . .  103
  97.       7.2 Time related statements and functions  . . . . . . . . . . .  106
  98.       7.3 Random numbers . . . . . . . . . . . . . . . . . . . . . . .  107
  99.       7.4 STOP and END statements  . . . . . . . . . . . . . . . . . .  108
  100.       7.5 Interrupt procedures . . . . . . . . . . . . . . . . . . . .  109
  101.       7.6 Mathematical functions . . . . . . . . . . . . . . . . . . .  109
  102.       7.7 Functions involving strings  . . . . . . . . . . . . . . . .  111
  103.       7.8 Other functions  . . . . . . . . . . . . . . . . . . . . . .  112
  104.     8 Objects  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  112
  105.       8.1 Introduction to OOP  . . . . . . . . . . . . . . . . . . . .  113
  106.       8.2 Methods  . . . . . . . . . . . . . . . . . . . . . . . . . .  118
  107.       8.3 Inheritance  . . . . . . . . . . . . . . . . . . . . . . . .  120
  108.       8.4 Virtual methods  . . . . . . . . . . . . . . . . . . . . . .  122
  109.       8.5 Constructors . . . . . . . . . . . . . . . . . . . . . . . .  124
  110.       8.6 Destructors  . . . . . . . . . . . . . . . . . . . . . . . .  126
  111.     9 Modules  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  127
  112.       9.1 Making modules . . . . . . . . . . . . . . . . . . . . . . .  128
  113.       9.2 Using modules  . . . . . . . . . . . . . . . . . . . . . . .  129
  114.  
  115.                                           2
  116.  
  117.  
  118.  
  119.  
  120.  
  121.       9.3 Signal procedures  . . . . . . . . . . . . . . . . . . . . .  130
  122.     10 Description of the standard modules . . . . . . . . . . . . . .  131
  123.       10.1 The System modules  . . . . . . . . . . . . . . . . . . . .  131
  124.         10.1.1 SystemCode  . . . . . . . . . . . . . . . . . . . . . .  131
  125.         10.1.2 System  . . . . . . . . . . . . . . . . . . . . . . . .  133
  126.       10.2 The graphics modules  . . . . . . . . . . . . . . . . . . .  135
  127.         10.2.1 Graphics  . . . . . . . . . . . . . . . . . . . . . . .  135
  128.         10.2.2 Turtle  . . . . . . . . . . . . . . . . . . . . . . . .  144
  129.       10.3 Catalog . . . . . . . . . . . . . . . . . . . . . . . . . .  148
  130.       10.4 Bob and sprite modules  . . . . . . . . . . . . . . . . . .  149
  131.       10.5 Memory  . . . . . . . . . . . . . . . . . . . . . . . . . .  151
  132.       10.6 CodeManInclude and InterpreterInclude . . . . . . . . . . .  152
  133.       10.7 StartProgram  . . . . . . . . . . . . . . . . . . . . . . .  152
  134.       10.9 Timer . . . . . . . . . . . . . . . . . . . . . . . . . . .  152
  135.       10.10 SerialComm . . . . . . . . . . . . . . . . . . . . . . . .  153
  136.       10.11 Operating system modules . . . . . . . . . . . . . . . . .  154
  137.         10.11.1 Library interface routines . . . . . . . . . . . . . .  155
  138.         10.11.2 Definitions for use in the library modules . . . . . .  156
  139.     11 The Comal Intuition Tools (CIT) . . . . . . . . . . . . . . . .  160
  140.       11.1 General description of CIT  . . . . . . . . . . . . . . . .  161
  141.       11.2 Simple CIT examples . . . . . . . . . . . . . . . . . . . .  163
  142.       11.3 CIT reference . . . . . . . . . . . . . . . . . . . . . . .  168
  143.         11.3.1 CITWorkbench  . . . . . . . . . . . . . . . . . . . . .  168
  144.         11.3.2 CITScreen . . . . . . . . . . . . . . . . . . . . . . .  169
  145.         11.3.3 CITWindow . . . . . . . . . . . . . . . . . . . . . . .  170
  146.         11.3.4 CITBorder . . . . . . . . . . . . . . . . . . . . . . .  174
  147.         11.3.5 CITView . . . . . . . . . . . . . . . . . . . . . . . .  175
  148.         11.3.6 CITGadgets  . . . . . . . . . . . . . . . . . . . . . .  175
  149.           11.3.6.1 TextGadget  . . . . . . . . . . . . . . . . . . . .  177
  150.           11.3.6.2 ButtonGadget  . . . . . . . . . . . . . . . . . . .  178
  151.           11.3.6.3 CheckboxGadget  . . . . . . . . . . . . . . . . . .  178
  152.           11.3.6.4 StringGadget  . . . . . . . . . . . . . . . . . . .  178
  153.           11.3.6.5 IntegerGadget . . . . . . . . . . . . . . . . . . .  179
  154.           11.3.6.6 SliderGadget  . . . . . . . . . . . . . . . . . . .  180
  155.           11.3.6.7 ScrollerGadget  . . . . . . . . . . . . . . . . . .  181
  156.           11.3.6.8 CycleGadget . . . . . . . . . . . . . . . . . . . .  183
  157.           11.3.6.9 RadioButtonGadget . . . . . . . . . . . . . . . . .  183
  158.           11.3.6.10 ListViewGadget . . . . . . . . . . . . . . . . . .  184
  159.           11.3.6.11 PaletteGadget  . . . . . . . . . . . . . . . . . .  186
  160.         11.3.7 CITText . . . . . . . . . . . . . . . . . . . . . . . .  187
  161.         11.3.8 CITGraphics . . . . . . . . . . . . . . . . . . . . . .  188
  162.         11.3.9 CITMenus  . . . . . . . . . . . . . . . . . . . . . . .  189
  163.         11.3.10 CITRequester . . . . . . . . . . . . . . . . . . . . .  193
  164.       11.4 Creating your own CIT classes . . . . . . . . . . . . . . .  194
  165.  
  166.   V. MAKING EXECUTABLE PROGRAMS  . . . . . . . . . . . . . . . . . . .  199
  167.     1 Comal code file  . . . . . . . . . . . . . . . . . . . . . . . .  199
  168.     2 Combined files . . . . . . . . . . . . . . . . . . . . . . . . .  199
  169.       2.1 Starting the Combiner from the editor  . . . . . . . . . . .  200
  170.       2.2 Starting the Combiner from Workbench . . . . . . . . . . . .  200
  171.  
  172.                                           3
  173.  
  174.  
  175.  
  176.  
  177.  
  178.       2.3 Starting the Combiner from the Shell (CLI) . . . . . . . . .  201
  179.     3 Using ToolTypes in executable files  . . . . . . . . . . . . . .  202
  180.  
  181.   VI. DESCRIPTION OF THE Comal SYSTEM  . . . . . . . . . . . . . . . .  203
  182.     1 The code manipulator Comal.CodeMan . . . . . . . . . . . . . . .  203
  183.     2 The interpreter Comal.Interpreter  . . . . . . . . . . . . . . .  210
  184.     3 The starter program Comal.Starter  . . . . . . . . . . . . . . .  216
  185.  
  186.   VII. THE Comal AREXX INTERFACE . . . . . . . . . . . . . . . . . . .  217
  187.     1 The editor AREXX interface . . . . . . . . . . . . . . . . . . .  217
  188.     2 The CodeMan AREXX interface  . . . . . . . . . . . . . . . . . .  224
  189.     3 The interpreter AREXX interface  . . . . . . . . . . . . . . . .  228
  190.     4 An AREXX script example  . . . . . . . . . . . . . . . . . . . .  229
  191.  
  192.   VIII. COMAL IO DEVICES . . . . . . . . . . . . . . . . . . . . . . .  231
  193.     1 What is a Comal device?  . . . . . . . . . . . . . . . . . . . .  231
  194.     2 Making new devices . . . . . . . . . . . . . . . . . . . . . . .  231
  195.     3 Making your own IO window  . . . . . . . . . . . . . . . . . . .  240
  196.  
  197.   IX. MASHINE CODED MODULES  . . . . . . . . . . . . . . . . . . . . .  242
  198.     1 The format of a mashine coded module . . . . . . . . . . . . . .  242
  199.       1.1 The interface part . . . . . . . . . . . . . . . . . . . . .  242
  200.       1.2 The initialization and signal routines . . . . . . . . . . .  243
  201.       1.3 The routine part . . . . . . . . . . . . . . . . . . . . . .  244
  202.     2 An assembler programmed module . . . . . . . . . . . . . . . . .  244
  203.     3 Programming modules in C . . . . . . . . . . . . . . . . . . . .  249
  204.       3.1 The interface part . . . . . . . . . . . . . . . . . . . . .  249
  205.       3.2 The procedures and functions . . . . . . . . . . . . . . . .  250
  206.       3.3 Linking the object files . . . . . . . . . . . . . . . . . .  251
  207.       3.4 An initialization routine  . . . . . . . . . . . . . . . . .  251
  208.       3.5 A signal routine . . . . . . . . . . . . . . . . . . . . . .  252
  209.       3.4 Using the script file MakeMod  . . . . . . . . . . . . . . .  252
  210.       3.5 The interface compiler CompInterface . . . . . . . . . . . .  253
  211.     4 Calling internal Comal routines from modules . . . . . . . . . .  253
  212.     5 Calling comal programmed routines from a module  . . . . . . . .  256
  213.     6 Making a library interface . . . . . . . . . . . . . . . . . . .  257
  214.  
  215.   X. APPENDIX  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  260
  216.     A. Customizing the Comal text  . . . . . . . . . . . . . . . . . .  260
  217.     B. The format of the AREXX macro file  . . . . . . . . . . . . . .  261
  218.     C. Customizing Comal.lib . . . . . . . . . . . . . . . . . . . . .  262
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.                                           4
  230.  
  231.  
  232.  
  233.  
  234.  
  235.   I. GETTING STARTED
  236.  
  237.  
  238.   1 Hardware requierements.
  239.  
  240.   The Comal  programming system  will run  on any  Amiga computer having at
  241.   least 1 megabyte of main memory and one diskette drive.
  242.  
  243.   Although one disk drive will suffice an extra disk drive (or a hard disk) is
  244.   recommended.
  245.  
  246.  
  247.  
  248.   2 Software requirements.
  249.  
  250.   Comal requires Workbench 1.3 or higher to run.
  251.  
  252.   To be able to use the Comal Intuition Tool (CIT) Workbench 2.04 or higher
  253.   is needed.
  254.  
  255.  
  256.  
  257.   3 Creating a backup disk.
  258.  
  259.   Comal is supplied on two 3.5" floppy disks named Comal  and Comal.Extras.
  260.   Before installing Comal, make a backup copy of the original disks and store
  261.   these in a safe place.
  262.  
  263.   Before doing this make sure that the disks are write protected (you should
  264.   be able to look through the small hole in the plastic disk cover).
  265.  
  266.   If your Amiga has only one disk drive the backup is done in this way:
  267.  
  268.   1.  Put the write protected Comal (Comal.Extras) disk into a disk drive.
  269.  
  270.   2.  Select the Comal (Comal.Extras) disk by clicking once on its icon with
  271.       the left mouse button.
  272.  
  273.   3.  Choose the Copy item from the Icons menu (in WB1.3 the duplicate item
  274.       from the  Workbench menu)  and follow the instructions in the reques-
  275.       ters.
  276.  
  277.   4.  After the copy has been made, choose the  Rename item  from the Icons
  278.       menu (the  Workbench menu  in WB1.3)  and remove  the "copy_of_" from
  279.       the name.
  280.  
  281.   If your Amiga has two disk drives the backup is done in this way:
  282.  
  283.   1.  Put the write protected Comal (Comal.Extras) disk into one disk drive.
  284.  
  285.  
  286.                                           5
  287.  
  288.  
  289.  
  290.  
  291.  
  292.   2.  Write enable a blank floppy disk and put it into the other disk drive.
  293.  
  294.   3.  Select the Comal (Comal.Extras) disk by clicking once on its icon with
  295.       the left mouse button and drag it on top of the icon of the blank disk.
  296.  
  297.   4.  After the copy, remove the original Comal (Comal.Extras) disk from the
  298.       disk drive, select the "copy_of_Comal" ("copy_of_Comal.Extras") disk by
  299.       clicking on its icon with the left mouse button and choose the Rename
  300.       item from the Icons  menu (the  Workbench menu  in WB1.3)  and remove
  301.       the "copy_of_" from the name.
  302.  
  303.  
  304.  
  305.   4 Installing Comal on a floppy disk system.
  306.  
  307.   The disk  named Comal  is ready  to use. Put the copy of this disk into a
  308.   disk drive and open the disk by double clicking on its icon.
  309.  
  310.  
  311.  
  312.   5 Installing Comal on a hard disk system.
  313.  
  314.   Put the copy of your Comal.Extras disk into a disk drive and open the disk
  315.   by double clicking on its icon.
  316.  
  317.   Make an  empty drawer  on your  hard disk by using the New drawer item in
  318.   the Window menu (use the empty drawer in WB1.3) and  give the  drawer the
  319.   name Comal (or another name). Select InstallHD by clicking on its icon with
  320.   the left mouse button. Press the shift key and double click on the icon of
  321.   the newly created drawer.
  322.  
  323.   As an alternative to creating a new drawer your self you may just start the
  324.   InstallHD program by double clicking on its icon. Then you will be promp-
  325.   ted for  the name  of the destination drawer (that will be created if not
  326.   found).
  327.  
  328.   During the installation you will be asked to put in the other disk and you
  329.   will be asked if the ARexx demo scripts should be copied to the Rexx: di-
  330.   rectory (if ARexx is installed).
  331.  
  332.   The InstallHD program does not do anything else than copying needed files
  333.   to the selected drawer and (if you accepted) ARexx scripts to Rexx:.
  334.  
  335.  
  336.  
  337.   6 Starting Comal from Workbench.
  338.  
  339.   Comal may  be started  from Workbench  in the  normal Amiga way by double
  340.   clicking on the Comal icon.
  341.  
  342.  
  343.                                           6
  344.  
  345.  
  346.  
  347.  
  348.  
  349.   If you are using a one drive Amiga system you will be asked to change disk
  350.   once during the loading (Comal has to load some disk based libraries). Nor-
  351.   mally this is only the first time you are starting Comal. The next time the
  352.   libraries are already loaded.
  353.  
  354.   In stead of double clicking on the Comal icon you may click on the icon of
  355.   a Comal program text (an ASCII text containing a Comal program). By doing
  356.   this Comal will be started and the program will be loaded into the editor.
  357.  
  358.  
  359.  
  360.   7 Starting Comal from the Shell (the CLI).
  361.  
  362.   Comal may be started from the Shell by executing the command:
  363.  
  364.     Comal
  365.  
  366.   or by executing the command
  367.  
  368.     Comal Program
  369.  
  370.   where Program  is the  name of  a Comal  program preceded  by the path to
  371.   the directory containing the program.
  372.  
  373.   Example:
  374.  
  375.     Comal CITDemos/TinyPaint
  376.  
  377.  
  378.   If you are specifying a program name, Comal will be started and  the pro-
  379.   gram will be loaded. The current directory will be the directory containing
  380.   the program.
  381.  
  382.  
  383.  
  384.   8 Setting the Comal environment.
  385.  
  386.   Several parameters  used by  the Comal programming environment may be set
  387.   either by using the  standard Workbench  info requester  or by  using the
  388.   Prefs program found in the Prefs drawer.
  389.  
  390.                                           7
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.   8.1 Setting the Comal TOOLTYPES.
  399.    
  400.   The info  requester can be displayed by selecting the Comal icon and then
  401.   select the Information... item from the  Icons menu  in Workbench (WB1.3:
  402.   select the Info item in the Workbench menu).
  403.  
  404.   The field  Tool Types  inside the Info requester is where you can set the
  405.   Comal parameters. Each of the parameter are set by using one line  of the
  406.   format:
  407.  
  408.     TOOLTYPE=ToolValue
  409.  
  410.  
  411.   The TOOLTYPE's and the ToolValue's you can use are described below. 
  412.  
  413.  
  414.     SCREEN
  415.  
  416.       By using the SCREEN tool type you select if Comal should open its own
  417.       screen or use the workbench screen. The possible tool values  are the
  418.       name of a public screen to be used (if the screen is not found it will
  419.       be created).
  420.  
  421.       Example:  SCREEN=Comal
  422.  
  423.       The only legal value for WB1.3 users is Workbench.
  424.  
  425.       The default value is a private screen.
  426.  
  427.  
  428.     DEPTH
  429.  
  430.       By using  the DEPTH  tool type  you select  depth of  the screen. The
  431.       default value is 2.
  432.  
  433.       Example:  DEPTH=4
  434.  
  435.  
  436.     LANGUAGE
  437.  
  438.       By using this tool type you may select the language of the texts used
  439.       in the Comal system.
  440.  
  441.       Example:  LANGUAGE=dansk
  442.  
  443.       The default language is English.
  444.  
  445.  
  446.  
  447.                                           8
  448.  
  449.  
  450.  
  451.  
  452.  
  453.     WINDOW
  454.  
  455.       By using this tool type you select the position and size of the editor
  456.       window at start. The format is
  457.  
  458.         WINDOW=LeftEdge,TopEdge,Width,Height
  459.  
  460.       Example:  WINDOW=95,30,540,200
  461.  
  462.  
  463.     ENTERMODE
  464.  
  465.       Selects the effect of the enter key. The tool values are Down and In-
  466.       sert. If you choose Insert the cursor is moved down and a  new, empty
  467.       line is  inserted each  time the  ENTER key is pressed. If you choose
  468.       Down the cursor is moved down but no  new line  is inserted.  The de-
  469.       fault value is Insert.
  470.  
  471.       Example:  ENTERMODE=Down
  472.  
  473.       The  behavior  of  the  ENTER  key  may at any time be changed inside
  474.       Comal.
  475.  
  476.  
  477.     KEYWORD
  478.  
  479.       Selects the letters used to list keywords. The tool values are Capital
  480.       and Small. The default value is Capital.
  481.  
  482.       Example:  KEYWORD=Small
  483.  
  484.       This parameter may at any time be changed inside Comal.
  485.  
  486.  
  487.     BACKUP
  488.  
  489.       Selects the  backup option.  The tool  values are On and Off. If on a
  490.       backup file is created each time a program text is stored on disk. The
  491.       default value is On.
  492.  
  493.       Example:  BACKUP=Off
  494.  
  495.       This parameter may at any time be changed inside Comal.
  496.  
  497.  
  498.     ICON
  499.  
  500.       Selects the icon option. The tool values are On and Off. If on an icon
  501.       is created when a program is stored on disk. If the program is stored
  502.       as a text file, this icon can be used to start Comal and load the pro-
  503.  
  504.                                           9
  505.  
  506.  
  507.  
  508.  
  509.  
  510.       gram. If it is stored as a code file, the icon can be used to start exe-
  511.       cution of the program (without loading the editor). The default value is
  512.       On.
  513.  
  514.       Example:  ICON=Off
  515.  
  516.       This parameter may at any time be changed inside Comal.
  517.  
  518.  
  519.     LINEEND
  520.  
  521.       Selects the lines are terminated in text files. The tool values are LF,
  522.       CR, CR+LF and PC. DThe default value is LF (standard Amiga).
  523.  
  524.       Example:  LINEEND=CR+LF
  525.  
  526.       This parameter may at any time be changed inside Comal.
  527.  
  528.  
  529.     AUTOVAR
  530.  
  531.       This tool type is used to select if a running program should create va-
  532.       riables automatically or if all variables has to be declared in a DIM or
  533.       LOCAL statement before use. The default value is On.
  534.  
  535.       Example:  AUTOVAR=Off
  536.  
  537.       This parameter may at any time be changed inside Comal.
  538.  
  539.  
  540.     EXECWINDOW
  541.  
  542.       This tool type is used to select if a running program should open the
  543.       standard execute window (used  by  PRINT,  INPUT  etc.).  The default
  544.       value is On.
  545.  
  546.       Example:  EXECWINDOW=Off
  547.  
  548.       This parameter may at any time be changed inside Comal.
  549.  
  550.  
  551.     PROGRAM
  552.  
  553.       Selects the  size of  the program  buffer. The default value is 25000
  554.       bytes.
  555.  
  556.       Example:  PROGRAM=20000
  557.  
  558.  
  559.  
  560.  
  561.                                          10
  562.  
  563.  
  564.  
  565.  
  566.  
  567.     WORKSPACE
  568.  
  569.       Selects the size of the workspace used by a running  program. The de-
  570.       fault value is 75000 bytes.
  571.  
  572.       Example:  WORKSPACE=60000
  573.  
  574.  
  575.     STACK
  576.  
  577.       Selects the size of the stack for a running program. The default value
  578.       is 8Kb.
  579.  
  580.       Example:  STACK=16000
  581.  
  582.  
  583.     MACRO
  584.  
  585.       By using this tool type you select the name of the file that contains
  586.       the macro definitions that will be assigned to the function keys. The
  587.       default file is Comal.Macro.
  588.  
  589.       Example:  MACRO=Comal:MyMacro
  590.  
  591.  
  592.  
  593.   The tool types (except the SCREEN and DEPTH  tool types)  can be  used in
  594.   icons for program texts. If this is done, only the parameters for that pro-
  595.   ject is affected. If another project is started (see section 3.1) the standard
  596.   parameters or the values set in the Comal icon is used.
  597.  
  598.   The parameter  values put  into the  Comal icon  is read even if Comal is
  599.   started from the Shell.
  600.  
  601.  
  602.  
  603.   8.2 The Preferences program Pref.
  604.  
  605.   Most of the parameters  that can  be set  by using  the TOOLTYPES  in the
  606.   Comal info  requester can  be set  in a much more comfortable way by run-
  607.   ning the program Prefs in the Prefs drawer.
  608.  
  609.   NOTE: Workbench 1.3 users can only set the language in this way.
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.                                          11
  619.  
  620.  
  621.  
  622.  
  623.  
  624.   II. TUTORIAL
  625.  
  626.   This chapter is intented to help beginners through the first difficult steps
  627.   in making their first programs. You will learn to make simple programs, to
  628.   use some of the menus in Comal and to debug your program.
  629.  
  630.   Skilled programmers may skip this chapter or just skim it.
  631.  
  632.  
  633.   1 Your first Comal programs.
  634.  
  635.   Having started Comal by clicking on its icon you will  se a  window - the
  636.   edit window. This window is used to type in your programs.
  637.  
  638.   Start by entering this program consisting of only one line:
  639.  
  640.     print "Hello there!"
  641.  
  642.   and press  <ENTER>. Nothing happens except that the word print is rewrit-
  643.   ten in capital.
  644.  
  645.   Now, let's try to execute it. Press the mouse menu button and  select the
  646.   Execute item  in the  Program menu  (or use the alternative short form of
  647.   this menu selection: <right Amiga>+<E>). As  a  result  a  new  window is
  648.   opened (the  output window)  and the text Hello there! is printed in this
  649.   window. After that the edit window is brought to front again.
  650.  
  651.   Let's remove this program and make  a little  longer program.  Select the
  652.   Clear Program  Buffer menu  item from the Project menu. As a result a re-
  653.   quester will pop up. This is because the  program you  just made  has not
  654.   been saved on disk. You will probably not want to save this little program,
  655.   so just click on Yes. The edit window will now be cleared and the execute
  656.   window will disappear.
  657.  
  658.   Enter this program:
  659.  
  660.     INPUT AT 10,5: "Type in your name: ": Name$
  661.  
  662.     PAGE  // Erase window
  663.  
  664.     PRINT AT 10,20: "Hello ",Name$,"!"
  665.     PRINT
  666.     PRINT AT 12,20: "Welcome to Comal."
  667.  
  668.  
  669.  
  670.   Remember to press <ENTER> after each line. Be careful to type in excactly
  671.   the same as shown. If you do not the Comal  system will  probably ask you
  672.   to correct the line.
  673.  
  674.  
  675.                                          12
  676.  
  677.  
  678.  
  679.  
  680.  
  681.   Let's execute this program. Select the Execute menu item from the Program
  682.   menu (or use the short form: <right Amiga>+<E>). As a  result the execute
  683.   window will  again be  opened and  you are asked to type in your name. Do
  684.   that and terminate by pressing <ENTER>. The window will be  cleared and a
  685.   text will be printed.
  686.  
  687.   If you  did not  typed excactly  as shown  the program may stop, an error
  688.   message will be printed in the status line of the edit window and the cur-
  689.   sor will be positioned on (or just after) the place where the error was de-
  690.   tected. Correct the error and execute the program again.
  691.  
  692.   If the program terminates without error you will notice that the edit win-
  693.   dow will be brought to front, so that you cannot see the text. This is bad.
  694.  
  695.   Use the  cursor keys  or the  mouse to  move the cursor to the end of the
  696.   program and add this line:
  697.  
  698.     WAIT 3  // Wait 3 secs
  699.  
  700.  
  701.   Run the program again  (<right Amiga>+<E>).  The program  waits 3 seconds
  702.   before it stops. Then you have the time to see the output.
  703.  
  704.  
  705.  
  706.   2 Working with graphics.
  707.  
  708.   In this and the following sections we will make programs that draws small
  709.   figures in the window. But before we continue, you should  clear the pro-
  710.   gram buffer.  Use the  the Clear  Program Buffer menu item in the Project
  711.   menu.
  712.  
  713.   Comal is an interactive programming language. This means that you can ex-
  714.   ecute commands  immediately without  putting them into a program. We will
  715.   use this facility to show you how some of the drawing routines works.
  716.  
  717.   Select the Open Command  Window item  from the  Project menu  (or use the
  718.   short form:  <right Amiga>+<K>). As a result a little window (the command
  719.   window) will appear in the top left corner of your screen. In this window
  720.   some of  the Comal  statements may  be executed  as commands. Try for in-
  721.   stance to write this line:
  722.  
  723.     PRINT 2+3
  724.  
  725.   and press <ENTER>. The expression will be calculated  and the  result (5)
  726.   will be printed at once.
  727.  
  728.   To be able to use the graphics routine you have to link one of the graphics
  729.   modules Graphics and Turtle into the system. We will choose Turtle.
  730.  
  731.  
  732.                                          13
  733.  
  734.  
  735.  
  736.  
  737.  
  738.   The linking is done by executing the line:
  739.  
  740.     USE Turtle
  741.  
  742.  
  743.   Type  this  line  into  the  command  window  and  terminate  by pressing
  744.   <ENTER>.  Comal  reads  the  module  from disk and makes all the routines
  745.   within this module accessible.
  746.  
  747.   Before you can make drawings, you have to open the  graphics system. This
  748.   is done by writing:
  749.  
  750.     graphicscreen(0)
  751.  
  752.   (remember to press <ENTER>).
  753.  
  754.   If you  have typed in commands as above the execute window will be opened
  755.   and a small triangle (a turtle) will be drawn in the middle of the window.
  756.  
  757.   Now we are ready to use the graphics routines in the Turtle module. Let's
  758.   move the turtle forward. This is done by writing the line
  759.  
  760.     forward(50)
  761.  
  762.   (remember <ENTER>).  The result is that the turtle is moved 50 units for-
  763.   ward and a line is drawn behind it.
  764.  
  765.   The turtle may be turned in any direction. This is done by writing the line
  766.  
  767.     right(90)
  768.  
  769.   which turns the turtle 90o to the right.
  770.  
  771.   If you repeat these two commands three more times (each repetition is most
  772.   easily done  by moving  the cursor up two lines and then pressing <ENTER>
  773.   twice) a nice square will be drawn.
  774.  
  775.   In the Turtle module there are a lot of different graphics routines. Read
  776.   more about these in the description of the graphics modules.
  777.  
  778.   Before we leave this section you should close the graphics system by wri-
  779.   ting the line:
  780.  
  781.     textscreen
  782.  
  783.   and then close the command window by clicking on its close gadget  in the
  784.   upper left corner of the window.
  785.  
  786.  
  787.  
  788.  
  789.                                          14
  790.  
  791.  
  792.  
  793.  
  794.  
  795.   3 Repetition.
  796.  
  797.   The drawing  routines used  in the preceeding section may be used as pro-
  798.   gram statements as well. Here is a program that draws the square from that
  799.   section:
  800.  
  801.  
  802.     // Program 3.1
  803.  
  804.     USE Turtle
  805.  
  806.     graphicscreen(0)  // Open the graphics system
  807.  
  808.     forward(50)       // Draw a square
  809.     right(90)
  810.     forward(50)
  811.     right(90)
  812.     forward(50)
  813.     right(90)
  814.     forward(50)
  815.     right(90)
  816.  
  817.     WAIT 4            // Time to look at the drawing
  818.  
  819.     textscreen        // Close the graphics system
  820.  
  821.  
  822.   You may type in the program in the editor or load it from disk where it is
  823.   stored. Select the Open... menu item in the Project menu (or use the short
  824.   form: <right Amiga>+<O>). A file requester will open.
  825.  
  826.   Click on the scroll bar in the right side of the requester and move it to
  827.   the bottom. Then click on the name Tutorial which will be written  in the
  828.   drawer field  of the requester (alternatively you may just write the name
  829.   Tutorial in this field). Now select the file Prg3.1 and then press the OK
  830.   gadget. As a result the program will be loaded.
  831.  
  832.   Try to  execute the  program (<right  Amiga>+<E>). It  should draw a nice
  833.   square in the execute window. The program will  wait four  seconds before
  834.   the edit window will be brought to front.
  835.  
  836.   In the program, the two statements:
  837.  
  838.     forward(50)
  839.     right(90)
  840.  
  841.   are repeated  four times.  The program can be made more elegant by making
  842.   the Comal system automatically repeat the two statements. This can be done
  843.   by using the LOOP statement:
  844.  
  845.  
  846.                                          15
  847.  
  848.  
  849.  
  850.  
  851.  
  852.     LOOP 4 TIMES
  853.         :
  854.       statements to be repeated
  855.         :
  856.     ENDLOOP
  857.  
  858.  
  859.   Let's try to modify the program. Move the cursor to line number 9 (use the
  860.   cursor keys or the mouse). Select the Mark Block Start  menu item  in the
  861.   Edit menu  (or short: <right Amiga>+<B>). The editor will change to block
  862.   mode (which is written in the status line) and the cursor line (line 9) is
  863.   written in  blue (red  in WB 1.3). Move the cursor down to line number 14
  864.   using the cursor key (the mouse cannot be  used in  block mode).  As seen
  865.   the lines 9-14 are marked as a block.
  866.  
  867.   Now delete this block by selecting the Erase menu item. As a result a re-
  868.   quester will pop up and you are requested to confirm. Press the Yes gadget
  869.   to accept the operation.
  870.  
  871.   Move the cursor three lines up (to line 6) and press <ENTER> to insert an
  872.   extra line. Write the line
  873.  
  874.     LOOP 4 TIMES
  875.  
  876.   and don't press <ENTER>. If you did press <ENTER> an extra line  has been
  877.   inserted. Delete this by pressing <shift>+<Del>. Move the cursor down three
  878.   lines (line 10 just after right(90)). Note that the lines are indented while
  879.   you are moving down.
  880.  
  881.   Write the line
  882.  
  883.     ENDLOOP
  884.  
  885.   and press <ENTER> to insert an extra line.
  886.  
  887.   May be  you should change the program header line (line 1). Move the cur-
  888.   sor to the end of this line and delete the last 1 by pressing  back space
  889.   (the key  on the  left side of the Del key above the <ENTER> key). Change
  890.   the line to:
  891.  
  892.     // Program 3.2
  893.  
  894.  
  895.   The changed program should now look like:
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.                                          16
  904.  
  905.  
  906.  
  907.  
  908.  
  909.     // Program 3.2
  910.  
  911.     USE Turtle
  912.  
  913.     graphicscreen(0)  // Open the graphics system
  914.  
  915.     LOOP 4 TIMES
  916.       forward(50)     // Draw a square
  917.       right(90)
  918.     ENDLOOP
  919.  
  920.     WAIT 4            // Time to look at the drawing
  921.  
  922.     textscreen        // Close the graphics system
  923.  
  924.  
  925.   Try to execute the program to make sure that it works just as before.
  926.  
  927.   Save the program on the RAM: disk (just as an exercise). Select  the Save
  928.   As... menu  item in the Project menu (short form: <right Amiga>+<A>). The
  929.   file requester will open. Select Disks  and RAM: and write the name Prg3.2
  930.   in the  File text field of the requester. Then save by clicking on the OK
  931.   gadget (or by pressing <ENTER>).
  932.  
  933.   By using the LOOP statement it  is easy  to make  the program  draw other
  934.   figures. Change the LOOP section to
  935.  
  936.     LOOP 3 TIMES
  937.       forward(50)
  938.       right(120)
  939.     ENDLOOP
  940.  
  941.   to draw a triangle, or to
  942.  
  943.     LOOP 6 TIMES
  944.       forward(50)
  945.       right(60)
  946.     ENDLOOP
  947.  
  948.   to draw a hexagon. Or try this funny little figure by changing it to
  949.  
  950.     LOOP 20 TIMES
  951.       forward(50)
  952.       right(168)
  953.     ENDLOOP
  954.  
  955.  
  956.   Comal  contains  a  number  of other repetition statements: WHILE, REPEAT
  957.   and FOR statements. Se chapter IV for a complete description.
  958.  
  959.  
  960.                                          17
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.   4 Selection.
  968.  
  969.   In section 3 we learned to draw triangles, squares etc. In this chapter we
  970.   will make  a program  that can draw any of these figures dependent of the
  971.   users choice.
  972.  
  973.   A skeleton for such a program would be:
  974.  
  975.     Program figures
  976.       initialize
  977.       print the possible choices
  978.       get users choice
  979.       draw the chosen figure
  980.  
  981.  
  982.   The initialization is simply:
  983.  
  984.     graphicscreen(0)
  985.  
  986.  
  987.   The printing section could be made in this way:
  988.  
  989.     PRINT AT 6,10: "Triangle ........ 3"
  990.     PRINT AT 8,10: "Square .......... 4"
  991.     PRINT AT 10,10: "Pentagon ........ 5"
  992.     PRINT AT 12,10: "Hexagon ......... 6"
  993.  
  994.  
  995.   The users choice is made by a single INPUT statement:
  996.  
  997.     INPUT AT 16,10: "Select figure: ": choice
  998.  
  999.  
  1000.   To draw the correct figure we have to use of one of  the selection state-
  1001.   ments in Comal. Here we will use the IF statement:
  1002.  
  1003.     IF choice=3 THEN
  1004.       draw triangle
  1005.     ELIF choice=4 THEN
  1006.       draw square
  1007.     ELIF choice=5 THEN
  1008.       draw pentagon
  1009.     ELIF choice=6 THEN
  1010.       draw hexagon
  1011.     ELSE
  1012.       print error
  1013.     ENDIF
  1014.  
  1015.  
  1016.  
  1017.                                          18
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.   The complete program looks like:
  1024.  
  1025.     // Program 4.1
  1026.  
  1027.     USE Turtle
  1028.  
  1029.     graphicscreen(0)
  1030.     ht
  1031.  
  1032.     PRINT AT 6,10: "Triangle ......... 3"
  1033.     PRINT AT 8,10: "Square ........... 4"
  1034.     PRINT AT 10,10: "Pentagon ......... 5"
  1035.     PRINT AT 12,10: "Hexagon .......... 6"
  1036.  
  1037.     INPUT AT 16,10: "Select figure: ": choice
  1038.  
  1039.     page
  1040.  
  1041.     IF choice=3 THEN    // Triangle
  1042.       LOOP 3 TIMES
  1043.         forward(50)
  1044.         right(120)
  1045.       ENDLOOP
  1046.     ELIF choice=4 THEN  // Square
  1047.       LOOP 4 TIMES
  1048.         forward(50)
  1049.         right(90)
  1050.       ENDLOOP
  1051.     ELIF choice=5 THEN  // Pentagon
  1052.       LOOP 5 TIMES
  1053.         forward(50)
  1054.         right(72)
  1055.       ENDLOOP
  1056.     ELIF choice=6 THEN  // Hexagon
  1057.       LOOP 6 TIMES
  1058.         forward(50)
  1059.         right(60)
  1060.       ENDLOOP
  1061.     ELSE
  1062.       PRINT AT 12,10: "I don't know that figure!"
  1063.     ENDIF
  1064.  
  1065.     WAIT 4
  1066.     textscreen
  1067.  
  1068.  
  1069.   You may  read this program from the disk (<right Amiga>+<O>). The name of
  1070.   the program is Prg4.1). Execute it. Remember that a selection of a number
  1071.   must be terminated by pressing <ENTER>.
  1072.  
  1073.  
  1074.                                          19
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.   5 Procedures.
  1082.  
  1083.   The program  in section  4 would  be more  readable if we could write the
  1084.   selection part in this way:
  1085.  
  1086.     IF choice=3 THEN
  1087.       triangle
  1088.     ELIF choice=4 THEN
  1089.       square
  1090.     ELIF choice=5 THEN
  1091.       pentagon
  1092.     ELIF choice=6 THEN
  1093.       hexagon
  1094.     ELS
  1095.       PRINT AT 12,10: "I don't know that figure!"
  1096.     ENDIF
  1097.  
  1098.  
  1099.   To do this we have to define procedures for each of the  figures in ques-
  1100.   tion. The square procedure for instance would be:
  1101.  
  1102.     PROC square
  1103.       LOOP 4 TIMES
  1104.         forward(50)
  1105.         right(90)
  1106.       ENDLOOP
  1107.     ENDPROC square
  1108.  
  1109.  
  1110.   Let's try to change the program in this way.
  1111.  
  1112.   Load the  program Prg4.1 into the editor (if it is not already there) and
  1113.   move the cursor to line 17  (the first  LOOP statement).  Select the Mark
  1114.   Block Start  menu item in the Edit menu (or short: <right Amiga>+<B>) and
  1115.   move  the  cursor  three  lines  down  (so  that  the  whole LOOP-ENDLOOP
  1116.   structure is marked as a block).
  1117.  
  1118.   Cut the block off the program and move it into the clip board by selecting
  1119.   the Cut menu item in the Edit menu  (short: <right  Amiga>+<X>). Move one
  1120.   line up and press <ENTER> to make an empty line and write triangle in this
  1121.   line (this line works as a replacement for the removed block).
  1122.  
  1123.   Move to the end of the program by  pressing <Ctrl>+<down  arrow>, make an
  1124.   extra empty line by pressing <ENTER> and write
  1125.  
  1126.     PROC triangle
  1127.  
  1128.   and press <ENTER> to move to the next line.
  1129.  
  1130.  
  1131.                                          20
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.   Insert the  block from the clip board by selecting the Paste menu item in
  1138.   the Edit menu (short: <right  Amiga>+<V>)  and  move  to  the  line after
  1139.   ENDLOOP and write:
  1140.  
  1141.     ENDPROC triangle
  1142.  
  1143.   Make similar changes for the other figures. The result should look like:
  1144.  
  1145.     // Program 5.1
  1146.  
  1147.     USE Turtle
  1148.  
  1149.     graphicscreen(0)
  1150.     ht
  1151.  
  1152.     PRINT AT 6,10: "Triangle ......... 3"
  1153.     PRINT AT 8,10: "Square ........... 4"
  1154.     PRINT AT 10,10: "Pentagon ......... 5"
  1155.     PRINT AT 12,10: "Hexagon .......... 6"
  1156.     INPUT AT 16,10: "Select figure: ": choice
  1157.  
  1158.     PAGE
  1159.     IF choice=3 THEN    // Triangle
  1160.       triangle
  1161.     ELIF choice=4 THEN  // Square
  1162.       square
  1163.     ELIF choice=5 THEN  // Pentagon
  1164.       pentagon
  1165.     ELIF choice=6 THEN  // Hexagon
  1166.       hexagon
  1167.     ELSE
  1168.       PRINT AT 12,10: "I don't know that figure!"
  1169.     ENDIF
  1170.  
  1171.     WAIT 4
  1172.     textscreen
  1173.  
  1174.     // ********* end of main program **************
  1175.  
  1176.     PROC triangle
  1177.       LOOP 3 TIMES
  1178.         forward(50)
  1179.         right(120)
  1180.       ENDLOOP
  1181.     ENDPROC triangle
  1182.  
  1183.     PROC square
  1184.       LOOP 4 TIMES
  1185.         forward(50)
  1186.         right(90)
  1187.  
  1188.                                          21
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.       ENDLOOP
  1195.     ENDPROC square
  1196.  
  1197.     PROC pentagon
  1198.       LOOP 5 TIMES
  1199.         forward(50)
  1200.         right(72)
  1201.       ENDLOOP
  1202.     ENDPROC pentagon
  1203.  
  1204.     PROC hexagon
  1205.       LOOP 6 TIMES
  1206.         forward(50)
  1207.         right(60)
  1208.       ENDLOOP
  1209.     ENDPROC hexagon
  1210.  
  1211.  
  1212.   The program is not shorter neither is it faster, but it is much more read-
  1213.   able, since you only need to read the first 30 lines to see what  it does
  1214.   (provided you have used descriptive names).
  1215.  
  1216.   The four  procedures at  the end  of the  program contain almost the same
  1217.   code. We could use this fact to make the program shorter. A general Poly-
  1218.   gon procedure could be made in this way:
  1219.  
  1220.     PROC Polygon(n)
  1221.       LOOP n TIMES
  1222.         forward(50)
  1223.         right(360/n)
  1224.       ENDLOOP
  1225.     ENDPROC Polygon
  1226.  
  1227.  
  1228.   By using this, the four procedures should be changed to (note that the new
  1229.   procedure must be written Polygon and  not polygon  or you  will conflict
  1230.   with one of the procedures in the Turtle module):
  1231.  
  1232.     PROC triangle
  1233.       Polygon(3)
  1234.     ENDPROC triangle
  1235.  
  1236.     PROC square
  1237.       Polygon(4)
  1238.     ENDPROC square
  1239.  
  1240.     PROC pentagon
  1241.       Polygon(5)
  1242.     ENDPROC pentagon
  1243.  
  1244.  
  1245.                                          22
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.     PROC hexagon
  1252.       Polygon(6)
  1253.     ENDPROC hexagon
  1254.  
  1255.  
  1256.   Try to make these changes as an exercise. The changed version is stored on
  1257.   disk under the name Prg5.2. Execute the program to see if it still does the
  1258.   same.
  1259.  
  1260.   One of  the advantages  of using  procedures is  that the program is more
  1261.   readable. But it is also much easier to make changes in a program that uses
  1262.   procedures. Try for instance to type in the following little procedure at the
  1263.   end of your program:
  1264.  
  1265.     PROC Fwrd(length)
  1266.       IF length<10 THEN
  1267.         forward(length)
  1268.       ELSE
  1269.         Fwrd(length/3)
  1270.         left(60)
  1271.         Fwrd(length/3)
  1272.         right(120)
  1273.         Fwrd(length/3)
  1274.         left(60)
  1275.         Fwrd(length/3)
  1276.       ENDIF
  1277.     ENDPROC Fwrd
  1278.  
  1279.   and replace the line forward(50) in the polygon procedure (line 51 in the
  1280.   program Prg5.2) with the line
  1281.  
  1282.     Fwrd(50)
  1283.  
  1284.   Execute the program to see the effect of the changes. It is very surprising!
  1285.  
  1286.  
  1287.   6 Making modules.
  1288.  
  1289.   As you saw in the last section it is a good idea to hide "complicated" code
  1290.   in procedures and put these procedures in a separate section  of the pro-
  1291.   gram. Another  good reason for using procedures is that the same piece of
  1292.   code may be reused. The Polygon procedure is a good  example of  this (it
  1293.   was used four times).
  1294.  
  1295.   The idea  of hiding and reusing code may be developped further by putting
  1296.   the procedures into a module and store this module on disk. This is in fact
  1297.   what has been done in the Turtle module. In this section it will be shown
  1298.   how such a module is made. As an example we will put  the four procedures
  1299.   triangle, square, pentagon and hexagon into a module called Figures so that
  1300.   they can be used in other programs.
  1301.  
  1302.                                          23
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.   First you have to load the program Prg5.2  into the  editor (<rightAmiga>
  1310.   +<O>). Then  go to  the line  before the first procedure (line 32). Press
  1311.   <ENTER> to insert an extra line and write the following in this empty line:
  1312.  
  1313.     MODULE Figures
  1314.  
  1315.  
  1316.   Go to the end of the program (note that the  lines are  being indented as
  1317.   you are moving down), insert an extra line and write:
  1318.  
  1319.     ENDMODULE Figures
  1320.  
  1321.  
  1322.   Now you  have made  an internal  module which  can be tested before it is
  1323.   stored on disk. But the module is not ready for test. You have to USE the
  1324.   Turtle module  inside this  module and you have to tell which ones of the
  1325.   procedures should be made accessible from outside. This is done in special
  1326.   EXPORT statements. The final module should look like this:
  1327.  
  1328.     MODULE Figures
  1329.  
  1330.       USE Turtle
  1331.  
  1332.       EXPORT triangle,square,pentagon,hexagon
  1333.  
  1334.       PROC triangle
  1335.         Polygon(3)
  1336.       ENDPROC triangle
  1337.  
  1338.       PROC square
  1339.         Polygon(4)
  1340.       ENDPROC square
  1341.  
  1342.       PROC pentagon
  1343.         Polygon(5)
  1344.       ENDPROC pentagon
  1345.  
  1346.       PROC hexagon
  1347.         Polygon(6)
  1348.       ENDPROC hexagon
  1349.  
  1350.       PROC Polygon(n)
  1351.         LOOP n TIMES
  1352.           forward(50)
  1353.           right(360/n)
  1354.         ENDLOOP
  1355.       ENDPROC Polygon
  1356.  
  1357.     ENDMODULE Figures
  1358.  
  1359.                                          24
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.   Put the  USE statement  and the  EXPORT statement into the module so that
  1368.   it looks as above.
  1369.  
  1370.   Now let's try to execute the program. Press <right Amiga>+<E> and select 3
  1371.   (triangle) and press <ENTER>.
  1372.  
  1373.   What happened? An error occured! The cursor is placed after the word tri-
  1374.   angle and an error message in the status line tells you that  the name is
  1375.   unknown. This is because you have not told the main program to import the
  1376.   procedures from the module. You have to add the line
  1377.  
  1378.     USE Figures
  1379.  
  1380.   in the start of the program (for instance just after the line: USE Turtle).
  1381.   The start of the main program should look like:
  1382.  
  1383.     // Program 6.1
  1384.  
  1385.     USE Turtle
  1386.     USE Figures
  1387.  
  1388.     graphicscreen(0)
  1389.  
  1390.  
  1391.   Having added  the USE line to your program, you are ready to test the mo-
  1392.   dule once more. This time it should be okay. The program is stored on disk
  1393.   under the name Prg6.1
  1394.  
  1395.   The next step in making a module is to store it on disk.
  1396.  
  1397.   First you  have cut  the module off the program and move it into the clip
  1398.   board. Go to the MODULE line  (line 34  of Prg6.1)  and enter  block mode
  1399.   (<right  Amiga>+<B>).  Move  to  the  ENDMODULE  line  (line 63). Now the
  1400.   whole module is marked as a block. Cut it off the program (<right Amiga>+
  1401.   <X>).
  1402.  
  1403.   As the  next step  you have  to open  a new  project. Select the New menu
  1404.   item in the Project menu (<right  Amiga>+<N>). As  a result  a new editor
  1405.   window will  be opened. It is named Project 2. In fact you have started a
  1406.   new process in the Amiga. In this new  project you  can edit  and execute
  1407.   programs independent  of what  you are doing in the original project. And
  1408.   you can even run programs in the two projects in parallel. But we are not
  1409.   going to do that now.
  1410.  
  1411.   The clip  board we have used is the standard Amiga clip board so that you
  1412.   can get the content from the  newly started  project (and  other programs
  1413.   that uses  this clip  board). Select the Paste menu item in the Edit menu
  1414.   (<right Amiga>+<V>) and the module will be copied into your editor.
  1415.  
  1416.                                          25
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.   And now we have to store it on disk. But in contradiction to what we have
  1424.   done earlier,  where we have stored programs on disk as simple text files
  1425.   (ready to be loaded by any text editor like for instance MEmacs or ED), we
  1426.   have to store it in a special code form.
  1427.  
  1428.   Select the Save... menu item in the Program menu (no short form - sorry!).
  1429.   As a result the well known file requester will open.  Activate the Drawer
  1430.   text field  by clicking on it with your mouse (the left mouse button) and
  1431.   write
  1432.  
  1433.     Comal:Modules
  1434.  
  1435.  
  1436.   Then write the following name into the File text field:
  1437.  
  1438.     Figures.mod
  1439.  
  1440.   Be careful to write it correct! Press <ENTER> (or click on the OK gadget)
  1441.   to store the module.
  1442.  
  1443.   That's all. Close Project 2 by clicking on the close gadget and start your
  1444.   program in Project 1. You will notice that it starts reading the module from
  1445.   disk. But otherwise the program works as before.
  1446.  
  1447.   Store your  program on  disk in the drawer Tutorial under the name Prg6.2
  1448.   (<right Amiga>+<A>).
  1449.  
  1450.  
  1451.   7 Looking into modules.
  1452.  
  1453.   If you are using externale modules stored on disk it may happen  that you
  1454.   want to see the content of a specific module. If there is a written docu-
  1455.   mentation for that module, you may find the  answer to  your questions in
  1456.   this. But if you do not have such a documentation there is another possibi-
  1457.   lity.
  1458.  
  1459.   Load the program Prg6.2 (if it is not already in the editor) and execute it
  1460.   so that  modules are  loaded. Select the Show Modules... menu item in the
  1461.   Program menu (short: <right Amiga>+<H>). As a result a file requester like
  1462.   window will pop up showing you all modules loaded so far.
  1463.  
  1464.   You  may  wonder!  Five  modules  are  shown but you have only loaded the
  1465.   Turtle module and the Figures module. The explanation is easy. The Turtle
  1466.   module itself uses the Graphics module and the System module which itself
  1467.   uses the SystemCode module.
  1468.  
  1469.   Select the Figures module either by pressing <ENTER> or by clicking on the
  1470.   Accept gadget. As a result your Figures module is shown in the editor win-
  1471.   dow. The status line tells you that you are in  module mode  and what the
  1472.  
  1473.                                          26
  1474.  
  1475.  
  1476.  
  1477.  
  1478.  
  1479.   name of  the module  is. In  module mode  you can move around in the text
  1480.   but you cannot edit the text and a lot of functions are disabled.
  1481.  
  1482.   To go back to the main  program select  the Edit  Main Program  menu item
  1483.   in the Edit menu (short: <right Amiga>+<M>).
  1484.  
  1485.   Let's see the loaded modules again (<right Amiga>+<H>).
  1486.  
  1487.   Modules may  be written  in Comal  or they  may be mashine coded modules.
  1488.   The Figures, Turtle and System modules  are Comal  modules while Graphics
  1489.   and SystemCode are mashine coded modules. Select the Graphics module (for
  1490.   instance by double clicking on the name).
  1491.  
  1492.   This time a new window is opened. The source of the module  is not shown,
  1493.   but an  interface containing  all the procedures and functions are shown.
  1494.   Move around in the text by using the cursor keys  or by  using the scroll
  1495.   bars. Click  on the  close gadget in the top left corner of the window to
  1496.   remove the window.
  1497.  
  1498.   Try to look into the other modules, for instance the Turtle module. It is a
  1499.   large and  rather complicated module that will convince you of the advan-
  1500.   tage of hiding code in modules.
  1501.  
  1502.  
  1503.   8 Making gadgets.
  1504.  
  1505.   The programs  in sections  4-6 used  the INPUT  statement to  get a users
  1506.   choice. This  is somewhat old fashioned. A better and more Amiga like me-
  1507.   thod is to use gadgets so that the user can press on  the relevant gadget
  1508.   by using the mouse.
  1509.  
  1510.   By using the CIT-modules (CIT is short for Comal Intuition Tool) it is rela-
  1511.   tively easy to make  programs with  gadgets. NOTE!  CIT can  only be used
  1512.   with WB2.04 or higher.
  1513.  
  1514.   Load the program Prg6.1 or Prg6.2 (if not already in the editor). First add
  1515.   two USE lines specifying the CIT-modules we are going to  use: CITWindows
  1516.   and CITGadgets. The start of the program should look like this:
  1517.  
  1518.     // Program 6.1
  1519.  
  1520.     USE CITWindow
  1521.     USE CITGadgets
  1522.     USE Turtle
  1523.     USE Figures
  1524.  
  1525.     graphicscreen(0)
  1526.     ht
  1527.  
  1528.  
  1529.  
  1530.                                          27
  1531.  
  1532.  
  1533.  
  1534.  
  1535.  
  1536.   First we'll make a gadget for the triangle. This is done by executing a DIM
  1537.   statement of the form:
  1538.  
  1539.     DIM TriangleGad OF ButtonGadget
  1540.  
  1541.  
  1542.   The gadget is a simple ButtonGadget. By using CIT a lot of  other gadgets
  1543.   can be made, but in this section only button gadgets will be used.
  1544.  
  1545.   We have  to tell  CIT what the size of the gadget should be and where the
  1546.   gadget is to be placed. This is done in the following statements:
  1547.  
  1548.     TriangleGad.Size(120,20)    // Width = 120 and height = 20 pixels
  1549.     TriangleGad.Position(0,0)   // The upper left corner of the window
  1550.  
  1551.  
  1552.   The point between TriangleGad and Size/Position  indicates that  Size and
  1553.   Position are in fact methods in a data structure. Read chapter IV.8 if you
  1554.   want to know more about methods  and objects.  But here  you do  not need
  1555.   think more about that (just write as shown).
  1556.  
  1557.   Inside the gadget we want the label Triangle. This is specified in this way:
  1558.  
  1559.     TriangleGad.Label("Triangle",INSIDE)
  1560.  
  1561.  
  1562.   Now we have specified the layout and the position of the gadget. It is in-
  1563.   serted in the standard Comal window in this way:
  1564.  
  1565.     ComalWindow.InsObject(TriangleGad,Error)
  1566.  
  1567.  
  1568.   As a result of executing this statement the gadget will be visible in the
  1569.   window. If  an error  occurs an error message is returned in the variable
  1570.   Error. We will not test for errors until all gadgets are made.
  1571.  
  1572.   The gadgets for the other figures are made in the same way:
  1573.  
  1574.     DIM SquareGad OF ButtonGadget
  1575.     SquareGad.Size(120,20)
  1576.     SquareGad.Position(120,0)
  1577.     SquareGad.Label("Square",INSIDE)
  1578.     ComalWindow.InsObject(SquareGad,Error)
  1579.  
  1580.     DIM PentagonGad OF ButtonGadget
  1581.     PentagonGad.Size(120,20)
  1582.     PentagonGad.Position(240,0)
  1583.     PentagonGad.Label("Pentagon",INSIDE)
  1584.     ComalWindow.InsObject(PentagonGad,Error)
  1585.  
  1586.  
  1587.                                          28
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.     DIM HexagonGad OF ButtonGadget
  1594.     HexagonGad.Size(120,20)
  1595.     HexagonGad.Position(360,0)
  1596.     HexagonGad.Label("Hexagon",INSIDE)
  1597.     ComalWindow.InsObject(HexagonGad,Error)
  1598.  
  1599.  
  1600.   To be able to stop the program we have to add a Close gadget. This is also
  1601.   a button gadget and it is placed to the right of all the other gadgets:
  1602.  
  1603.     DIM Close OF ButtonGadget
  1604.     Close.Size(138,20)
  1605.     Close.Position(480,0)
  1606.     Close.Label("STOP",INSIDE)
  1607.     ComalWindow.InsObject(Close,Error)
  1608.  
  1609.  
  1610.   Now it's time to test for errors:
  1611.  
  1612.     IF Error THEN
  1613.       STOP "Could not create one or more gadgets"
  1614.     ENDIF
  1615.  
  1616.  
  1617.   To prevent  the graphics  routines from  overwriting the  gadgets we will
  1618.   change the graphics viewport:
  1619.  
  1620.     viewport(0,width-1,0,height-20)
  1621.  
  1622.  
  1623.   Having made all the gadgets we are entering a loop where we  can wait for
  1624.   some buttons  to be pressed. The loop terminates when the Close button is
  1625.   pressed:
  1626.  
  1627.  
  1628.     REPEAT
  1629.       WAIT
  1630.       clearscreen  
  1631.       IF TriangleGad.Pressed THEN
  1632.         triangle
  1633.       ELIF SquareGad.Pressed THEN
  1634.         square
  1635.       ELIF PentagonGad.Pressed THEN
  1636.         pentagon
  1637.       ELIF HexagonGad.Pressed THEN
  1638.         hexagon
  1639.       ENDIF
  1640.     UNTIL Close.Pressed
  1641.  
  1642.  
  1643.  
  1644.                                          29
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.   The last statement in the main program closes the graphics system:
  1651.  
  1652.     textscreen
  1653.  
  1654.  
  1655.   The complete program looks:
  1656.  
  1657.     // Program 8.1
  1658.  
  1659.     USE CITWindow
  1660.     USE CITGadgets
  1661.     USE Turtle
  1662.     USE Figures
  1663.  
  1664.     graphicscreen(0)
  1665.     ht
  1666.  
  1667.     DIM TriangleGad OF ButtonGadget
  1668.     TriangleGad.Size(120,20)
  1669.     TriangleGad.Position(0,0)
  1670.     TriangleGad.Label("Triangle",INSIDE)
  1671.     ComalWindow.InsObject(TriangleGad,Error)
  1672.  
  1673.     DIM SquareGad OF ButtonGadget
  1674.     SquareGad.Size(120,20)
  1675.     SquareGad.Position(120,0)
  1676.     SquareGad.Label("Square",INSIDE)
  1677.     ComalWindow.InsObject(SquareGad,Error)
  1678.  
  1679.     DIM PentagonGad OF ButtonGadget
  1680.     PentagonGad.Size(120,20)
  1681.     PentagonGad.Position(240,0)
  1682.     PentagonGad.Label("Pentagon",INSIDE)
  1683.     ComalWindow.InsObject(PentagonGad,Error)
  1684.  
  1685.     DIM HexagonGad OF ButtonGadget
  1686.     HexagonGad.Size(120,20)
  1687.     HexagonGad.Position(360,0)
  1688.     HexagonGad.Label("Hexagon",INSIDE)
  1689.     ComalWindow.InsObject(HexagonGad,Error)
  1690.  
  1691.     DIM Close OF ButtonGadget
  1692.     Close.Size(138,20)
  1693.     Close.Position(480,0)
  1694.     Close.Label("STOP",INSIDE)
  1695.     ComalWindow.InsObject(Close,Error)
  1696.  
  1697.     IF Error THEN
  1698.       STOP "Could not create one or more gadgets"
  1699.     ENDIF
  1700.  
  1701.                                          30
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.     viewport(0,width-1,0,height-20)
  1709.  
  1710.     REPEAT
  1711.       WAIT
  1712.       clearscreen  
  1713.       IF TriangleGad.Pressed THEN
  1714.         triangle
  1715.       ELIF SquareGad.Pressed THEN
  1716.         square
  1717.       ELIF PentagonGad.Pressed THEN
  1718.         pentagon
  1719.       ELIF HexagonGad.Pressed THEN
  1720.         hexagon
  1721.       ENDIF
  1722.     UNTIL Close.Pressed
  1723.  
  1724.     textscreen
  1725.  
  1726.  
  1727.   The program is stored on disk under the name Prg8.1.  Execute the program
  1728.   to see how it works. Before the program starts you will notice a lot of disk
  1729.   reading. The CIT system is in fact a rather complicated system and a lot of
  1730.   modules are used.
  1731.  
  1732.  
  1733.  
  1734.   9 Event driven programs.
  1735.  
  1736.   The program in section 8 can be made better. The final loop is in fact un-
  1737.   necessary. Why not let the buttons themselves call the procedures automa-
  1738.   tically?
  1739.  
  1740.   To do  this we  have to add event procedures to each button. Add the fol-
  1741.   lowing lines after the the insertion of the TriangleGad (after line 15 in
  1742.   PRG8.1):
  1743.  
  1744.     TriangleGad.EventHandler(TriangleEvent())
  1745.     PROC TriangleEvent(Id OF USHORT)
  1746.       clearscreen
  1747.       triangle
  1748.     ENDPROC TriangleEvent
  1749.  
  1750.  
  1751.   By doing this you are telling CIT that the procedure TriangleEvent should
  1752.   be called automatically when the triangle button is pressed.
  1753.  
  1754.   Add similar lines after the insertion af the other buttons except the close
  1755.   button.
  1756.  
  1757.  
  1758.                                          31
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.   By using event procedures that are automatically called by CIT the loop can
  1765.   now be changed to this single line:
  1766.  
  1767.     WHILE NOT Close.Pressed DO WAIT
  1768.  
  1769.  
  1770.   The complete program now looks:
  1771.  
  1772.     // Program 9.1
  1773.  
  1774.     USE CITWindow
  1775.     USE CITGadgets
  1776.     USE Turtle
  1777.     USE Figures
  1778.  
  1779.     graphicscreen(0)
  1780.     ht
  1781.  
  1782.     DIM TriangleGad OF ButtonGadget
  1783.     TriangleGad.Size(120,20)
  1784.     TriangleGad.Position(0,0)
  1785.     TriangleGad.Label("Triangle",INSIDE)
  1786.     ComalWindow.InsObject(TriangleGad,Error)
  1787.     TriangleGad.EventHandler(TriangleEvent())
  1788.     PROC TriangleEvent(Id OF USHORT)
  1789.       clearscreen
  1790.       triangle
  1791.     ENDPROC TriangleEvent
  1792.  
  1793.     DIM SquareGad OF ButtonGadget
  1794.     SquareGad.Size(120,20)
  1795.     SquareGad.Position(120,0)
  1796.     SquareGad.Label("Square",INSIDE)
  1797.     SquareGad.EventHandler(SquareEvent())
  1798.     ComalWindow.InsObject(SquareGad,Error)
  1799.     PROC SquareEvent(Id OF USHORT)
  1800.       clearscreen
  1801.       square
  1802.     ENDPROC SquareEvent
  1803.  
  1804.     DIM PentagonGad OF ButtonGadget
  1805.     PentagonGad.Size(120,20)
  1806.     PentagonGad.Position(240,0)
  1807.     PentagonGad.Label("Pentagon",INSIDE)
  1808.     PentagonGad.EventHandler(PentagonEvent())
  1809.     ComalWindow.InsObject(PentagonGad,Error)
  1810.     PROC PentagonEvent(Id OF USHORT)
  1811.       clearscreen
  1812.       pentagon
  1813.     ENDPROC PentagonEvent
  1814.  
  1815.                                          32
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.     DIM HexagonGad OF ButtonGadget
  1823.     HexagonGad.Size(120,20)
  1824.     HexagonGad.Position(360,0)
  1825.     HexagonGad.Label("Hexagon",INSIDE)
  1826.     HexagonGad.EventHandler(HexagonEvent())
  1827.     ComalWindow.InsObject(HexagonGad,Error)
  1828.     PROC HexagonEvent(Id OF USHORT)
  1829.       clearscreen
  1830.       hexagon
  1831.     ENDPROC HexagonEvent
  1832.  
  1833.     DIM Close OF ButtonGadget
  1834.     Close.Size(138,20)
  1835.     Close.Position(480,0)
  1836.     Close.Label("STOP",INSIDE)
  1837.     ComalWindow.InsObject(Close,Error)
  1838.  
  1839.     IF Error THEN
  1840.       STOP "Could not create one or more gadgets"
  1841.     ENDIF
  1842.  
  1843.     viewport(0,width-1,0,height-21)
  1844.  
  1845.     WHILE NOT Close.Pressed DO WAIT
  1846.  
  1847.     textscreen
  1848.  
  1849.  
  1850.   Some programmers may find this program rather strange. It looks as if the
  1851.   program does not do anything but waiting for the close gadget to be pres-
  1852.   sed (in the WHILE statement).
  1853.  
  1854.   But it does! While you are waiting for the close button to be pressed all
  1855.   your event procedures are called automatically.
  1856.  
  1857.   This sort of a program is called an event driven program.
  1858.  
  1859.   The changed  version is stored on disk under the name Prg9.1. Execute the
  1860.   program to see if it still does the same.
  1861.  
  1862.  
  1863.  
  1864.   10 Debugging programs.
  1865.  
  1866.   The Comal system has an integrated debugger that allow you to examine the
  1867.   behavior of your programs. To show how it works enter this little program
  1868.   (that calculates the number 6!=720):
  1869.  
  1870.  
  1871.  
  1872.                                          33
  1873.  
  1874.  
  1875.  
  1876.  
  1877.  
  1878.     // Program 10.1
  1879.  
  1880.     n:=6
  1881.  
  1882.     fak:=1
  1883.     WHILE n>0 DO
  1884.       fak:=fak*n
  1885.       n:=n-1
  1886.     ENDWHILE
  1887.  
  1888.     PRINT fak
  1889.  
  1890.   or load it from disk (Prg10.1 in the Tutorial drawer).
  1891.  
  1892.   Select the Trace Mode? menu item in the Program menu (no short  form). As
  1893.   a result a little window (the watch window) is opned and the first execut-
  1894.   able line (here n:=6) is printed in the reverse pen color. The status line
  1895.   shows that  you are  now in trace mode. In trace mode you can move around
  1896.   in the text but you cannot edit the text and a lot of functions are disab-
  1897.   led.
  1898.  
  1899.   Select the  Execute One Step menu item from the Trace menu (short: <right
  1900.   Amiga>+<T>). As a result the current line will be executed and the next line
  1901.   (fak:=1) is printed in the reverse pen color. Continue to execute steps 4-5
  1902.   times by pressing <right Amiga>+<T>.
  1903.  
  1904.   As you see, you are able to follow the execution step by step. But to exa-
  1905.   mine the execution in detail it is necessary to watch the value of certain
  1906.   expressions. Select  the New  Watch Expression  menu item  from the Trace
  1907.   menu (no short form). A requester will pop up. Write n into the text field
  1908.   of the requester and press <ENTER>  to accept.  Now the  current value of
  1909.   the  variable  n  is  shown  in  the  watch  window. Select the New Watch
  1910.   Expression menu item once more and enter the name fak. Also the  value of
  1911.   this variable  will be  shown in the watch window as soon as you have ac-
  1912.   cepted it.
  1913.  
  1914.   Continue to  execute program  steps (<right  Amiga>+<T>) and  look at the
  1915.   watch window.  The current value of the watch variables are updated after
  1916.   each step.
  1917.  
  1918.   If you have not stepped to the end of the program (the  watch window will
  1919.   close) try  to remove  a watch expression by double clicking on it in the
  1920.   watch window. You will be asked to confirm.
  1921.  
  1922.   Step to the end of the program and start tracing again. The actual line is
  1923.   again n:=0.  The watch  window tells you that the variable is not defined
  1924.   (you has not yet executed the line). Set a break point at line 8 (the line
  1925.   n:=n-1) by double clicking on the line. The line will be marked as a break
  1926.   point line.
  1927.  
  1928.  
  1929.                                          34
  1930.  
  1931.  
  1932.  
  1933.  
  1934.  
  1935.   Start execution by selecting  the Continue  Execution menu  item from the
  1936.   Program menu (short: <right Amiga>+<G>). The execution starts and it stops
  1937.   the first time the break point line is met. Note the value of the watch ex-
  1938.   pression.
  1939.  
  1940.   Remove the break point by double clicking on it once more and execute the
  1941.   program to the end.
  1942.  
  1943.   Let's look at another example. Load the program Prg10.2 from the Tutorial
  1944.   drawer  (<right  Amiga>+<O>).  This  program counts the occurences of one
  1945.   (small) text in another (bigger) text.
  1946.  
  1947.   Enter the trace mode (Program menu) and add  the following  watches: pos,
  1948.   pattern$, text$  and Cnt.  Note that  no one  is defined yet. Single step
  1949.   (<right Amiga>+<T>) 12 times.
  1950.  
  1951.   Note that each time the line :
  1952.  
  1953.     Cnt:=1+Count(pattern$,text$(pos+1..))
  1954.  
  1955.   is executed, the next line to be executed is the first line of the function
  1956.   Count, that is called in this line. This can be avoided by selecting the Exe-
  1957.   cute One Line menu item from the Trace menu (short: <right Amiga>+<L>).
  1958.  
  1959.   By using the Execute One Line command the  whole function  and all recur-
  1960.   sive calls to this function will be executed until execution returns to the
  1961.   same level as before. Try it to see how it works.
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.                                          35
  1987.  
  1988.  
  1989.  
  1990.  
  1991.  
  1992.   III. THE PROGRAMMING ENVIRONMENT
  1993.  
  1994.   After start Comal will open its own screen  and a  window in  this screen
  1995.   (the editor  window) and  you may  start typing in your program or load a
  1996.   program from disk.
  1997.  
  1998.   From within the editor you may  edit programs,  load programs  from disk,
  1999.   start executing programs and much more.
  2000.  
  2001.  
  2002.   1 The keyboard.
  2003.  
  2004.   The editor  works much  like any other editor except that it makes syntax
  2005.   control of all the lines entered and organize the program lines with correct
  2006.   indention etc.
  2007.  
  2008.   All changes will be put into the program buffer immediately. What you see
  2009.   om the screen is the same as is in the buffer. The only exception  is the
  2010.   cursor line. It will not be put into the program buffer before you try to
  2011.   leave the line (by using the cursor keys, the ENTER key or the mouse). By
  2012.   pressing <Esc> the line will be restored to the content of the buffer.
  2013.  
  2014.   Certain keys have special functions. Here is a description of these keys and
  2015.   their functions:
  2016.  
  2017.  
  2018.     <shift>+<cur up>            move to top of window or show
  2019.                                 previous page
  2020.  
  2021.     <Ctrl>+<cur up>             move to start of text
  2022.  
  2023.  
  2024.     <shift>+<cur down>          move to bottom of window or show
  2025.                                 next page
  2026.  
  2027.     <Ctrl>+<cur down>           move to end of text
  2028.  
  2029.  
  2030.     <Alt>+<cur left>            scroll line right
  2031.  
  2032.  
  2033.     <Alt>+<cur right>           scroll line left
  2034.  
  2035.  
  2036.     <Alt>+<cur up>              scroll text down
  2037.  
  2038.  
  2039.     <Alt>+<cur down>            scroll text up
  2040.  
  2041.  
  2042.  
  2043.                                          36
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.     < <- >                      delete character before cursor
  2050.  
  2051.  
  2052.     <Del>                       delete character under cursor
  2053.  
  2054.  
  2055.     <shift>+<Del>               delete cursor line
  2056.  
  2057.  
  2058.     <shift>+<Ins>               toggles insert/replace mode  -  the current
  2059.                                 state is shown in the status line
  2060.  
  2061.  
  2062.     <shift>+<Alt>+<Ins>         insert line
  2063.  
  2064.  
  2065.     <Esc>                       restore line
  2066.  
  2067.  
  2068.  
  2069.   On Amiga's  without the  numeric keys  (Amiga 600) the following replace-
  2070.   ments for the <Ins> key can be used:
  2071.  
  2072.     <shift>+<Ins>         ->    <shift>+<Alt>+<cur right>
  2073.  
  2074.                                     or
  2075.  
  2076.                                 <<Alt>+<RETURN>
  2077.  
  2078.  
  2079.     <shift>+<Alt>+<Ins>   ->    <shift>+<Alt>+<cur down>
  2080.  
  2081.                                     or
  2082.  
  2083.                                 <shift>+<Alt>+<RETURN>
  2084.  
  2085.  
  2086.  
  2087.   2 The mouse.
  2088.  
  2089.   The mouse can be used to move the cursor around in the  the text.  If you
  2090.   move to another line the previous cursor line will be syntax checked and if
  2091.   the syntax is not correct an error message will pop up and cursor will not
  2092.   be moved.
  2093.  
  2094.   On the right side of the editor window you will find a scroll bar. The po-
  2095.   sition of the scroller inside the container shows the approximate position of
  2096.   the window  inside the  whole text and the size of the scroller shows the
  2097.   size of the window compared to the whole text.
  2098.  
  2099.  
  2100.                                          37
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.   By moving the scroller the window is moved  inside the  text. Like before
  2107.   this will result in a syntax controll of the previos cursor line and if the
  2108.   syntax is not correct an error message will pop up and the  scroller (the
  2109.   window) will not be moved.
  2110.  
  2111.  
  2112.   3 The menus.
  2113.  
  2114.   Most of  the commands  that can  be executed  from the editor are reached
  2115.   through the menus.
  2116.  
  2117.  
  2118.   3.1 The Project menu.
  2119.  
  2120.   The Project menu is placed far to the left. It contains the following items:
  2121.  
  2122.     New
  2123.       By selecting this a new project with its own editor window and its own
  2124.       program buffer will be opened.
  2125.  
  2126.     Open
  2127.       A file requester will pop up and you may select the name of a program
  2128.       to load. The program file must be a text file.
  2129.  
  2130.       After the load the name of the file will be shown in the screen title
  2131.       line.
  2132.  
  2133.     Save
  2134.       Store program buffer on disk as a text file. If there is a current name
  2135.       this will be used. Otherwise a requester will pop up.
  2136.  
  2137.     Save As
  2138.       Store program buffer on disk as a text file. A requester will pop up so
  2139.       that you can select a name.
  2140.  
  2141.     File
  2142.       An extended  form of  the file requester will pop up. From this it is
  2143.       possible to rename files, delete files, copy files, move files from one
  2144.       directory to another, make a new directory and a new drawer (a direc-
  2145.       tory with a drawer info file).
  2146.  
  2147.       Delete, copy and move accepts the  selection of  more than  one file.
  2148.       Press the shift key while selecting the next file(s).
  2149.  
  2150.     New Shell
  2151.       A new Shell (CLI) will open.
  2152.  
  2153.     Print
  2154.       Output the program in the program buffer to a printer.
  2155.  
  2156.  
  2157.                                          38
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.     Open Command Window
  2164.       This  will  open  a  command  window  where  you may type in commands
  2165.       like you are used to in other Comal's.
  2166.  
  2167.       There are no special  commands like  LIST, ENTER  etc. The  only com-
  2168.       mands you can use is PRINT, DIR, CHDIR etc.
  2169.  
  2170.     About
  2171.       Useful information about the system will be shown
  2172.  
  2173.     Clear Program Buffer
  2174.       The program  in the program buffer will be erased. You will be warned
  2175.       if the program in the buffer has not been saved since last change.
  2176.  
  2177.     Quit Project
  2178.       The current project will be terminated and if it the only project the
  2179.       Comal system will terminate.
  2180.  
  2181.       You will  be warned  if the  program in the buffer has not been saved
  2182.       since last change.
  2183.  
  2184.  
  2185.   3.2 The Edit menu.
  2186.  
  2187.   The menu to theright  of the  Project menu  is the  Edit menu.  This menu
  2188.   contains the following items:
  2189.  
  2190.     Mark Block Start
  2191.       The cursor line will be one end of a block and it will be printed in the
  2192.       inverse pen color. Select the other  end of  the block  by moving the
  2193.       cursor (cursor up/down, PgUp/Dn) or by moving the scroll bar.
  2194.  
  2195.       The  status  line  will  change  from Insert/Replace to Block and you
  2196.       cannot edit the program.
  2197.  
  2198.       If you are already in block mode this mode will be terminated.
  2199.  
  2200.     Cut
  2201.       The marked block will be cut  off the  text and  moved into  the clip
  2202.       board.
  2203.  
  2204.     Copy
  2205.       A copy of the marked block block will be moved into the clip board
  2206.  
  2207.     Paste
  2208.       The content of the clip board will be inserted in the program.
  2209.  
  2210.     Erase
  2211.       The marked block will be erased. You will be prompted to confirm.
  2212.  
  2213.  
  2214.                                          39
  2215.  
  2216.  
  2217.  
  2218.  
  2219.  
  2220.     Insert file
  2221.       A program text file will be inserted at the cursor line.
  2222.  
  2223.     Save Block
  2224.       Store the marked block on disk as a text file.
  2225.  
  2226.     Print block
  2227.       Print out the marked block.
  2228.  
  2229.     Edit Main Program
  2230.       If the editor contains a module you may turn back to the main program
  2231.       by using this menu.
  2232.  
  2233.  
  2234.  
  2235.   Comal uses the clipboard.device of the Amiga so that blocks  may be moved
  2236.   between different  projects (started by the New item in the Project menu)
  2237.   or other text editors using this device.
  2238.  
  2239.  
  2240.   3.3 The Search menu.
  2241.  
  2242.   The third menu contains only these three items:
  2243.  
  2244.     Search
  2245.       A requester will pop up and you may enter a searh string.
  2246.  
  2247.     Search & Replace
  2248.       As before but also a replace string has to be entered.
  2249.  
  2250.       When a match is found you will be asked if the string should be repla-
  2251.       ced. After the answer the search will continue. Use Esc to abort.
  2252.  
  2253.     Search Again
  2254.       The previous search/search & replace will be resumed.
  2255.  
  2256.  
  2257.   Note that the search is case sensitive.
  2258.  
  2259.  
  2260.  
  2261.   3.4 The Macros menu.
  2262.  
  2263.   A macro  is an  ARexx script  that can be used to add new commands to the
  2264.   editor. The ARexx interface will be described in detail later. Here you will
  2265.   find only a short description of the menu items:
  2266.  
  2267.     Assign Macro
  2268.       This item contains a subitem for each function key (F1..F10).
  2269.  
  2270.  
  2271.                                          40
  2272.  
  2273.  
  2274.  
  2275.  
  2276.  
  2277.       By selecting  one of these a requester will pop up an you may enter a
  2278.       macro string to be assigned to that function key. The macro string may
  2279.       be the  name of  an ARexx  script file  (which must  be placed in the
  2280.       REXX: directory) or an ARexx command.
  2281.  
  2282.     Load
  2283.       Load a complete set of assignments for the function key.
  2284.  
  2285.     Save
  2286.       Save the current set of assignment for the function keys on disk.
  2287.  
  2288.  
  2289.   At the start of a project a macro  file is  read and  assignments for the
  2290.   function keys are made according to the definitions in this file. The name
  2291.   of this file is Comal.macro unless another name is specified by the MACRO
  2292.   tool type (se section I.9).
  2293.  
  2294.   If ARexx is not installed in the system this menu is disabled (goasted).
  2295.  
  2296.  
  2297.  
  2298.   3.5 The Settings menu.
  2299.  
  2300.   In the Settings menu various parameters may be changed. The content is:
  2301.  
  2302.     New Line At <ENTER>
  2303.       If selected a new line will be inserted after the current line when the
  2304.       enter key is pressed.
  2305.  
  2306.     Keywords In Capital
  2307.       Some people prefer small letters. They are more readable they say. With
  2308.       this item  you may  choose to  print keywords  in upper or lower case
  2309.       letters.
  2310.  
  2311.     Create Backup
  2312.       If selected a backup file will be created when a program is saved.
  2313.  
  2314.     Create Icon
  2315.       If selected an icon will be  created  when  a  program  is  saved. By
  2316.       clicking on  this icon  Comal will be started and the program will be
  2317.       loaded.
  2318.  
  2319.       All the options selected in this menu wil be stored in the  tool type
  2320.       array of the icon.
  2321.  
  2322.     Store Window Parameters
  2323.       The window  position and size will be stored along with other parame-
  2324.       ters in the icon (if icon is selected). This is useful if more than one
  2325.       project is loaded at a time.
  2326.  
  2327.  
  2328.                                          41
  2329.  
  2330.  
  2331.  
  2332.  
  2333.  
  2334.     ASCII File Format
  2335.       This item has four subitems:
  2336.  
  2337.         LF      -   line end is LF  (standard Amiga)
  2338.  
  2339.         CR      -   line end is CR
  2340.  
  2341.         CR+LF   -   line end is CR+LF
  2342.  
  2343.         PC      -   program is  stored in PC format (line end is CR+LF) and
  2344.                     characters are converted.
  2345.  
  2346.  
  2347.     Automatic variables?
  2348.       Selects if variables in a program should be created automatically or if
  2349.       they must be declared in a DIM or LOCAL statement before use.
  2350.  
  2351.  
  2352.     Execute IO Window?
  2353.       Selects if  you want an execute window (used by PRINT, INPUT etc.) to
  2354.       be opened. If this window is not open, Comal will send it the Command
  2355.       Window (if open).
  2356.  
  2357.  
  2358.  
  2359.   3.6 The Program menu.
  2360.  
  2361.   Now we come to the importent Program menu:
  2362.  
  2363.  
  2364.     Control
  2365.       The program  is scanned and the structure is checked. Modules USEd by
  2366.       the program are loaded and initialized and finally all functions/proce-
  2367.       dures are  made known  so that  they can be executed from the command
  2368.       window.
  2369.  
  2370.     Execute
  2371.       Program execution starts. During execution the status line is changed to
  2372.       Program execution. It is possible to move around in the program buffer
  2373.       during program execution but no editing can be performed.
  2374.  
  2375.       It is also possible to open another project and start editing or execu-
  2376.       ting a new program.
  2377.  
  2378.     Stop Execution
  2379.       Program execution is stopped.
  2380.  
  2381.     Continue Execution
  2382.       A stopped program can be restarted.
  2383.  
  2384.  
  2385.                                          42
  2386.  
  2387.  
  2388.  
  2389.  
  2390.  
  2391.     Load
  2392.       A program stored by the Save item can be loaded.
  2393.  
  2394.     Save
  2395.       Store program buffer in code form. This should be used to store modu-
  2396.       les.
  2397.  
  2398.     Combine
  2399.       Combines the interpreter, the program and all modules into an execut-
  2400.       able file. A file requester will pop up and you may select the name of
  2401.       the output file.
  2402.  
  2403.     Show Modules
  2404.       A requester like a file requester shows all modules loaded. By selecting
  2405.       one of these modules you may see the content.
  2406.  
  2407.     Remove All Modules
  2408.       All modules loaded is removed.
  2409.  
  2410.     Trace Mode
  2411.       Toggle the trace (debugging) mode.
  2412.  
  2413.  
  2414.  
  2415.   3.7 The Trace menu.
  2416.  
  2417.   This last menu is only active if Trace Mode is on. It contains the following
  2418.   items:
  2419.  
  2420.     Execute One Step
  2421.       One programming step is executed. Then  all watch  expressions in the
  2422.       watch window is updated and control is returned to the editor with the
  2423.       cursor placed on the next line to be  executed (shown  in reverse pen
  2424.       color).
  2425.  
  2426.     Execute One Line
  2427.       One program  line is  executed. Procedures, functions and single line
  2428.       loops are executed. Then all watch expressions in the watch window is
  2429.       updated and control is returned to the editor with the cursor placed on
  2430.       the next line to be executed (shown in reverse pen color).
  2431.  
  2432.     Open Watch Window
  2433.       If you have closed the watch window by clicking on its close gadget it
  2434.       is re-opened.
  2435.  
  2436.     New Watch Expressing
  2437.       A requester  will pop  up and you may enter an expression (like a va-
  2438.       riable, a function name or a more complicated expression). The expres-
  2439.       sion and its current value will be shown in the watch window and will
  2440.       be updated after each program step.
  2441.  
  2442.                                          43
  2443.  
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.       A watch expression can  be removed  by double  clicking on  it in the
  2450.       watch window. You will be prompted to accept.
  2451.  
  2452.     Clear All Watches
  2453.       All watch expressions will be removed. You will be prompted to accept.
  2454.  
  2455.     Clear All Break Points
  2456.       All break points in the program will be removed. You will be prompted
  2457.       to accept.
  2458.  
  2459.  
  2460.   A break point is set by double clicking on a  program line  in the editor
  2461.   while being in trace mode. It is possible to set break points in modules,
  2462.   too.
  2463.  
  2464.   Concerning the use of the debugger see the tutorial chapter (section 7).
  2465.  
  2466.  
  2467.  
  2468.  
  2469.  
  2470.  
  2471.  
  2472.  
  2473.  
  2474.  
  2475.  
  2476.  
  2477.  
  2478.  
  2479.  
  2480.  
  2481.  
  2482.  
  2483.  
  2484.  
  2485.  
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.                                          44
  2500.  
  2501.  
  2502.  
  2503.  
  2504.  
  2505.   IV. DESCRIPTION OF THE Comal LANGUAGE
  2506.  
  2507.  
  2508.   1 Data types, variables and expressions.
  2509.  
  2510.   1.1 Identifiers.
  2511.  
  2512.   Identifiers are used as names of variables, functions, procedures etc.
  2513.  
  2514.   Examples of identifiers are:
  2515.  
  2516.     C   parity    Even    NewName    alfa1    get'key    prg_21
  2517.  
  2518.  
  2519.   An identifier consists of a letter eventually followed by a number of let-
  2520.   ters, digits, underscores (_) or single quotes ('). An identifier may have any
  2521.   length (in fact not longer than 255 characters, but who  would ever reach
  2522.   that limit?). Letters may be national letters such as the danish letters  , O
  2523.   and A.
  2524.  
  2525.   Identifiers may end with a number sign (#) or a dollar sign ($). Such iden-
  2526.   tifiers are used as names of integer or string variables or functions.
  2527.  
  2528.   Upper and lower case letters are destinct. These identifiers are different:
  2529.  
  2530.     newname     NewName   NEWNAME
  2531.  
  2532.  
  2533.   Some identifiers are reserved and are used either as names of predeclared
  2534.   functions or procedures or they are used as names of  Comal language key-
  2535.   words. Examples of reserved words are:
  2536.  
  2537.     sin    inkey$     IF     PROC     COS     ENDLOOP
  2538.  
  2539.  
  2540.   Reserved identifiers may be written in either upper or lower case letters.
  2541.   This means that both print and  PRINT are the  name  of  the  output key-
  2542.   word, but Print is not.
  2543.  
  2544.  
  2545.   1.2 Simple data types.
  2546.  
  2547.   Comal has  a few important data types built into the language. These data
  2548.   types are numbers and strings. Other data types may be defined by the pro-
  2549.   grammer (see the sections 1.3.2 and 1.5).
  2550.  
  2551.   Numbers may  be either integers or floats (reals). But normally you don't
  2552.   need to distinguish between integers and floats.
  2553.  
  2554.  
  2555.  
  2556.                                          45
  2557.  
  2558.  
  2559.  
  2560.  
  2561.  
  2562.   1.2.1 Constants.
  2563.  
  2564.   Integers
  2565.  
  2566.     The following numbers are examples of integers:
  2567.  
  2568.       123456    -852       0
  2569.  
  2570.     The integer data type is divided into different subtypes differing by the
  2571.     range of integers that can be the value of the type. These types are:
  2572.  
  2573.       type      integer range
  2574.  
  2575.       ULONG     0 ... 4294967295
  2576.  
  2577.       LONG      -2147483648 ... 214783647
  2578.  
  2579.       USHORT    0 ... 65535
  2580.  
  2581.       SHORT     -32768 ... 32767
  2582.  
  2583.       UBYTE     0 ... 255
  2584.  
  2585.       BYTE      -128 ... 127
  2586.  
  2587.  
  2588.     Integer constants may be written in either decimal, hexadecimal or binary
  2589.     format. Hexadecimal constants are preceded by a dollar sign ($) and bina-
  2590.     ry constants by a percent sign (%):
  2591.  
  2592.       $1234FED    $ABCD   $FFFFFFFF
  2593.       %010011     %111    %1000111101111110001
  2594.  
  2595.  
  2596.   Floats
  2597.  
  2598.     The float  number type is used to represent fractional numbers and num-
  2599.     bers of very large or very small magnitude.
  2600.  
  2601.     The float numbers are represented internally as floating  point (64 bit
  2602.     IEEE). This means that they have aproximately 16 digits of precision and
  2603.     a tens exponent in the range -308 to 308.
  2604.  
  2605.     Float constants may be written as normal numbers with a  single decimal
  2606.     point or in exponential notation:
  2607.  
  2608.       3.14159     123456.0     -852.3     0.00001
  2609.       3.52E-27    4756328E112   0.000123E-27
  2610.  
  2611.  
  2612.  
  2613.                                          46
  2614.  
  2615.  
  2616.  
  2617.  
  2618.  
  2619.   Strings
  2620.  
  2621.     A string is a sequence af characters (printable as well as non printable).
  2622.  
  2623.     A string  constant is  typed as  a sequence of characters surrounded by
  2624.     quotes ("):
  2625.  
  2626.       "This is a string containing 51 printable characters"
  2627.       "Comal"
  2628.       "123"
  2629.  
  2630.     A quotation mark is written using a double quote:
  2631.  
  2632.       "A ""double quote"" example"
  2633.  
  2634.     Non printable characters are written by  using its  ASCII number within
  2635.     quotation marks:
  2636.  
  2637.       "A bad error "7""
  2638.  
  2639.  
  2640.   1.2.2 Expressions.
  2641.  
  2642.   An expression consists of constants, variables, functions, parenthesis and
  2643.   operators that yield a new value.
  2644.  
  2645.  
  2646.   Expressions involving numbers
  2647.  
  2648.     Operators used in expressions involving numbers are:
  2649.  
  2650.                                       examples of use
  2651.  
  2652.         -     unary minus             -7  -3.14157
  2653.  
  2654.         ^     exponentiation          2^3 (=8)
  2655.  
  2656.         *     multiplication          5.2*7.1 (=36.92)
  2657.  
  2658.         /     division                4.8/3 (=1.6)
  2659.  
  2660.        MOD    modulo (remainder)      27 MOD 4 (=3)
  2661.  
  2662.        DIV    integer division        27 DIV 4 (=6)
  2663.  
  2664.         +     addition                4.56+5.77 (=10.33)
  2665.  
  2666.         -     subtraction             4.56-5.77 (=-1.21)
  2667.  
  2668.       BITAND  binary AND              %1101 BITAND %0110 (=%0100)
  2669.  
  2670.                                          47
  2671.  
  2672.  
  2673.  
  2674.  
  2675.  
  2676.  
  2677.       BITOR   binary OR               %1101 BITOR %0110 (=%1111)
  2678.  
  2679.       BITXOR  binary XOR              %1101 BITXOR %0110 (=%1011)
  2680.  
  2681.         <     less than               25<37 (=TRUE = 1)
  2682.  
  2683.        <=     less or equal           27<=27  (=TRUE)
  2684.  
  2685.         =     equal                   5=8 (=FALSE = 0)
  2686.  
  2687.        >=     greater or equal        -56>=56 (=FALSE)
  2688.  
  2689.         >     greater than            -33>-57 (=TRUE)
  2690.  
  2691.        <>     not equal to            44<>0 (=TRUE)
  2692.  
  2693.        NOT    logical NOT             NOT 44<>0 (=FALSE)
  2694.  
  2695.        AND    logical AND             44<>0 AND 5=8 (=FALSE)
  2696.  
  2697.        OR     logical OR              44<>0 AND 5=8 (=TRUE)
  2698.  
  2699.  
  2700.     The operators are listed in the order of their precedence. This precedence
  2701.     may be changed by using parenthesis:
  2702.  
  2703.        2+3*4    = 14
  2704.       (2+3)*4   = 20
  2705.  
  2706.  
  2707.     Before the  evaluation of an expression all integer types except ULONGs
  2708.     are changed to LONG. The type of the  result depends  on the  types and
  2709.     the operators in the expression according to the following table
  2710.  
  2711.      +------------------+------------------+------------------+
  2712.      |                  |                  |                  |
  2713.      |   left operand   |  right operand   |    result        |
  2714.      |                  |                  |                  |
  2715.      +------------------+------------------+------------------+
  2716.      |                  |                  |                  |
  2717.      |      FLOAT       |    any number    |    FLOAT         |
  2718.      |                  |                  |                  |
  2719.      |   any number     |      FLOAT       |    FLOAT         |
  2720.      |                  |                  |                  |
  2721.      |      LONG        |  LONG or ULONG   |     LONG         |
  2722.      |                  |                  |                  |
  2723.      |     ULONG        |  LONG or ULONG   |    ULONG         |
  2724.      |                  |                  |                  |
  2725.      +------------------+------------------+------------------+
  2726.  
  2727.                                  48
  2728.  
  2729.  
  2730.  
  2731.  
  2732.  
  2733.  
  2734.  
  2735.     The result of an expression involving division (/) is FLOAT.
  2736.  
  2737.     Normally all  parts of  an expression is evaluated. This means that the
  2738.     right parenthesis in
  2739.  
  2740.       (6-2*3)*(5+7)
  2741.  
  2742.     is evaluated even though the value of the expression is determined by the
  2743.     first parenthesis (which is zero).
  2744.  
  2745.     An important exception from this rule is expressions containing the logi-
  2746.     cal operators AND and OR. If the left operand of  an AND  expression is
  2747.     evaluated to  FALSE the  right operand is not evaluated and if the left
  2748.     operand of an OR expression is evaluated to TRUE, the  right operand is
  2749.     not evaluated. As an example the expression
  2750.  
  2751.       (25>37) AND (2=1/0)
  2752.  
  2753.     is evaluated to FALSE and it will not result in a run time error since the
  2754.     right expression is not evaluated.
  2755.  
  2756.     This evaluation rule for AND and OR simplifies a lot  of programming as
  2757.     the following example shows.
  2758.  
  2759.     Example: This  piece of  code can be used to find a given number n in a
  2760.       table of numbers Table()
  2761.  
  2762.         index:=MAXINDEX(Table())
  2763.         WHILE Index>0 AND n<>Table(index) DO
  2764.           index:=index-1
  2765.         ENDWHILE
  2766.  
  2767.       If the number is not found the value of index is zero.
  2768.  
  2769.  
  2770.     Note that there are no boolean type in Comal. Boolean expressions evalu-
  2771.     ates to 1 if they are true and they evaluates to 0 if they are false.
  2772.  
  2773.     Any number expression used as a boolean expression is considered false if
  2774.     it is zero and true otherwise.
  2775.  
  2776.  
  2777.  
  2778.   Expressions involving strings
  2779.  
  2780.     Operators in expressions involving strings are:
  2781.  
  2782.  
  2783.  
  2784.                                          49
  2785.  
  2786.  
  2787.  
  2788.  
  2789.  
  2790.                                     examples of use
  2791.  
  2792.       (..)  string selection        "strings"(3..6)  (= "ring")
  2793.  
  2794.        *    string repetition       3*"Comal" (="ComalComalComal")
  2795.  
  2796.        +    string concatenation    "some"+"times" (="sometimes")
  2797.  
  2798.        <    less than               "alf"<"alfa" (=TRUE)
  2799.  
  2800.       <=    less or equal           "abc"<="ABC"  (=FALSE)
  2801.  
  2802.        =    equal                   "some"="any" (=FALSE)
  2803.  
  2804.       >=    greater or equal        "2">="!"  (=TRUE)
  2805.  
  2806.        >    greater than            "Comal">"BASIC" (=TRUE)
  2807.  
  2808.       <>    not equal to            ""<>" " (=TRUE)
  2809.  
  2810.       IN    contained in            "me" IN "sometimes" (=3)
  2811.  
  2812.  
  2813.     Note that only the first three has string values. The remaining operators
  2814.     are used between strings but the value of the expression is a number.
  2815.  
  2816.     The selection operator (..) selects part of a string. The first character of
  2817.     the selected substring is the character with the position specified by the
  2818.     first number in the parenthesis and the last character in the substring is
  2819.     the character with the position specified by the last number.
  2820.  
  2821.     Example: The function DATE$ returns  the  current  date  in  the format
  2822.       yyyy-mm-dd. This  piece of code prints the current data in the format
  2823.       mm.dd.yy:
  2824.  
  2825.         PRINT DATE$(6..7),".",DATE$(9..10),"."DATE$(3..4)
  2826.  
  2827.  
  2828.     It is possible to omit the first or the last character position. In this case
  2829.     it is considered as 1 and the length of the string respectively:
  2830.  
  2831.         "sometimes"(..4)    = "some"
  2832.         "sometimes"(5..)    = "times"
  2833.  
  2834.     During evaluation of expressions involving the comparison oprators <, <=,
  2835.     =, >=, > and <>, the characters in the strings are compared  one by one
  2836.     using the ASCII value of the characters (or the value set in the sorting
  2837.     table - see section 10.1.2).
  2838.  
  2839.  
  2840.  
  2841.                                          50
  2842.  
  2843.  
  2844.  
  2845.  
  2846.  
  2847.     An IN expression evaluates to the first position of the left string operand
  2848.     in the right string operand (if it is part of this) and it evaluates to zero
  2849.     if the left operand is not part of the right operand.
  2850.  
  2851.     Note that since a non zero value is considered true if it is used  as a
  2852.     boolean value, an IN expression can be used as a boolean expression.
  2853.  
  2854.  
  2855.     Example: This  piece of  code can be used to get a "Yes/No"-answer from
  2856.       the user:
  2857.  
  2858.         PRINT "Yes or No (Y/N)? :",
  2859.         REPEAT
  2860.           Answ$:=INKEY$
  2861.         UNTIL Answ$ IN "YyNn"
  2862.         PRINT Answer$
  2863.  
  2864.  
  2865.   1.2.3 Variables.
  2866.  
  2867.   A variable is a location in the main memory used to hold a value of a cer-
  2868.   tain type. Such locations may be identified by a name (an identifier). Very
  2869.   often this name is identified as the variable itself.
  2870.  
  2871.   Since the variable is used to hold values of a certain type the size of the
  2872.   memory location depends on the type in question.
  2873.  
  2874.   Number variables
  2875.  
  2876.     Number variables  are declared  (memory is  reserved) in DIM statements
  2877.     like
  2878.  
  2879.       DIM Number OF FLOAT       // A floating point variable
  2880.       DIM n OF LONG, m OF LONG  // Two long integer variables
  2881.       DIM c OF UBYTE            // A variable of type UBYTE
  2882.  
  2883.  
  2884.     The general format of a number declaration DIM statement is
  2885.  
  2886.       DIM variablename [OF NumberType]
  2887.  
  2888.     where NumberType is one of  the  types  FLOAT,  ULONG,  ...  BYTE  or a
  2889.     user defined type (see 1.5). The default type is FLOAT.
  2890.  
  2891.     After the execution of a DIM statements the values of the declared vari-
  2892.     ables are zero. This value may be replaced by another value in assignment
  2893.     statements like:
  2894.  
  2895.       Number:=2.718281828       n:=-38
  2896.       m:=45+n                   c:=10
  2897.  
  2898.                                          51
  2899.  
  2900.  
  2901.  
  2902.  
  2903.  
  2904.  
  2905.     The general format of an assignment statement is:
  2906.  
  2907.       identifier:=expression
  2908.  
  2909.  
  2910.     The different number types may be mixed in expressions. Comal makes the
  2911.     necessary convertions between the types. If an integer variable is assig-
  2912.     ned the value of an expression with a floating point value, that value is
  2913.     rounded to the nearest integer value. If a value exceeds the range of the
  2914.     type, an error is reported by the Comal system.
  2915.  
  2916.     Floating point  and long  integer variables need not be declared before
  2917.     they are used. If the variable Alfa is not declared before its use, it is
  2918.     automatically created as a floating point variable (unless you have turned
  2919.     off automatic variable creation - see section III.3.6). If the variable i# is
  2920.     not declared before its use, it is automatically created as a long integer
  2921.     variable (the number sign # tells the system that it is a  long integer
  2922.     variable).
  2923.  
  2924.     The  value  of  number  variables  may be decremented or incremented in
  2925.     special assignment statements like:
  2926.  
  2927.       n:-7
  2928.       x:+3.2
  2929.  
  2930.     The effect of these statements are the same as the effect af the state-
  2931.     ments
  2932.  
  2933.       n:=n-7
  2934.       x:=x+3.2
  2935.  
  2936.     but they are executed a little bit faster.
  2937.  
  2938.  
  2939.   String variables
  2940.  
  2941.     String variables are used to hold string values. The name of a string va-
  2942.     riable always ends with a dollar sign ($). String variables are declared in
  2943.     DIM statements like:
  2944.  
  2945.       DIM Name$ OF 25   // A variable holding up to 25 characters
  2946.       DIM Answ$er OF 1  // A variable holding only one character
  2947.  
  2948.  
  2949.     In the declaration af a string variable the maximum length of the string
  2950.     value is specified. This maximum string length may be up to 32767. After
  2951.     the declaration the value of the string variable is set to the empty string
  2952.     (""). This value may be replaced by another value in  assignment state-
  2953.     ments like:
  2954.  
  2955.                                          52
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.       Name$:="Borge"
  2963.       Answer$:="y"
  2964.  
  2965.  
  2966.     If a string variable is assigned a string which is longer than the maximum
  2967.     length specified in the declaration statement, the string is truncated. For
  2968.     example:
  2969.  
  2970.       Answer$:="No" // The string "No" is truncated to "N"
  2971.  
  2972.     A string variable need not be declared before its use. If a string variable
  2973.     is not declared before it is used, the system will automatically reserve
  2974.     space for 80 characters.
  2975.  
  2976.     The value  of string  variables may be "incremented" by using a special
  2977.     assignment statement like
  2978.  
  2979.       Name$:+" Christensen"
  2980.  
  2981.  
  2982.     Part of a string variable may be assigned a new value by using the selec-
  2983.     tion operator:
  2984.  
  2985.       s$:="Comal is a programming language"
  2986.       s$(5..9):=": the"
  2987.  
  2988.  
  2989.     If the value of the new substring is longer than the selected string, the
  2990.     value is truncated. If it is shorter, spaces are added.
  2991.  
  2992.  
  2993.  
  2994.   1.3 Structured data types.
  2995.  
  2996.   A structured type is a single type built out of simple types in certain ways
  2997.   and given a single name. This section discuss indexed variables (arrays) and
  2998.   records (strucs). In a later section the class type, which is an extension of
  2999.   the record type, will be discussed.
  3000.  
  3001.  
  3002.   1.3.1 Indexed variables.
  3003.  
  3004.   An indexed variable is a sort of table of values all of the same type. The
  3005.   table may have one ore more dimensions.
  3006.  
  3007.   Indexed variables are declared in DIM statements where the number  of in-
  3008.   dicies (dimensions), the number of index values of each dimension and the
  3009.   type of the elements are specified:
  3010.  
  3011.  
  3012.                                          53
  3013.  
  3014.  
  3015.  
  3016.  
  3017.  
  3018.     DIM a(4,5) OF FLOAT
  3019.     DIM b(100) OF BYTE
  3020.     DIM t$(20) OF 30
  3021.  
  3022.   The first table a has two indicies. The first index may have the values 1,
  3023.   2, 3  and 4 and the second index may have the values 1,2,3,4,5. The total
  3024.   number of elements, which are all of type FLOAT, is 20.
  3025.  
  3026.   The second table b has only one index taking on values from 1 to 100. The
  3027.   elements are of type BYTE. The third array t$ has one index that can take
  3028.   on values from 1 to 20. Each element is a string with  the maximum length
  3029.   30.
  3030.  
  3031.   The number of indicies and the range of each index is limited only by the
  3032.   available memory. The specified type may be any type (including user defi-
  3033.   ned types) except pointer type and array type.
  3034.  
  3035.   The indicies may take on the values from 1 (lower bound) up to the speci-
  3036.   fied upper bound. It is possible to specify other index ranges:
  3037.  
  3038.     DIM a(0..3,0..4) OF FLOAT
  3039.     DIM b(-50..49) OF BYTE
  3040.     DIM t$(10..29) OF 30
  3041.  
  3042.   Here is both the upper and lower bound of the indicies specified. The num-
  3043.   ber of index values are the same as in the previous example.
  3044.  
  3045.   The upper  and lower  bounds of the index values can be examined by using
  3046.   the functions MAXINDEX and MININDEX:
  3047.  
  3048.     MININDEX(a())     returns 0
  3049.     MININDEX(a(),1)   returns 0   (same as MININDEX(a())
  3050.     MAXINDEX(a(),2)   returns 4
  3051.     MAXINDEX(t$())    returns 29
  3052.  
  3053.  
  3054.   Note that the second argument is optional. If not present the bounds of the
  3055.   first dimensions is returned.
  3056.  
  3057.   The individual elements of the table is referenced by using the name of the
  3058.   table followed by the indicies of the element in parenthesis:
  3059.  
  3060.     a(2,3):=11.27
  3061.     INPUT "Enter a number: ":b(35)
  3062.     t$(15):="blue"
  3063.     PRINT a(1,1)
  3064.  
  3065.   Each of the elements referenced in this way is treated like a  simple va-
  3066.   riable of the elements type, and they may replace simple variables at any
  3067.   time.
  3068.  
  3069.                                          54
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.   The whole table can be set equal to the same value in one statement:
  3077.  
  3078.     a(,):=111.11
  3079.     b():=27
  3080.     t$():="yellow"
  3081.  
  3082.  
  3083.   1.3.2 Strucs (records).
  3084.  
  3085.   A struc is a user defined type whose value is a collection of values that
  3086.   are (possibly) of different types (in contradiction to indexed variables).
  3087.  
  3088.   The struc type is defined in a STRUC statement which has the form:
  3089.  
  3090.     STRUC identifier
  3091.         :
  3092.  
  3093.       DIM statements
  3094.  
  3095.         :
  3096.     ENDSTRUC identifier
  3097.  
  3098.  
  3099.  
  3100.   The DIM  statements in  the struc definition has the same format as other
  3101.   DIM statements except that all size specifications (like the size of a string
  3102.   and index bounds) must be constants.
  3103.  
  3104.   Later an extension of the struc concept (classes) will be discussed.
  3105.  
  3106.   Example:
  3107.  
  3108.     STRUC Person
  3109.       DIM FirstName$ OF 20, LastName$ OF 20
  3110.       DIM Address$ OF 30, City$ OF 20
  3111.       DIM Age of UBYTE
  3112.     ENDSTRUC Person
  3113.  
  3114.   Note that a STRUC statement defines a new type. No variables are defined.
  3115.   This is done in the normal way using DIM statements.
  3116.  
  3117.   Example:
  3118.  
  3119.     DIM Person OF Person
  3120.     DIM Member OF Person
  3121.     DIM Club(100) OF Person
  3122.  
  3123.     Note that it is possible to use the same name for the variable as is used
  3124.     for the type.
  3125.  
  3126.                                          55
  3127.  
  3128.  
  3129.  
  3130.  
  3131.  
  3132.  
  3133.   The elements of the struc are called fields and are accessed using the name
  3134.   of the struc variable, a dot and the name of the field (the dot notation).
  3135.  
  3136.   Example:
  3137.  
  3138.     Person.FirstName$:="Len"
  3139.     INPUT "Last name: ": Member.LastName$
  3140.     PRINT Club(35).Age
  3141.  
  3142.  
  3143.   A struc may be assigned the value of another struc in an assignment state-
  3144.   ment.
  3145.  
  3146.   Example:
  3147.     Member:=Club(35)
  3148.     Club():=Person
  3149.  
  3150.  
  3151.   1.4 Dynamic variables. Pointer variables.
  3152.  
  3153.   Any variable  that is  to be used in a program needs two things. It needs
  3154.   storage in the main memory to store the value of the variable and it needs
  3155.   some means of identification. A declaration like
  3156.  
  3157.     DIM Alfa OF UBYTE
  3158.  
  3159.   meets both this needs. It creates a variable (reserves storage in main me-
  3160.   mory) and it identifies this variable by the name Alfa.
  3161.  
  3162.   There is another more indirect way of creating and identifying a variable.
  3163.   In the declaration
  3164.  
  3165.     DIM p OF POINTER TO UBYTE
  3166.  
  3167.   a variable p is created. The value of this variable is not itself of type
  3168.   UBYTE. In stead the value is the identifier of a variable of type UBYTE.
  3169.  
  3170.   A variable is in fact a memory location in the main memory.  Such a loca-
  3171.   tion has an address. This address can be identified by a name (that's what
  3172.   we have used until now) or it can be identified by a number (in our daily
  3173.   life addresses  are mixtures  of names and numbers). In our newly created
  3174.   variable the address of the UBYTE variable is identified by  a number. If
  3175.   you execute the statement
  3176.  
  3177.     PRINT p
  3178.  
  3179.   you will get this number. It turns out to be zero which is synonymous for
  3180.   no address. There is no address since the UBYTE variable has not yet been
  3181.   created.
  3182.  
  3183.                                          56
  3184.  
  3185.  
  3186.  
  3187.  
  3188.  
  3189.  
  3190.   This can be done in a statement like
  3191.  
  3192.     ALLOCATE(p)
  3193.  
  3194.  
  3195.   Now the statement
  3196.  
  3197.     PRINT p
  3198.  
  3199.   will give a non zero address.
  3200.  
  3201.   The value of the UBYTE variable is accessed by using the indirection opra-
  3202.   tor @ as shown in the following statements
  3203.  
  3204.     p@:=5
  3205.     p@:+7
  3206.     PRINT p@+27
  3207.  
  3208.  
  3209.   As you see p@ is a normal variable (of type UBYTE).
  3210.  
  3211.   In the statement
  3212.  
  3213.     ALLOCATE(p)
  3214.  
  3215.   the procedure ALLOCATE reserves space for the variable  p@ among  all the
  3216.   other variables  used in  the program. The ALLOCATE procedure may also be
  3217.   called with two parameters:
  3218.  
  3219.     ALLOCATE(p,MemType)
  3220.  
  3221.  
  3222.   If this form is used the memory is allocated in the storage administrated by
  3223.   the Amiga operating system. The value of MemType can be:
  3224.  
  3225.       MEMF_PUBLIC (=1)
  3226.       MEMF_CHIP   (=2)
  3227.       MEMF_FAST   (=4)
  3228.  
  3229.  
  3230.   Normally  you  will  use  MEMF_PUBLIC.  This  name  as  well as the names
  3231.   MEMF_CHIP and MEMF_FAST are defined in the System module.
  3232.  
  3233.   The memory allocated by the  procedure  ALLOCATE  can  be  deallocated by
  3234.   the statement
  3235.  
  3236.     DEALLOCATE(p)
  3237.  
  3238.  
  3239.  
  3240.                                          57
  3241.  
  3242.  
  3243.  
  3244.  
  3245.  
  3246.   After the execution of this statement the value of p is again zero (which
  3247.   means no address).
  3248.  
  3249.   A variable created by the procedure  ALLOCATE is  created during  the ex-
  3250.   ecution of the program and is therefore called a dynamic variable. The va-
  3251.   riable p itself is called a pointer variable since the value of p points to a
  3252.   variable.
  3253.  
  3254.   The general format of the declaration af a pointer variable is
  3255.  
  3256.     DIM varname OF POINTER TO typename
  3257.     DIM varname@ OF typename            // Short form
  3258.  
  3259.   where typename can be any type except a pointer type (see next section).
  3260.  
  3261.   Normally the  type pointed  at (typename above) has to be known, i.e. the
  3262.   type must be defined somewhere else in the program or it must be imported
  3263.   from a module. Exception from that rule are pointers that are fields in a
  3264.   structure. In this case the type pointed at is set to unknown pointer if it
  3265.   is not defined.
  3266.  
  3267.   If a  structure with  unknown pointer types is imported from a module the
  3268.   system looks for the  type in  the program  environment that  imports the
  3269.   structure and changes the unknown pointer type to the correct type if it is
  3270.   found. Otherwise the type will contiue to be unknown pointer.
  3271.  
  3272.   It is not possible to use the indirection operator on a pointer with unknown
  3273.   pointer type.
  3274.  
  3275.  
  3276.   Example: To write a text directly into an intuition window a structure of
  3277.     the following is used
  3278.  
  3279.       STRUC IntuiText
  3280.         DIM FrontPen OF UBYTE
  3281.         DIM BackPen OF UBYTE
  3282.         DIM DrawMode OF UBYTE
  3283.         DIM LeftEdge OF SHORT
  3284.         DIM TopEdge OF SHORT
  3285.         DIM ITextFont OF POINTER TO TextAttr
  3286.         DIM IText OF POINTER TO UBYTE
  3287.         DIM NextText OF POINTER TO IntuiText
  3288.       ENDSTRUC IntuiText
  3289.  
  3290.  
  3291.     If the type TextAttr is not defined elsewhere the pointer type is set to
  3292.     unknown pointer.
  3293.  
  3294.  
  3295.  
  3296.  
  3297.                                          58
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.   Example: In the module System the ComalStruc structure is defined (se sec-
  3304.     tion 10.1.2). One of the fields of this structure is:
  3305.  
  3306.       DIM CommPort OF POINTER TO MsgPort
  3307.  
  3308.     The type MsgPort is not known in the  module and  the type  of CommPort
  3309.     is unknown pointer.
  3310.  
  3311.     If you want to use this field you have to import the module PortObjects
  3312.     along with the module System:
  3313.  
  3314.       USE PortObjects
  3315.       USE System
  3316.  
  3317.  
  3318.   A pointer variable acts in many cases like a variable of type ULONG. It has
  3319.   a value (an address) of type ULONG, that may be used in any expression. It
  3320.   is also possible to assign a value to a pointer variable using an assignment
  3321.   statement:
  3322.  
  3323.     p:=$0004
  3324.  
  3325.  
  3326.   Such an  assignment can be dangerous since you are now able to change any
  3327.   portion of the memory in your Amiga. To avoid mistakes  you can  only as-
  3328.   sign an  expression of type ULONG to a pointer. In this way most mistakes
  3329.   will be caught by the system because ULONG  values are  difficult to make
  3330.   (see description of expressions).
  3331.  
  3332.   Example:  The  function  in  this  example  implements  the PEEK function
  3333.     known from many BASIC dialects
  3334.  
  3335.  
  3336.         FUNC peek(MemPtr OF UbytePtr) OF UBYTE
  3337.           RETURN MemPtr@
  3338.         ENDFUNC peek
  3339.  
  3340.         TYPE UbytePtr=POINTER TO UBYTE
  3341.  
  3342.  
  3343.   Example: The following program fraction shows the use of pointers  in the
  3344.     creation of a linked list:
  3345.  
  3346.  
  3347.           :
  3348.           :
  3349.  
  3350.         STRUC Person
  3351.           DIM Next OF POINTER TO Person
  3352.           DIM Name$ OF 30
  3353.  
  3354.                                          59
  3355.  
  3356.  
  3357.  
  3358.  
  3359.  
  3360.           DIM Address$ OF 30
  3361.           DIM City$ OF 20
  3362.           DIM Age of UBYTE
  3363.         ENDSTRUC Person
  3364.  
  3365.         DIM Start OF POINTER TO Person
  3366.         DIM Node OF POINTER TO Person
  3367.  
  3368.           :
  3369.           :
  3370.  
  3371.         // Insert the variable Person@ in the list
  3372.  
  3373.         IF Start=0 THEN
  3374.           Start:=Person
  3375.         ELSE
  3376.           Node:=Start
  3377.           IF Start@.Name$<Person@.Name$ THEN
  3378.             WHILE Node@.Next AND Node@.Next@.Name$<Person@.Name$
  3379.               Node:=Node@.Next
  3380.             ENDWHILE
  3381.           ENDIF
  3382.           Person@.Next:=Node@.Next
  3383.           Node@.Next:=Person
  3384.         ENDIF
  3385.  
  3386.           :
  3387.           :
  3388.  
  3389.  
  3390.   A pointer  variable can  be used as a one dimensional indexed variable by
  3391.   placing an index value after the  variable name.  The range  of the index
  3392.   values is all non negative integers.
  3393.  
  3394.  
  3395.   Example: An  array of  100 elements  of type Person can be made by execu-
  3396.     ting the statements
  3397.  
  3398.       DIM Pers OF POINTER TO Person
  3399.  
  3400.       Pers:=malloc(100*SIZE(Person),MEMF_PUBLIC)
  3401.  
  3402.     and you can get one of the elements in this way:
  3403.  
  3404.       Pers(23).Name$="Donald E. Knut"
  3405.  
  3406.  
  3407.   This way of indexing into a dynamic variable can be very useful in connec-
  3408.   tion with some of the system routines.
  3409.  
  3410.  
  3411.                                          60
  3412.  
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  
  3418.   1.5 Type definition.
  3419.  
  3420.   New types  are defined  in a  STRUC statement.  But new types may also be
  3421.   defined in a TYPE  statement. The  TYPE statement  can take  on different
  3422.   forms.
  3423.  
  3424.  
  3425.   TYPE NewType=OldType
  3426.  
  3427.     By using  this form  of the TYPE statement no new type is created. It's
  3428.     only new names for existing types.
  3429.  
  3430.     Examples:
  3431.  
  3432.       TYPE UWORD=USHORT
  3433.       TYPE WORD=SHORT
  3434.       TYPE BOOL=BYTE
  3435.  
  3436.  
  3437.   TYPE PtrType=POINTER TO Type
  3438.  
  3439.     This form of the TYPE statement is used to create a pointer type.
  3440.  
  3441.     Examples:
  3442.       TYPE UbytePtr=POINTER TO UBYTE
  3443.       TYPE WordPtr=POINTER TO WORD
  3444.       TYPE PersonPtr=POINTER TO Person
  3445.       TYPE WdPtr=POINTER TO Window
  3446.  
  3447.   TYPE AryType=ARRAY(dimension list) OF Type
  3448.  
  3449.     This form of the TYPE statement is used  to create  an array  type. The
  3450.     dimension list has the same form as discussed in the description of the
  3451.     DIM statement in section 1.3.1 (Indexed variables) except that only con-
  3452.     stant may be used.
  3453.  
  3454.     Examples:
  3455.       TYPE IntArray=ARRAY(0..5,-2..10) OF LONG
  3456.       TYPE Data=ARRAY(0..150000) OF UBYTE
  3457.       TYPE String10=ARRAY(0..10) OF UBYTE
  3458.  
  3459.  
  3460.     Having made these type definitions a pointer to (for example) a variable
  3461.     of type Data can be declared and a large array of bytes can be created:
  3462.  
  3463.       DIM DataPtr OF POINTER TO Data
  3464.       ALLOCATE(DataPtr,MEMF_PUBLIC)
  3465.  
  3466.  
  3467.  
  3468.                                          61
  3469.  
  3470.  
  3471.  
  3472.  
  3473.  
  3474.   TYPE FncType=FUNC[(parameter type list)] [OF NumberType]
  3475.   TYPE PrcType=PROC[(parameter type list)]
  3476.  
  3477.     These forms of the TYPE statement is used to create function and proce-
  3478.     dure types. This is necessary if you want to make functions or procedures
  3479.     with such parameter types. The terms inside the square brackets are op-
  3480.     tional.
  3481.  
  3482.     Examples:
  3483.       TYPE FltFunc=FUNC(FLOAT) OF FLOAT
  3484.       TYPE ByteFnc=FUNC OF BYTE
  3485.       TYPE ExceptProc=PROC(ULONG)
  3486.  
  3487.  
  3488.     Example: In  this program an integral function is made and the integral
  3489.       of the function sin from 0 to pi is printed out:
  3490.  
  3491.         PRINT integral(SIN(),0,PI)
  3492.  
  3493.         FUNC integral(f OF FltFunc,a,b)
  3494.           LOCAL n, dx, xi, s
  3495.           n:=16; dx:=(b-a)/n;
  3496.           xi:=a; s:=(f(a)-f(b))*dx/6
  3497.           LOOP n TIMES xi:=xi+dx; s:=s+(f(xi)+2*f(xi-dx/2))*dx/3
  3498.           RETURN s
  3499.         ENDFUNC integral
  3500.  
  3501.         TYPE FltFunc=FUNC(FLOAT) OF FLOAT
  3502.  
  3503.  
  3504.   TYPE statements may be  placed in  the main  program, in  closed procedu-
  3505.   res/functions or in modules. The program execution speed is not affected by
  3506.   the use of new type names. All type references are resolved at  the scan-
  3507.   ning time.
  3508.  
  3509.   The search for a matching type is done in this way:
  3510.  
  3511.     1.  The scanner  searches for  the name  in the same program level (the
  3512.         same procedure/function, module or the main program).
  3513.  
  3514.     2.  Then the name is searched for in the  modules used  in this program
  3515.         level.
  3516.  
  3517.     3.  Then the  name is  searched for  in lower  program levels (the main
  3518.         program or a procedure if the current procedure is local) or in modu-
  3519.         les used in these lower levels.
  3520.  
  3521.   If the  name cannot  be found the scanner will stop with an error message
  3522.   and the cursor will be placed on the unknown type name.
  3523.  
  3524.  
  3525.                                          62
  3526.  
  3527.  
  3528.  
  3529.  
  3530.  
  3531.  
  3532.   2 Program flow control statements.
  3533.  
  3534.   This section discuss the program statements that can be used to direct the
  3535.   program's sequence of execution ("flow control statements").
  3536.  
  3537.  
  3538.   2.1 Selection.
  3539.  
  3540.   Comal provides several forms of decision-making statements: the IF state-
  3541.   ments and the CASE statement.
  3542.  
  3543.  
  3544.   2.1.1 The IF statements.
  3545.  
  3546.   More than five variants of the IF statement are available, depending upon
  3547.   the use of ELSE and ELIF.
  3548.  
  3549.  
  3550.   Single line IF - THEN
  3551.  
  3552.     The single line IF statement has the form:
  3553.  
  3554.       IF condition THEN simple_statement
  3555.  
  3556.     where condition  is a number expression whose value is interpreted as a
  3557.     boolean value and simple_statement is any  non declaration  single line
  3558.     statement (except single line IF). If the condition is fulfilled the state-
  3559.     ment after THEN is executed.
  3560.  
  3561.     Examples:
  3562.  
  3563.       IF Printer$="Y" THEN SELECT OUTPUT "lp:"
  3564.  
  3565.       IF x>Max THEN Max:=x
  3566.  
  3567.  
  3568.   IF - THEN - ENDIF
  3569.  
  3570.     This is the simplest form of the multy  line IF  statement. The general
  3571.     format is:
  3572.  
  3573.       IF condition THEN
  3574.         statements
  3575.       ENDIF
  3576.  
  3577.     If the condition is fulfilled the statement(s) between the IF-THEN line
  3578.     and the ENDIF line is executed. If the condition is not fulfilled, then
  3579.     these lines  are skipped, and the program execution continues after the
  3580.     ENDIF line.
  3581.  
  3582.                                          63
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.     Example: In the following example an Intuition window is opened. If the
  3590.       operation fails (Window pointer is zero) an error message is printed and
  3591.       the program stops:
  3592.  
  3593.         Window=OpenWindow(ADR(NewWindow))
  3594.         IF Window=0 THEN
  3595.           PRINT "Window could not be opened"
  3596.           STOP
  3597.         ENDIF
  3598.  
  3599.  
  3600.  
  3601.   IF - THEN - ELSE - ENDIF
  3602.  
  3603.     The general format of this variation of the IF statement is:
  3604.  
  3605.       IF condition THEN
  3606.         statements
  3607.       ELSE
  3608.         statements
  3609.       ENDIF
  3610.  
  3611.     The statement(s) between the IF-THEN line and the ELSE line is executed
  3612.     if the condition is fulfilled, while the statement(s) between the ELSE line
  3613.     and the ENDIF line is executed if the condition is not satisfied. continues
  3614.     after the  ENDIF line. One of the statement segments will always be ex-
  3615.     ecuted, but never both. When the selected segment has been executed the
  3616.     program execution continues after the ENDIF line.
  3617.  
  3618.  
  3619.     Example:
  3620.  
  3621.       IF Printer$="Y" THEN
  3622.         SELECT OUTPUT "lp:"
  3623.       ELSE
  3624.         PAGE  // Clear screen
  3625.       ENDIF
  3626.  
  3627.  
  3628.   IF - THEN - ELIF - ENDIF
  3629.  
  3630.     The simplest form of this variation of the IF statement is:
  3631.  
  3632.       IF condition THEN
  3633.         statements
  3634.       ELIF condition THEN
  3635.         statements
  3636.       ENDIF
  3637.  
  3638.  
  3639.                                          64
  3640.  
  3641.  
  3642.  
  3643.  
  3644.  
  3645.  
  3646.     The ELIF (else if) condition is examined if and only if the IF condition is
  3647.     not satisfied. An arbitrary number of ELIF statements may be  placed in
  3648.     the IF-statement, for instance:
  3649.  
  3650.       IF condition THEN
  3651.         statements
  3652.       ELIF condition THEN
  3653.         statements
  3654.       ELIF condition THEN
  3655.         statements
  3656.       ELIF condition THEN
  3657.         statements
  3658.       ENDIF
  3659.  
  3660.  
  3661.     The conditions are examined one by one until one is fulfilled or there is
  3662.     no more ELIF lines. If a condition is fulfilled the statement(s) between
  3663.     the corresponding  IF/ELIF and  the next  ELIF/ENDIF is executed. After
  3664.     that the remainig conditions and statements are skipped, and the program
  3665.     execution continues after the ENDIF line. If none of conditions are ful-
  3666.     filed, then no statements are executed, and the  program execution con-
  3667.     tinues after the ENDIF line.
  3668.  
  3669.  
  3670.     Example:
  3671.  
  3672.       IF x>Max THEN
  3673.         Max:=x
  3674.       ELIF x<Min THEN
  3675.         Min:=x
  3676.       ENDIF
  3677.  
  3678.  
  3679.  
  3680.   IF - THEN - ELIF - ELSE - ENDIF
  3681.  
  3682.     The simplest form of this variation of the IF statement is:
  3683.  
  3684.       IF condition THEN
  3685.         statements
  3686.       ELIF condition THEN
  3687.         statements
  3688.       ELSE
  3689.         statements
  3690.       ENDIF
  3691.  
  3692.  
  3693.     An arbitrary  number of  ELIF statements may be placed in the IF-state-
  3694.     ment, for instance:
  3695.  
  3696.                                          65
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.       IF condition THEN
  3704.         statements
  3705.       ELIF condition THEN
  3706.         statements
  3707.       ELIF condition THEN
  3708.         statements
  3709.       ELIF condition THEN
  3710.         statements
  3711.       ELSE
  3712.         statements
  3713.       ENDIF
  3714.  
  3715.     The conditions are examined one by one until one is fulfilled or there is
  3716.     no more ELIF lines. If a condition is fulfilled the statement(s) between
  3717.     the corresponding IF/ELIF and the  next  ELIF/ELSE  is  executed. After
  3718.     that the  remainig part of the IF statement is skipped, and the program
  3719.     execution continues after the ENDIF line. If none of conditions are ful-
  3720.     filed, then the statements between ELSE and ENDIF will be executed.
  3721.  
  3722.     Example: This  program section  prints the  solution of a second degree
  3723.       equation (with coefficients A, B and C)
  3724.  
  3725.         D:=B^2-4*A*C    // The discriminant is calculated
  3726.         IF D<0 THEN
  3727.           PRINT "No solution"
  3728.         ELIF D=0 THEN
  3729.           PRINT "There is one solution:";-B/(2*A)
  3730.         ELSE
  3731.           x1:=(-B-SQR(D))/(2*A)
  3732.           x2:=(-B+SQR(D))/(2*A)
  3733.           PRINT "There are two solutions:";x1;"and";x2
  3734.         ENDIF
  3735.  
  3736.  
  3737.  
  3738.   2.1.2 The CASE statement.
  3739.  
  3740.     With a CASE statement it is possible to provide multiple branching. The
  3741.     general form of the statement is:
  3742.  
  3743.       CASE expression OF
  3744.       WHEN expression_list
  3745.         statements
  3746.       WHEN expression_list
  3747.         statements
  3748.       WHEN expression_list
  3749.         statements
  3750.       WHEN expression_list
  3751.         statements
  3752.  
  3753.                                          66
  3754.  
  3755.  
  3756.  
  3757.  
  3758.  
  3759.  
  3760.         :
  3761.  
  3762.       OTHERWISE
  3763.         statements
  3764.       ENDCASE
  3765.  
  3766.  
  3767.     An arbitrary  number of  WHEN options  can be  used. The OTHERWISE part
  3768.     is optional.
  3769.  
  3770.     When the CASE expression has been evaluated, it  will be  compared with
  3771.     each of the values specified in the first WHEN branch. If one of the val-
  3772.     ues agrees with the CASE expression, then the following statement (until
  3773.     next  WHEN/OTHERWISE/ENDCASE)   will  be   executed,  and  the  program
  3774.     execution will continue after ENDCASE.
  3775.  
  3776.     Each WHEN branch expression in the CASE statement  will be  examined in
  3777.     the order  in which  they occur.  The first  WHEN segment  for which an
  3778.     agreement is found will  be executed.  The remaining  part of  the CASE
  3779.     statement will be skipped, and the program execution will continue after
  3780.     ENDCASE.
  3781.  
  3782.     If none of the WHEN branch values agree  with the  CASE expression, the
  3783.     statement(s)  after  OTHERWISE  (if  present)  will  be executed. If no
  3784.     OTHERWISE part is present and none  of  the  WHEN  branch  values agree
  3785.     with the CASE expression, and error message will be generated.
  3786.  
  3787.  
  3788.     Example:
  3789.  
  3790.       CASE month$ OF
  3791.       WHEN "jan","mar","may","jul","aug","oct","dec"
  3792.         days:=31
  3793.       WHEN "apr","jun","sep","nov"
  3794.         days:=30
  3795.       WHEN "feb"
  3796.         days:=28    // No leap year support
  3797.       ENDCASE
  3798.  
  3799.  
  3800.     The type  of the  WHEN branch  values must  be the  same as the type of
  3801.     the CASE expression (string or number).
  3802.  
  3803.  
  3804.  
  3805.   2.2 Repetition.
  3806.  
  3807.   In Comal there are several forms  of repetive  statements: REPEAT, WHILE,
  3808.   FOR and LOOP.
  3809.  
  3810.                                          67
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.   REPEAT - UNTIL
  3819.  
  3820.     This repetive statement allows groups of statements to be executed again
  3821.     and again, until some terminating UNTIL condition is fulfilled.
  3822.  
  3823.     The general format of the statement is
  3824.  
  3825.       REPEAT
  3826.         statements
  3827.       UNTIL condition
  3828.  
  3829.     Since the the statements are executed before the condition is evaluated,
  3830.     the statements will always be executed at least once.
  3831.  
  3832.     Example:
  3833.  
  3834.       REPEAT
  3835.         CURSOR 5,10
  3836.         PRINT ""155"K",   // Erase to end of line
  3837.         INPUT "Enter number of disks (between 1 and 10): ": Num
  3838.       UNTIL Num>=1 AND Num<=10
  3839.  
  3840.  
  3841.  
  3842.   WHILE - ENDWHILE
  3843.  
  3844.     The  WHILE  statement  is  similar  to the REPEAT statement. It is used
  3845.     when a block of statements is to be  executed repeatedly  as long  as a
  3846.     particular condition is fulfilled. The major difference is that the condition
  3847.     is evaluated and tested before any statements inside the WHILE-block is
  3848.     executed.
  3849.  
  3850.     The general format of the WHILE statement is:
  3851.  
  3852.       WHILE condition DO
  3853.         statements
  3854.       ENDWHILE
  3855.  
  3856.     If the  condition is fulfilled, then the statement(s) between the WHILE
  3857.     line and ENDWHILE line is executed, and the condition will then be eval-
  3858.     uated again.
  3859.  
  3860.     If the condition is not satisfied, then the statement block is skipped and
  3861.     the program execution will continue after the ENDWHILE line.
  3862.  
  3863.  
  3864.     Example: This little program will print the content of a text file on the
  3865.       screen
  3866.  
  3867.                                          68
  3868.  
  3869.  
  3870.  
  3871.  
  3872.  
  3873.  
  3874.  
  3875.         OPEN FILE 1,"TextFile",READ
  3876.         WHILE NOT EOF(1) DO
  3877.           INPUT FILE 1: Line$
  3878.           PRINT Line$
  3879.         ENDWHILE
  3880.         CLOSE FILE 1
  3881.  
  3882.  
  3883.   Single line WHILE
  3884.  
  3885.     If only a single statement follows the WHILE line, then the statement can
  3886.     be placed in a single line WHILE.
  3887.  
  3888.     The format of a single line WHILE is:
  3889.  
  3890.       WHILE condition DO statement
  3891.  
  3892.     where simple_statement is any non declaration single line statement.
  3893.  
  3894.     Example: This line waits for a key to be pressed without using CPU time:
  3895.  
  3896.         WHILE KEY$<>"" DO WAIT
  3897.  
  3898.  
  3899.  
  3900.   FOR - ENDFOR
  3901.  
  3902.     The FOR statement is used if a group of statements are to be executed a
  3903.     certain number  of times with given counter values. The number of times
  3904.     the statement block is to be executed, is determined by means of a con-
  3905.     trol variable (the counter).
  3906.  
  3907.     The general format is
  3908.  
  3909.       FOR counter:=start TO end [STEP interval] DO
  3910.         statements
  3911.       ENDFOR counter
  3912.  
  3913.     The FOR statement contains an indication of the start and end values of
  3914.     the control variable. The statement block is executed until the control
  3915.     variable exceeds the the end value.
  3916.  
  3917.     When the group of statements has been executed, the control variable is
  3918.     changed. How much it is changed can be specified by  means of  the STEP
  3919.     option. If this option is omitted, then the control variable will be incre-
  3920.     mented by 1. After the change of the control variable the value is com-
  3921.     pared with the end value.
  3922.  
  3923.  
  3924.                                          69
  3925.  
  3926.  
  3927.  
  3928.  
  3929.  
  3930.     The first  time the value is surpassed, the FOR loop is completed , and
  3931.     the program execution continues after the ENDFOR line.
  3932.  
  3933.  
  3934.     Example:
  3935.  
  3936.       FOR i:=1 TO MaxMember DO
  3937.         PRINT Club(i).LastName$,", ",Club(i).FirstName$
  3938.         PRINT Club(i).Address$
  3939.         PRINT Club(i).City$
  3940.         PRINT
  3941.       ENDFOR i
  3942.  
  3943.  
  3944.   Single line FOR
  3945.  
  3946.     If only a single statement follows the FOR line, then the statement can
  3947.     be placed in a single line FOR.
  3948.  
  3949.     The format of a single line FOR is:
  3950.  
  3951.       FOR counter:=start TO end [STEP interval] DO statement
  3952.  
  3953.     where statement is any non declaration single line statement.
  3954.  
  3955.     Example:
  3956.  
  3957.       FOR x:=0 TO 6.3 STEP 0.1 DO PRINT x;COS(x);SIN(x)
  3958.  
  3959.  
  3960.  
  3961.   LOOP - TIMES - ENDLOOP
  3962.  
  3963.     The LOOP  statement is used if a group of statements are to be executed
  3964.     a certain number of times and you do not need a counter variable.
  3965.  
  3966.     The general format is:
  3967.  
  3968.       LOOP number TIMES
  3969.         statements
  3970.       ENDLOOP
  3971.  
  3972.  
  3973.     The statements are executed number times  before the  program execution
  3974.     continues after the ENDLOOP line.
  3975.  
  3976.     This loop  statement is  executed considerably faster than the FOR loop
  3977.     because of the lack of the counter variable.
  3978.  
  3979.  
  3980.  
  3981.                                          70
  3982.  
  3983.  
  3984.  
  3985.  
  3986.  
  3987.     Example:
  3988.  
  3989.       LOOP 4 TIMES
  3990.         forward(80)
  3991.         right(90)
  3992.       ENDLOOP
  3993.  
  3994.  
  3995.   Single line LOOP
  3996.  
  3997.     If only a single statement follows the LOOP-TIMES line, then the state-
  3998.     ment can be placed in a single line LOOP.
  3999.  
  4000.     The format of a single line LOOP is:
  4001.  
  4002.       LOOP number TIMES simple_statement
  4003.  
  4004.     where simple_statement is any non declaration single line statement.
  4005.  
  4006.     Example:
  4007.  
  4008.       t$:=""
  4009.       LOOP 30 TIMES t$:+"*"
  4010.  
  4011.  
  4012.   Endless LOOP
  4013.  
  4014.     This is  the simplest of all the repetive statements. It is used when a
  4015.     block of statements is to be executed an infinite number of times.
  4016.  
  4017.     The format of the statemet is
  4018.  
  4019.       LOOP
  4020.         statements
  4021.       ENDLOOP
  4022.  
  4023.     Example: The following piece of code is a typical main  part of  a menu
  4024.       driven program
  4025.  
  4026.         LOOP
  4027.           PAGE
  4028.           PRINT AT 7,10: "Create"
  4029.           PRINT AT 9,10: "Delete"
  4030.           PRINT AT 11,10: "Write"
  4031.           PRINT AT 15,10: "Select job: ",
  4032.           job$:=PressKey$("CcDdWw")
  4033.           CASE job$ OF
  4034.           WHEN "C","c"
  4035.             Create
  4036.           WHEN "D","d"
  4037.  
  4038.                                          71
  4039.  
  4040.  
  4041.  
  4042.  
  4043.  
  4044.             Delete
  4045.           WHEN "W","p"
  4046.             Write
  4047.           ENDCASE
  4048.         ENDLOOP
  4049.  
  4050.  
  4051.     The loop can be terminated by executing one of the branching statements
  4052.     (GOTO, IF .. GOTO, EXIT, EXIT WHEN ..).
  4053.  
  4054.  
  4055.  
  4056.   2.3 Branching.
  4057.  
  4058.   Branching means changing a program's flow of control by some  means other
  4059.   than the  statements described in the sections 2.1 and 2.2. There are two
  4060.   such branching statements: the GOTO statement and the EXIT statement.
  4061.  
  4062.  
  4063.   2.3.1 The GOTO statement.
  4064.  
  4065.   The GOTO statement is used to redirect execution  to another  part of the
  4066.   program. The new location is specified by a label.
  4067.  
  4068.   The general format of a GOTO statement is:
  4069.  
  4070.     GOTO label
  4071.  
  4072.  
  4073.   The format of a label line is:
  4074.  
  4075.     label:
  4076.  
  4077.   where label is an identifier. Note the colon (:) after the label name.
  4078.  
  4079.   The GOTO  statement is  not often  used, because of the presence of other
  4080.   flexible structures like the other program flow statements discussed in sec-
  4081.   tion 2.1 and 2.2. But there are times (usually error conditions) when it is
  4082.   the least painful way to break out of a number  of nested  program struc-
  4083.   tures.
  4084.  
  4085.  
  4086.     Example:
  4087.  
  4088.       Window=OpenWindow(ADR(NewWindow))
  4089.       IF Window=0 THEN
  4090.         PRINT "Window could not be opened"
  4091.         GOTO CleanUp
  4092.       ENDIF
  4093.  
  4094.  
  4095.                                          72
  4096.  
  4097.  
  4098.  
  4099.  
  4100.  
  4101.  
  4102.  
  4103.   2.3.1 The EXIT statement.
  4104.  
  4105.   The EXIT statement is used in any of the repetive statements to cause con-
  4106.   ditional or unconditional interrupt of the loop. When EXIT has been execu-
  4107.   ted, the program execution continues after the end of the loop.
  4108.  
  4109.   The format of an EXIT statement is:
  4110.  
  4111.     EXIT [WHEN condition]
  4112.  
  4113.   If the  optional WHEN part is present the exit of the loop will only take
  4114.   place if the condition is fulfilled. Otherwise the exit will take place uncon-
  4115.   ditionally.
  4116.  
  4117.     Example:
  4118.  
  4119.       OPEN 1,"SER:",READ        // Open serial port
  4120.       LOOP
  4121.         ch$=GET$(1,1)
  4122.         EXIT WHEN ch$=""26""    // ^Z (ASCII 26) is end of file
  4123.         PRINT ch$
  4124.       ENDLOOP
  4125.       CLOSE FILE 1
  4126.  
  4127.  
  4128.   3 Procedures and functions.
  4129.  
  4130.   One way  of designing  modular programs  in Comal  is by using procedures
  4131.   and functions.
  4132.  
  4133.   Procedures and functions are some sort of named  subprograms that  can be
  4134.   activated in any part of the program.
  4135.  
  4136.  
  4137.   3.1 Procedures.
  4138.  
  4139.   The general format of a procedure is
  4140.  
  4141.     PROC procedure_name[(formal_parameter_list)] [CLOSED]
  4142.       program_statements
  4143.     ENDPROC procedure_name
  4144.  
  4145.  
  4146.   The program_statements  inside the  procedure are activated by an execute
  4147.   statement. The format of this statement is
  4148.  
  4149.     procedure_name[(actual_parameter_list)]
  4150.  
  4151.  
  4152.                                          73
  4153.  
  4154.  
  4155.  
  4156.  
  4157.  
  4158.  
  4159.   The statements inside the procedure are executed as normal program state-
  4160.   ments. The  execution of  these statements  stops when the ENDPROC state-
  4161.   ment is reached or when a RETURN statement is executed.
  4162.  
  4163.   The format of a procedure RETURN statement is
  4164.  
  4165.     RETURN
  4166.  
  4167.  
  4168.   When the execution of the procedure statements stops,  the program execu-
  4169.   tion continues after the execute statement that activated the procedure.
  4170.  
  4171.   The name of a procedure is an identifier. Normally one chooses a name that
  4172.   reflects the action of the procedure. Procedures can be placed averywhere
  4173.   in the  program except  that it  may not  appear within IF, CASE, REPEAT,
  4174.   WHILE, FOR, LOOP and TRAP statements.
  4175.  
  4176.   It's a good idea to place procedures at the end of the program. In this way
  4177.   it reflects the top-down programming strategi.
  4178.  
  4179.  
  4180.   3.1.1 Procedures without parameters.
  4181.  
  4182.   The simplest form of procedures are the procedures without parameters. The
  4183.   general format of such procedures is
  4184.  
  4185.     PROC procedure_name
  4186.       program_statements
  4187.     ENDPROC procedure_name
  4188.  
  4189.   and they are activated by an execute statement of the form
  4190.  
  4191.     procedure_name
  4192.  
  4193.   Example: The procedure EraseToEndOfLine in this example will erase to the
  4194.     end of the line
  4195.  
  4196.         :
  4197.       REPEAT
  4198.         CURSOR 5,10
  4199.         EraseToEndOfLine
  4200.         INPUT "Enter number of disks (between 1 and 10): ": Num
  4201.       UNTIL Num>=1 AND Num<=10
  4202.         :
  4203.  
  4204.       PROC EraseToEndOfLine
  4205.         PRINT ""155"K",
  4206.       ENDPROC EraseToEndOfLine
  4207.  
  4208.  
  4209.                                          74
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.   3.1.2 Value parameters.
  4218.  
  4219.   Data can  be transferred  to procedures through parameters. There are two
  4220.   kinds of parameters: Value parameters and reference parameters. Value pa-
  4221.   rameters are exclusively used to transfer data into the procedure. Reference
  4222.   parameters are used both to transfere data into the procedure  and to get
  4223.   data back  from the  procedure. Value parameters and reference parameters
  4224.   can be mixed in procedures, but they are discussed in  separate sections.
  4225.   Reference parameters will be discussed in the next section.
  4226.  
  4227.   Value parameters are special kinds of local variables that are initialized
  4228.   when the procedure is called.
  4229.  
  4230.   A procedure with value parameters have the format
  4231.  
  4232.     PROC procedure_name(formal_parameter_list) [CLOSED]
  4233.       program_statements
  4234.     ENDPROC procedure_name
  4235.  
  4236.  
  4237.   The formal_parameter_list consists of one or more formal parameters sepa-
  4238.   rated by commas. The format of a formal value parameter is
  4239.  
  4240.     ParameterName [OF Type]
  4241.     IntegerName#
  4242.     StringName$
  4243.  
  4244.  
  4245.   If the type in the first form is not specified, the type of the parameter is
  4246.   set to FLOAT (the default type).
  4247.  
  4248.  
  4249.   Example: The procedure polygon in this  example draws  a polygon.  It re-
  4250.     quires that the Turtle module is loaded.
  4251.  
  4252.       PROC polygon(Corners OF UBYTE, SideLen OF FLOAT)
  4253.         LOOP Corners TIMES
  4254.           forward(SideLen)
  4255.           right(360/Corners)
  4256.         ENDLOOP
  4257.       ENDPROC polygon
  4258.  
  4259.  
  4260.   A procedure with parameter(s) is called by executing a line of the format
  4261.  
  4262.     procedure_name(actual_parameter_list)
  4263.  
  4264.  
  4265.  
  4266.                                          75
  4267.  
  4268.  
  4269.  
  4270.  
  4271.  
  4272.   The actual  parameters consists  of one  or more expressions separated by
  4273.   commas. The types of the expressions  must be  assignment compatible with
  4274.   the corresponding formal parameters, i.e. numbers must correspond to num-
  4275.   bers and strings to strings.
  4276.  
  4277.  
  4278.   Example:  The following procedure calls are all legal calls to the procedure
  4279.     polygon:
  4280.  
  4281.       DIM s OF BYTE
  4282.  
  4283.       polygon(3,s)
  4284.       polygon(4,3.5)
  4285.       polygon(6,25/3+s)
  4286.  
  4287.  
  4288.   A value  parameter can  be of  any type  except a  STRUC. An array can be
  4289.   transferred either by defining an array type and then use this type in the
  4290.   formal parameter description, or by using array indicators.
  4291.  
  4292.  
  4293.   Example:
  4294.  
  4295.     PROC ArrParProc1(Alfa OF ArrType)   // Array type used
  4296.     PROC ArrParProc2(Beta(,) OF LONG)   // Array indicator used
  4297.     TYPE ArrType=ARRAY(5,8) OF LONG
  4298.  
  4299.  
  4300.   In both  cases the  actual parameter must be an array name with array in-
  4301.   dicators.
  4302.  
  4303.  
  4304.   Example: The procedure PrintArray in this example prints an array as a two
  4305.     dimensional table.
  4306.  
  4307.     PROC PrintArray(Beta(,) OF BYTE)
  4308.       ZONE 5
  4309.       FOR i=1 to MAXINDEX(Beta(,),1) DO
  4310.         FOR j=1 TO MAXINDEX(Beta(,),2) DO
  4311.           PRINT Beta(i,j),
  4312.         ENDFOR j
  4313.         PRINT
  4314.       ENDFOR i
  4315.     ENDPROC PrintArray
  4316.  
  4317.     PrintArray(A(,))
  4318.  
  4319.  
  4320.   Note that  if arrays are used as value parameters, a copy of the array is
  4321.   made each time the procedure is called. This can result in a  lot of time
  4322.  
  4323.                                          76
  4324.  
  4325.  
  4326.  
  4327.  
  4328.  
  4329.   consuming copying. Therefor it is recommended to use reference parameters
  4330.   when possible (as for instance in the example above).
  4331.  
  4332.   Procedures (and functions) can be used as parameters. To do this a procu-
  4333.   dure (function) type has to be defined (see section 1.5).
  4334.  
  4335.  
  4336.   3.1.3 Reference parameters.
  4337.  
  4338.   Reference parameters can be used to return values back from a procedure.
  4339.  
  4340.   Procedures with reference parameters have the format
  4341.  
  4342.     PROC procedure_name(formal_parameter_list) [CLOSED]
  4343.       program_statements
  4344.     ENDPROC procedure_name
  4345.  
  4346.  
  4347.   The formal_parameter_list consists of one or more formal parameters sepa-
  4348.   rated by commas. The format of a formal referencee parameter is
  4349.  
  4350.     REF ParameterName [OF Type]
  4351.     REF IntegerName#
  4352.     REF StringName$
  4353.  
  4354.  
  4355.   If the type in the first form is not specified, the type of the parameter is
  4356.   set to FLOAT (the default type).
  4357.  
  4358.   Example: The  procedure swap  in this example interchanges the content of
  4359.     two string variables (with maximal length 50)
  4360.  
  4361.       text1$:="Text number 1"
  4362.       text2$:="Text number 2"
  4363.       swap(text1$,text2$)
  4364.  
  4365.       PROC swap(REF t1$,REF t2$)
  4366.         LOCAL Temp$ OF 50
  4367.  
  4368.         Temp$:=t1$
  4369.         t1$:=t2$
  4370.         t2$:=Temp$
  4371.       ENDPROC swap
  4372.  
  4373.  
  4374.   A procedure with reference parameter(s) is called by executing a line of the
  4375.   format
  4376.  
  4377.     procedure_name(actual_parameter_list)
  4378.  
  4379.  
  4380.                                          77
  4381.  
  4382.  
  4383.  
  4384.  
  4385.  
  4386.  
  4387.   The actual parameters consists of one or more variables separated by com-
  4388.   mas. The type of the variables must be the same as the type of the corre-
  4389.   sponding formal  parameters, i.e. string must correspond to string, FLOAT
  4390.   to FLOAT, ULONG to ULONG etc.
  4391.  
  4392.   At the call to a procedure with reference parameters a new local variable
  4393.   is not created (as was the case with value parameters). Only a new name is
  4394.   introduced to identify an existing variable. Every change made in the para-
  4395.   meter is therefore made on the variable used as the actual parameter in the
  4396.   calling line.
  4397.  
  4398.   To be specific. The changes made on the strings t1$ and t2$ in the proce-
  4399.   dure swap  in the  example above are in fact made on the string variables
  4400.   text1$ and text2$.
  4401.  
  4402.  
  4403.   3.1.4 Local procedures.
  4404.  
  4405.   It is possible to place procedures and/or functions inside a procedure (or
  4406.   function). Such a procedure is called a local procedure and it is only known
  4407.   inside the procedure where it is placed.
  4408.  
  4409.   Example:
  4410.  
  4411.     PROC QuickSort(REF t$(),Start OF LONG,End OF LONG)
  4412.       LOCAL temp$ OF 10, x$ OF 10
  4413.       LOCAL a OF LONG, z OF LONG
  4414.  
  4415.       a:=Start; z:=End; x$:=t$((Start+End)/2)
  4416.       REPEAT
  4417.         WHILE t$(a)<x$ DO a:+1
  4418.         WHILE x$<t$(z) DO z:-1
  4419.         IF a<=z THEN
  4420.           swap(t$(a),t$(z))
  4421.           a:+1; z:-1
  4422.         ENDIF
  4423.       UNTIL a>z
  4424.       IF Start<z THEN QuickSort(t$(),Start,z)
  4425.       IF a<End THEN QuickSort(t$(),a,End)
  4426.  
  4427.       PROC swap(REF t1$,REF t2$)
  4428.         LOCAL Temp$ OF 50
  4429.  
  4430.         Temp$:=t1$
  4431.         t1$:=t2$
  4432.         t2$:=Temp$
  4433.       ENDPROC swap
  4434.  
  4435.     ENDPROC QuickSort
  4436.  
  4437.                                          78
  4438.  
  4439.  
  4440.  
  4441.  
  4442.  
  4443.  
  4444.  
  4445.  
  4446.   3.1.5 Local and global variables. CLOSED procedures.
  4447.  
  4448.   Variables, procedures, functions and type definitions outside a procedure are
  4449.   accessible from a procedure.
  4450.  
  4451.   Further more, a variable created inside a procedure (either declared in a
  4452.   DIM statement or declared implicitely in an assignment statement) is in fact
  4453.   created out side the procedure an is still there after the procedure is left.
  4454.  
  4455.  
  4456.   Example: The output from the following little program
  4457.  
  4458.       x:=-5
  4459.       y:=-8
  4460.       MyProc
  4461.       PRINT x;y
  4462.  
  4463.       PROC MyProc
  4464.         x:=11
  4465.         y:=7
  4466.       ENDPROC MyProc
  4467.  
  4468.     is
  4469.  
  4470.       11 7
  4471.  
  4472.  
  4473.   Sometimes these effects of creating and/or using variables inside a proce-
  4474.   dure are intended. But in other cases it is the source of unpredictable and
  4475.   undiserable results.
  4476.  
  4477.   If a variable used inside a procedure is strictly local to that procedure, it
  4478.   should be declared as local. This is done in a LOCAL statement,  that has
  4479.   the same form as a DIM statement:
  4480.  
  4481.     LOCAL name[(dimension_specification)] [OF Type]
  4482.     LOCAL pntr_name OF POINTER TO Type
  4483.     LOCAL integer_name#[(dimension_specification)]
  4484.     LOCAL string_name$[(dimension_specification)] OF string_len
  4485.  
  4486.  
  4487.   Example: The output from the following little program
  4488.  
  4489.       x:=-5
  4490.       y:=-8
  4491.       MyProc
  4492.       PRINT x;y
  4493.  
  4494.                                          79
  4495.  
  4496.  
  4497.  
  4498.  
  4499.  
  4500.  
  4501.       PROC MyProc
  4502.         LOCAL x OF SHORT
  4503.         x:=11
  4504.         y:=7
  4505.       ENDPROC MyProc
  4506.  
  4507.     is
  4508.  
  4509.       -5 7
  4510.  
  4511.  
  4512.   Example:
  4513.  
  4514.     PROC QuickSort(REF t$(),Start OF LONG,End OF LONG)
  4515.       LOCAL temp$ OF 10, x$ OF 10
  4516.       LOCAL a OF LONG, z OF LONG
  4517.       a:=Start; z:=End; x$:=t$((Start+End)/2)
  4518.       REPEAT
  4519.         WHILE t$(a)<x$ DO a:+1
  4520.         WHILE x$<t$(z) DO z:-1
  4521.         IF a<=z THEN
  4522.           temp$:=t$(a); t$(a):=t$(z); t$(z):=temp$
  4523.           a:+1; z:-1
  4524.         ENDIF
  4525.       UNTIL a>z
  4526.       IF Start<z THEN QuickSort(t$(),Start,z)
  4527.       IF a<End THEN QuickSort(t$(),a,End)
  4528.     ENDPROC QuickSort
  4529.  
  4530.  
  4531.   The use of local variables prevents undiserable name coincidence. Another
  4532.   way to avoid this is to make the procedure closed. This is accomplished by
  4533.   adding the word CLOSED at the end of the PROC line.
  4534.  
  4535.   All variables in a closed procedure are local, and variables, procedures and
  4536.   functions found outside the procedure is unknown inside the procedure.
  4537.  
  4538.   Example: The output from the following little program is -5 -8
  4539.  
  4540.  
  4541.       x:=-5
  4542.       y:=-8
  4543.       MyProc
  4544.       PRINT x;y
  4545.  
  4546.       PROC MyProc CLOSED
  4547.         x:=11
  4548.         y:=7
  4549.       ENDPROC MyProc
  4550.  
  4551.                                          80
  4552.  
  4553.  
  4554.  
  4555.  
  4556.  
  4557.  
  4558.  
  4559.   In order to make identifiers outside a closed procedure accessible it is pos-
  4560.   sible to  import them. This is done by using the IPMPORT statement or the
  4561.   GLOBAL statement.
  4562.  
  4563.   The IMPORT statement is used to import identifiers from the program level
  4564.   just below  the procedures  level (for  instance another procedure if the
  4565.   IMPORT statement is placed  in a  local procedure).  The GLOBAL statement
  4566.   imports identifiers from the main part of the current program environment
  4567.   (from the main program, from the initialization part of a  module or from
  4568.   the fields in a STRUC if the GLOBAL statement is placed in a method).
  4569.  
  4570.   The general format of an IMPORT statement and a GLOBAL statement is
  4571.  
  4572.     IMPORT name_list
  4573.     GLOBAL name_list
  4574.  
  4575.   where name_list is one or more names separated by commas.
  4576.  
  4577.   Example:
  4578.     IMPORT a,Beta,Str$
  4579.     GLOBAL p#,Alfa$,x
  4580.  
  4581.  
  4582.   Example:  The QuickSort procedure could have been written (although it is
  4583.     not recommendable):
  4584.  
  4585.     PROC QuickSort(Start OF LONG,End OF LONG) CLOSED
  4586.       IMPORT t$
  4587.       DIM temp$ OF 10, x$ OF 10
  4588.       DIM a OF LONG, z OF LONG
  4589.       a:=Start; z:=End; x$:=t$((Start+End)/2)
  4590.       REPEAT
  4591.         WHILE t$(a)<x$ DO a:+1
  4592.         WHILE x$<t$(z) DO z:-1
  4593.         IF a<=z THEN
  4594.           temp$:=t$(a); t$(a):=t$(z); t$(z):=temp$
  4595.           a:+1; z:-1
  4596.         ENDIF
  4597.       UNTIL a>z
  4598.       IF Start<z THEN QuickSort(Start,z)
  4599.       IF a<End THEN QuickSort(a,End)
  4600.     ENDPROC QuickSort
  4601.  
  4602.  
  4603.   It is possible to place USE statements and TYPE definition statements in-
  4604.   side a closed procedure.
  4605.  
  4606.  
  4607.  
  4608.                                          81
  4609.  
  4610.  
  4611.  
  4612.  
  4613.  
  4614.   3.2 Functions.
  4615.  
  4616.   The FUNC  statement is  used to  define funtions. The general format of a
  4617.   FUNC statement is
  4618.  
  4619.     FUNC func_name[(formal_parameter_list)] [OF NumType] [CLOSED]
  4620.       program_statements
  4621.     ENDFUNC func_name
  4622.  
  4623.   or
  4624.  
  4625.     FUNC int_func_name#[(formal_parameter_list)] [CLOSED]
  4626.       program_statements
  4627.     ENDFUNC int_func_name#
  4628.  
  4629.   or
  4630.  
  4631.     FUNC str_func_name$[(formal_parameter_list)] [CLOSED]
  4632.       program_statements
  4633.     ENDFUNC str_func_name$
  4634.  
  4635.  
  4636.   The default type in the first form is FLOAT. The value returned by a func-
  4637.   tion is calculated in a function RETURN statement of the form:
  4638.  
  4639.     RETURN expression
  4640.  
  4641.  
  4642.   The expression  must match with the function type and there have to be at
  4643.   least one function RETURN line in a function.
  4644.  
  4645.   The program statements inside the functions are activated  by placing the
  4646.   function name in an expression.
  4647.  
  4648.   Examples:
  4649.  
  4650.     PRINT 1-errf(1.5)
  4651.     y:=sinh(x)/cosh(x)
  4652.  
  4653.  
  4654.   Except for the returned value, there is no difference between functions and
  4655.   procedures. The sections 3.1.1 to 3.1.5 holds for functions, too.
  4656.  
  4657.   Example: The following function gcd calculates the greatest common divisor
  4658.     of two integer numbers
  4659.  
  4660.       FUNC gcd(m OF LONG,n OF LONG)
  4661.         IF (m MOD n)=0 THEN
  4662.           RETURN n
  4663.         ELSE
  4664.  
  4665.                                          82
  4666.  
  4667.  
  4668.  
  4669.  
  4670.  
  4671.           RETURN gcd(n,m MOD n)
  4672.         ENDIF
  4673.       ENDFUNC gcd
  4674.  
  4675.  
  4676.   Example: The following function WaitKey$ waits for special keys to be en-
  4677.     tered
  4678.  
  4679.         :
  4680.       PRINT "Yes or No (Y/N)? ",
  4681.       IF WaitKey$("YyNn") IN "Yy" THEN
  4682.         :
  4683.       ELSE
  4684.         :
  4685.       ENDIF
  4686.         :
  4687.  
  4688.       FUNC WaitKey$(WaitChars$)
  4689.         LOCAL ch$ OF 1
  4690.         REPEAT
  4691.           ch$:=INKEY$
  4692.         UNTIL ch$ IN WaitChars$
  4693.         PRINT ch$,
  4694.         RETURN ch$
  4695.       ENDFUNC WaitKey$
  4696.  
  4697.  
  4698.   Example: The following function  PenColor$ returns  a string  that can be
  4699.     used to set the drawing color of the console
  4700.  
  4701.         :
  4702.       PRINT PenColor$(3),"A nice color",PenColor$(1)
  4703.         :
  4704.  
  4705.       FUNC PenColor$(col OF UBYTE)
  4706.         RETURN CHR$($9B)+STR$(30+(col MOD 7))+"m"
  4707.       ENDFUNC PenColor$
  4708.  
  4709.  
  4710.   4 Exception handling.
  4711.  
  4712.   This section describes how exceptions such as user break and run time er-
  4713.   rors may be handled.
  4714.  
  4715.   4.1 The TRAP statement.
  4716.  
  4717.   Normally a run time error such as Division by zero or Out  of memory will
  4718.   result in  a program  stop. This  can be prevented by the TRAP statement.
  4719.   The format of a TRAP statement is
  4720.  
  4721.  
  4722.                                          83
  4723.  
  4724.  
  4725.  
  4726.  
  4727.  
  4728.       TRAP
  4729.         statements_1
  4730.       HANDLER
  4731.         statements_2
  4732.       ENDTRAP
  4733.  
  4734.  
  4735.   If an error is detected during the execution af statements_1 then the seg-
  4736.   ment statements_2  will be executed. Otherwise the program continues with
  4737.   the first statement after ENDTRAP.
  4738.  
  4739.  
  4740.   Example: In this example two files are used. If an error is detected during
  4741.     the opening of the second file the first one has to be closed before the
  4742.     the program stops
  4743.  
  4744.       OPEN FILE 1,File1$,WRITE
  4745.       TRAP
  4746.         OPEN FILE 2,File2$,READ
  4747.       HANDLER
  4748.         CLOSE FILE 1
  4749.         REPORT
  4750.       ENDTRAP
  4751.  
  4752.         :
  4753.  
  4754.  
  4755.  
  4756.   In connection with the handling of errors a number of error handling state-
  4757.   ments an convenient system functions are available:
  4758.  
  4759.       REPORT [ErrNum,[ErrText$]]
  4760.  
  4761.         This statement can be used to generate an error.
  4762.  
  4763.         If used  alone the error reported will be the error that caused the
  4764.         HANDLER section to be executed.
  4765.  
  4766.         If ErrNum is present the error text connected to this number will be
  4767.         reported.
  4768.  
  4769.         If ErrText$ is present this test will be reported.
  4770.  
  4771.  
  4772.       RETRY
  4773.  
  4774.         This statement directs the execution back to the first statement in
  4775.         statemens_1.
  4776.  
  4777.  
  4778.  
  4779.                                          84
  4780.  
  4781.  
  4782.  
  4783.  
  4784.  
  4785.       ERR
  4786.  
  4787.         A function that returns the error number of the error detected.
  4788.  
  4789.  
  4790.       ERRFILE
  4791.  
  4792.         A function that returns the number of the  file in  question if the
  4793.         error occurs in connection with a file operation.
  4794.  
  4795.  
  4796.       ERRTEXT$
  4797.  
  4798.         A function that returns the string containing the error message that
  4799.         the system would have generated.
  4800.  
  4801.  
  4802.   Example:  This piece of code reads  a  number  using  the  standard input
  4803.     statement INPUT. If the input is not a legal number the screen is flashed
  4804.     and the input statement is reexecuted:
  4805.  
  4806.         TRAP
  4807.           INPUT AT 5,10: "Enter a number: ": Num
  4808.         HANDLER
  4809.           PRINT CHR$(7),
  4810.           RETRY
  4811.         ENDTRAP
  4812.  
  4813.  
  4814.  
  4815.   4.2 The TRAP ESC statement.
  4816.  
  4817.   If the user presses the Esc-key (while the execute window  is active) the
  4818.   program will normally be breaked.
  4819.  
  4820.   The TRAP  ESC statement  is used  to control the operation of user breaks
  4821.   from within a Comal program.
  4822.  
  4823.   By executing TRAP ESC+ a user  break will  be handled  in the  normal way
  4824.   (the execution is interrupted).
  4825.  
  4826.   By executing TRAP ESC- the following will occur:
  4827.  
  4828.     - Ppressing the Esc-key will no longer interrupt a running program.
  4829.  
  4830.     - The system  function ESC  equals FALSE  (=0) until  the user tries to
  4831.       break the program; then it equals TRUE (=1).
  4832.  
  4833.   Thus a Comal program can use the value of ESC to check for user break.
  4834.  
  4835.  
  4836.                                          85
  4837.  
  4838.  
  4839.  
  4840.  
  4841.  
  4842.   Note, that the selection of the Stop Execution  item in  the Program menu
  4843.   cannot be masked, i.e. the program will always be stopped by doing this.
  4844.  
  4845.  
  4846.  
  4847.   5 IO statements.
  4848.  
  4849.   In this section the different forms of IO statements will be described. The
  4850.   most frequent used IO statements are PRINt and INPUT.
  4851.  
  4852.  
  4853.   5.1 The PRINT statement.
  4854.  
  4855.   The general format of the output statement PRINT is
  4856.  
  4857.     PRINT [AT Row,Col:] [USING Format_text:] [print_list] [mark]
  4858.  
  4859.    
  4860.   Simple PRINT statement
  4861.  
  4862.     The simplest for af the PRINT statement has the form
  4863.  
  4864.       PRINT print_list [mark]
  4865.  
  4866.     where print_list is one ore more of the following separated by either a
  4867.     comma (,) or a semicolon (;)
  4868.  
  4869.       TAB(position)
  4870.  
  4871.         where position is a numeric expression with value from 1 to 255
  4872.  
  4873.       string expression
  4874.  
  4875.       number expression
  4876.  
  4877.     and mark is either a comma (,) or a semicolon (;).
  4878.  
  4879.     The use  of TAB will result in the output of spaces up to the specified
  4880.     position if this position is not already passed.
  4881.  
  4882.     The separator comma (,) has no influence on the output (it acts solely as
  4883.     a separator). The separator semicolon (;) outputs spaces up to the next
  4884.     ZONE tabulation (the default ZONE tabulation is one resulting always in
  4885.     the output one extra space).
  4886.  
  4887.     If mark is not used a terminating line feed is output. If present it acts
  4888.     like the separator.
  4889.  
  4890.  
  4891.  
  4892.  
  4893.                                          86
  4894.  
  4895.  
  4896.  
  4897.  
  4898.  
  4899.     Examples:
  4900.  
  4901.       PRINT 2;-3
  4902.       PRINT "x=",x;"y=",y
  4903.       PRINT x,TAB(8),
  4904.       PRINT y,TAB(16)
  4905.       PRINT SIN(x);
  4906.       PRINT             // Output an empty line
  4907.  
  4908.  
  4909.   Formatted output with PRINT USING
  4910.  
  4911.     The PRINT USING statement allows formatted  output. This  statement has
  4912.     the format:
  4913.  
  4914.       PRINT USING Format_text: [print_list] [mark]
  4915.  
  4916.     where Format_text is a normal text expression containing the format cha-
  4917.     racters '#' '.' and '-' and print_list is one ore more number expressions
  4918.     separated by comma (,).
  4919.  
  4920.     Examples:
  4921.  
  4922.       PRINT USING "Pi = #.####": PI
  4923.       FOR x=0 TO 2*PI STEP 0.2 DO
  4924.         PRINT USING "sin(#.#)=-#.####":x,SIN(x)
  4925.       ENDFOR x
  4926.  
  4927.     All the characters in the the format except the special formmat charac-
  4928.     ters are printed as is. The format fields in the text are replaced one by
  4929.     one by  the values of the number expressions in the Print_list. To make
  4930.     room for a sign a minus sign (-) has to precede the format characters.
  4931.  
  4932.  
  4933.   PRINT AT specified position in window
  4934.  
  4935.     The beginning of the output can be set to any position of the screen by
  4936.     means of the PRINT AT statement with the form
  4937.  
  4938.       PRINT AT Row,Col: [USING Format_text:] [print_list] [mark]
  4939.  
  4940.  
  4941.     Examples:
  4942.  
  4943.       PRINT AT 10,20: "Hello world!"
  4944.       PRINT AT 0,20: USING "Pi = #.####": PI
  4945.  
  4946.  
  4947.     If Row is zero the current line is used, and if Col is zero the current
  4948.     column is used.
  4949.  
  4950.                                          87
  4951.  
  4952.  
  4953.  
  4954.  
  4955.  
  4956.  
  4957.  
  4958.   5.2 The INPUT statement.
  4959.  
  4960.   The general format of the input statement INPUT is
  4961.  
  4962.     INPUT [AT Row,Col[,lenght]:] [Promt-string:] variable_list [mark]
  4963.  
  4964.  
  4965.   Simple INPUT statement
  4966.  
  4967.     The simple form of the INPUT statement is
  4968.  
  4969.       INPUT [Promt_string:] variable_list [mark]
  4970.  
  4971.     where variable_list is one ore more text or number variables separated by
  4972.     comma (,) and mark has the same effect as in the PRINT statement.
  4973.  
  4974.  
  4975.     Example:
  4976.  
  4977.       INPUT x,y,t$
  4978.       INPUT "Enter a text: ": t$
  4979.  
  4980.  
  4981.     If the Promt_string is present this will be printed. Otherwise a question
  4982.     mark (?) wil be printed. Then the cursor is turned on and  the user may
  4983.     type in the values for the variables. The input is terminated by pressing
  4984.     the <ENTER>  key. The  values entered  are assigned  one by  one to the
  4985.     variables in the variable list. A string variable will be assigned the rest
  4986.     of the line entered.
  4987.  
  4988.  
  4989.   INPUT AT specified position in window
  4990.  
  4991.     The beginning of the promt string can be set to any position of the win-
  4992.     dow by means of the INPUT AT statement with the form
  4993.  
  4994.       INPUT AT Row,Col: [Promt-string:] variable_list [mark]
  4995.  
  4996.  
  4997.     Example:
  4998.  
  4999.       INPUT AT 5,10: "Enter a number: ": Num
  5000.  
  5001.  
  5002.     If Row is zero the current line is used, and if Col is zero the current
  5003.     column is used (like PRINT AT).
  5004.  
  5005.  
  5006.  
  5007.                                          88
  5008.  
  5009.  
  5010.  
  5011.  
  5012.  
  5013.   Specifying the length of the input field
  5014.  
  5015.     By adding a lengthfield to the  AT part  of an  INPUT AT  statement the
  5016.     length of  the input field can be specified. The general format of this
  5017.     statement is
  5018.  
  5019.       INPUT AT Row,Col,Lenght: [Promt-string:] variable_list [mark]
  5020.  
  5021.  
  5022.     Example:
  5023.  
  5024.       INPUT AT 0,0,1: "Accept (Y/N)? ": Answer$
  5025.  
  5026.  
  5027.   5.3 Redirection of IO.
  5028.  
  5029.   Normally all IO goes through the console attached to the program. But it is
  5030.   possible to redirect input and/or output to another device or a file. This
  5031.   done by using the SELECT statement that has the form:
  5032.  
  5033.     SELECT Direction File$
  5034.  
  5035.   where Direction is INPUT, OUTPUT or  INOUT and  File$ is  either the name
  5036.   of a file or the name of one of the standard devices
  5037.  
  5038.     ds:   the console window (only output)
  5039.     kb:   the keyboard (only input)
  5040.     lp:   a printer (only output)
  5041.  
  5042.  
  5043.     Example:
  5044.  
  5045.       INPUT "Output on printer (Y/N)? ": Answer$
  5046.  
  5047.       IF "Yy" IN Answer$ THEN
  5048.         SELECT OUTPUT "lp:"     // Select printer
  5049.         MakeOutput
  5050.         SELECT OUTPUT "ds:"     // Output back to window
  5051.       ELSE
  5052.         MakeOutput
  5053.       ENDIF
  5054.  
  5055.  
  5056.   It is  possible to  add other devices than the three above (or replace an
  5057.   existing one). To do this you have to write device drivers for that device
  5058.   and then add the device to the device list. Normally these drivers is writ-
  5059.   ten in C, but it is possible to write them in Comal, too. See chapter VII.
  5060.  
  5061.  
  5062.  
  5063.  
  5064.                                          89
  5065.  
  5066.  
  5067.  
  5068.  
  5069.  
  5070.   5.4 System functions performing IO.
  5071.  
  5072.   A number of system function can be used to perform IO. These are
  5073.  
  5074.  
  5075.     FUNC KEY$
  5076.  
  5077.       By calling this string function the keyboard buffer is scanned. If there
  5078.       is no  key in  the buffer the empty string is returned. Otherwise the
  5079.       first key in the buffer is returned. Note that some  keys return more
  5080.       than a single character.
  5081.  
  5082.       The key returned (if any) is not echoed on the window.
  5083.  
  5084.       Example:
  5085.  
  5086.         PRINT "Press any key to continue"
  5087.         WHILE KEY$="" DO WAIT
  5088.  
  5089.  
  5090.     FUNC INKEY$
  5091.  
  5092.       This string  function does the same as KEY$ but if there is no key in
  5093.       the buffer the empty string is not returned. In stead the process will
  5094.       go to sleep until a key is pressed.
  5095.  
  5096.       The key returned is not echoed on the window.
  5097.  
  5098.  
  5099.     FUNC INKEY$(time_out)
  5100.  
  5101.       This string function does the same as INKEY$ but if there is no key in
  5102.       the buffer it will wait maximal time_out seconds for a keypress before
  5103.       continuing program  execution. If  no keypress is detected within the
  5104.       time limit the empty strin is returned.
  5105.  
  5106.       The key returned (if any) is not echoed on the window.
  5107.  
  5108.  
  5109.   5.5 Other IO related statements and functions.
  5110.  
  5111.  
  5112.     CURSOR Row,Col
  5113.  
  5114.       Statement used to place the cursor on the window.
  5115.  
  5116.       If Row is zero the current line is used, and if Col is zero the current
  5117.       column is used (like PRINT AT and INPUT AT).
  5118.  
  5119.  
  5120.  
  5121.                                          90
  5122.  
  5123.  
  5124.  
  5125.  
  5126.  
  5127.       Example:
  5128.  
  5129.         CURSOR 15,5
  5130.  
  5131.  
  5132.  
  5133.     CURCOL
  5134.  
  5135.       Function returning the current column position of the cursor.
  5136.  
  5137.       Example:
  5138.  
  5139.         CurX:=CURCOL
  5140.  
  5141.  
  5142.  
  5143.     CURROW
  5144.  
  5145.       Function returning the current row position of the cursor.
  5146.  
  5147.       Example:
  5148.  
  5149.         CurY:=CURROW
  5150.  
  5151.  
  5152.  
  5153.     PAGE
  5154.  
  5155.       Statement used to clear the screen or make a form feed (page eject) if
  5156.       the current output direction is the printer.
  5157.  
  5158.       Example:
  5159.  
  5160.         PAGE
  5161.  
  5162.  
  5163.     ZONE tab_interval
  5164.  
  5165.       Statement used to set the width of the  tab zone  on the  window (see
  5166.       description of the separator semicolon (;) in section 5.1)
  5167.  
  5168.       Example:
  5169.  
  5170.         ZONE 8
  5171.  
  5172.       At startup the zone value is 1.
  5173.  
  5174.  
  5175.  
  5176.  
  5177.  
  5178.                                          91
  5179.  
  5180.  
  5181.  
  5182.  
  5183.  
  5184.     ZONE
  5185.  
  5186.       Function used to return the current zone value.
  5187.  
  5188.       Example:
  5189.  
  5190.         OldZone:=ZONE
  5191.  
  5192.  
  5193.  
  5194.     DIGITS number_of_digits
  5195.  
  5196.       Statement used to specify the number of significant digits wich will be
  5197.       shown in any PRINT statement.
  5198.  
  5199.       Example:
  5200.  
  5201.         DIGITS 12
  5202.  
  5203.       At startup the number of digits is 10.
  5204.  
  5205.  
  5206.     DIGITS
  5207.  
  5208.       Function used to return the current  number of  digits used  in PRINT
  5209.       statements.
  5210.  
  5211.       Example:
  5212.  
  5213.         OldDigits:=DIGITS
  5214.  
  5215.  
  5216.  
  5217.  
  5218.   6 File statements.
  5219.  
  5220.  
  5221.   Comal saves  data on  external starage media using two different types of
  5222.   data files:
  5223.  
  5224.     - Sequential files
  5225.  
  5226.     - Random access files (direct files)
  5227.  
  5228.   Further more data can be saved in two different formats:
  5229.  
  5230.     - Binary format
  5231.  
  5232.     - ASCII format (text files)
  5233.  
  5234.  
  5235.                                          92
  5236.  
  5237.  
  5238.  
  5239.  
  5240.  
  5241.  
  5242.   6.1 Sequential binary files.
  5243.  
  5244.   In a sequential file one item is saved after another without regard for the
  5245.   space that each item occupies.
  5246.  
  5247.   A sequential  data file  has to  be opened before you can read from it or
  5248.   write to it. This is done by executing an OPEN statement of the format
  5249.  
  5250.     OPEN FILE FileNo,FileName$,OpenMode
  5251.  
  5252.   where FileNo is a number in the range 1..32767 used to identify  the file
  5253.   and OpenMode is one of the following:
  5254.  
  5255.     READ        file is opened for reading only
  5256.     WRITE       write only (create new file or overwrite existing file)
  5257.     READWRITE   both read and write access possible
  5258.     APPEND      write access (append to existing or create a new file)
  5259.  
  5260.  
  5261.   FileName$ is  the name  of an  AmigaDOS file  or the  name of  one of the
  5262.   standard devices introduced in section 5.3.  Normally the  READWRITE open
  5263.   mode is used only in connection with special devices such as a serial devi-
  5264.   ce.
  5265.  
  5266.  
  5267.   Example:
  5268.  
  5269.     OPEN FILE 2,"MyFile",APPEND
  5270.     OPEN FILE 1,"Data",READ
  5271.  
  5272.  
  5273.   Data is written to a sequential binary file using a WRITE statement of the
  5274.   form:
  5275.  
  5276.     WRITE FILE FileNo: write_list
  5277.  
  5278.   where write_list is one or more expressions or variables separated by com-
  5279.   mas (,) and FileNo is the number used in the OPEN statement.
  5280.  
  5281.  
  5282.   Example:
  5283.  
  5284.     WRITE FILE 1: Alfa,Text$,Beta
  5285.     WRITE FILE 9: 2+4,3.14159,"Amiga"+"DOS"
  5286.  
  5287.  
  5288.   It is possible to write a whole record or a whole array to a  file in one
  5289.   write statement.
  5290.  
  5291.  
  5292.                                          93
  5293.  
  5294.  
  5295.  
  5296.  
  5297.  
  5298.  
  5299.   Example:
  5300.     DIM Member OF Person
  5301.     DIM Club(100) OF Person
  5302.  
  5303.       :
  5304.  
  5305.     WRITE FILE 2: Member
  5306.     WRITE FILE 2: Club()      // Note the array indicator
  5307.  
  5308.  
  5309.   Data is  read from a sequential binary file using a READ statement of the
  5310.   form:
  5311.  
  5312.     READ FILE FileNo: read_list
  5313.  
  5314.   where read_list is one or more variables separated by commas (,) and File-
  5315.   No is the number used in the OPEN statement.
  5316.  
  5317.  
  5318.   Example:
  5319.     READ FILE 1: Alfa,Text$,Beta
  5320.     READ FILE 9: n,x,t$
  5321.     READ FILE 2: Member,Club()
  5322.  
  5323.  
  5324.   The type  of the variables used to read in data from a file must have the
  5325.   same type as the corresponding data written to the file. It is very impor-
  5326.   tant that you observe this rule. Comal has almost no way to test the type
  5327.   of the data saved on a file.
  5328.  
  5329.   It is recommended that you always use variables (and not  expressions) in
  5330.   the  WRITE  statements.  Then  you  can pair WRITE and READ statements by
  5331.   using the same variables:
  5332.  
  5333.     WRITE FILE 1: Alfa,Text$,Beta
  5334.  
  5335.       :
  5336.  
  5337.     READ FILE 1: Alfa,Text$,Beta
  5338.  
  5339.  
  5340.   When file operations have been completed the file must be closed by using
  5341.   a CLOSE statement of the form:
  5342.  
  5343.     CLOSE [FILE FileNo]
  5344.  
  5345.  
  5346.   If FileNo is specified only this file will be closed. Otherwise all currently
  5347.   opened files will be closed.
  5348.  
  5349.                                          94
  5350.  
  5351.  
  5352.  
  5353.  
  5354.  
  5355.  
  5356.   Example:
  5357.  
  5358.     CLOSE FILE 2
  5359.     CLOSE
  5360.  
  5361.  
  5362.   Example: This little program will print out the whole content of a file con-
  5363.     taining short integer numbers:
  5364.  
  5365.       DIM n OF SHORT
  5366.  
  5367.       OPEN FILE 1,"Numbers",READ
  5368.       WHILE NOT EOF(1) DO
  5369.         READ FILE 1: n
  5370.         PRINT n
  5371.       ENDWHILE
  5372.       CLOSE FILE 1
  5373.  
  5374.  
  5375.     The function EOF used in the program is discussed in section 6.4.
  5376.  
  5377.  
  5378.   6.2 Random access binary files.
  5379.  
  5380.   In a random access file data items is stored on fixed positions in the file.
  5381.   A random access file is some times refered to as a direct file, because a
  5382.   specific number of bytes is reserved for each record (a group of data items)
  5383.   allowing direct access to a record when its number is known.
  5384.  
  5385.   A random access file must exist before you can open it (in contradiction to
  5386.   sequential files opened in WRITE or APPEND mode). A random access file is
  5387.   created by using a CREATE statement:
  5388.  
  5389.     CREATE FileName$,NoOfRecords,RecordLength
  5390.  
  5391.  
  5392.   where FileName$ is the name of the file you are going to create and NoOf-
  5393.   Records is the total number of records each one having the length Record-
  5394.   Length.
  5395.  
  5396.   The statement creates a file containing NoOfRecords records numbered from
  5397.   1 to NoOfRecords). The file is filled with CHR$(0).
  5398.  
  5399.  
  5400.   Example:
  5401.  
  5402.     CREATE "Numbers",100,12   // 100 records each holding one long integer
  5403.                               // .. and one float
  5404.     CREATE "Addresses",50,27  // 50 records each holding a text of max. 25
  5405.  
  5406.                                          95
  5407.  
  5408.  
  5409.  
  5410.  
  5411.  
  5412.  
  5413.  
  5414.   When you  are going  to create  a data  file you  have to decide how many
  5415.   records you need and to caclulate the necessary  size of  the records. To
  5416.   make this  calculation you  have to  use this  information about how many
  5417.   bytes each data item occupies in the record:
  5418.  
  5419.     - a text item occupies the actual length of the text (returned by the LEN
  5420.       function) plus two. The last two bytes is used to hold the actual length
  5421.       of the text.
  5422.  
  5423.     - all other data items occupies the size returned by the function SIZE.
  5424.  
  5425.  
  5426.   For the simple data types the SIZE function will return:
  5427.  
  5428.     UBYTE and BYTE:   1
  5429.     USHORT and SHORT: 2
  5430.     ULONG and LONG:   4
  5431.     FLOAT:            8
  5432.  
  5433.  
  5434.   Example: To create a file that is to hold 200 records each holding the con-
  5435.     tent of the structure
  5436.  
  5437.         STRUC Person
  5438.           DIM Name$ OF 30
  5439.           DIM Address$ OF 30
  5440.           DIM City$ OF 20
  5441.           DIM Age of UBYTE
  5442.         ENDSTRUC Person
  5443.  
  5444.     you could do the following:
  5445.  
  5446.         DIM Person of Person
  5447.         CREATE "PersonFile",200,SIZE(Person)
  5448.  
  5449.  
  5450.  
  5451.   A random  access binary  file is opened by executing an OPEN statement of
  5452.   the form
  5453.  
  5454.     OPEN FILE FileNo,FileName$,RANDOM RecordLength
  5455.  
  5456.  
  5457.   where FileNo and FileName$ is the  same as  discussed in  connection with
  5458.   sequential files and RecordLength is the size of the records in the file (the
  5459.   same size as was used to create the file).
  5460.  
  5461.  
  5462.  
  5463.                                          96
  5464.  
  5465.  
  5466.  
  5467.  
  5468.  
  5469.   Example:
  5470.     OPEN FILE 1,"Numbers",RANDOM 4
  5471.     OPEN FILE 2,"Addresses",RANDOM 27
  5472.     OPEN FILE 3,"PersonFile",RANDOM SIZE(Person)
  5473.  
  5474.  
  5475.   Data is written to a random access binary file using a WRITE statement of
  5476.   the form:
  5477.  
  5478.     WRITE FILE FileNo,RecordNo[,Offset]: write_list
  5479.  
  5480.   where FileNo  and write_list  is the same as discussed in connection with
  5481.   sequential files and RecordNo is the number of the record (a positive inte-
  5482.   ger) you want to update.
  5483.  
  5484.   If Offset is present the writing starts Offset bytes from the start of the
  5485.   record (default is zero). The Offset option is rarely used.
  5486.  
  5487.   Examples:
  5488.     WRITE FILE 1,51: n,x
  5489.     WRITE FILE 2,1: Address$
  5490.  
  5491.   Data is read from a random access binary file using  a READ  statement of
  5492.   the form:
  5493.  
  5494.     READ FILE FileNo,RecordNo[,Offset]: read_list
  5495.  
  5496.   where FileNo and read_list is the same as discussed in connection with se-
  5497.   quential files and RecordNo is the number of the record (a positive integer)
  5498.   you want to read.
  5499.  
  5500.   If Offset is present the reading starts Offset bytes from the start of the
  5501.   record (default is zero). The Offset option is rarely used.
  5502.  
  5503.   Examples:
  5504.  
  5505.     READ FILE 1,51: n,x
  5506.     READ FILE 2,1: Address$
  5507.  
  5508.  
  5509.   When file operations have been completed the file must be closed by using
  5510.   a CLOSE statement of the same form as discussed in the preceding section.
  5511.  
  5512.  
  5513.  
  5514.   6.3 ASCII files.
  5515.  
  5516.   ASCII files (text files) are always sequential. An ASCII file is opened in the
  5517.   same way as a sequential binary file, e.i. executing a statement of the form:
  5518.  
  5519.  
  5520.                                          97
  5521.  
  5522.  
  5523.  
  5524.  
  5525.  
  5526.     OPEN FILE FileNo,FileName$,OpenMode
  5527.  
  5528.   where FileNo is a number in the range 1..32767 used to identify  the file
  5529.   and OpenMode is one of the following:
  5530.  
  5531.     READ        file is opened for reading only
  5532.     WRITE       write only (create new file or overwrite existing file)
  5533.     READWRITE   both read and write access possible
  5534.     APPEND      write access (append to existing or create a new file)
  5535.  
  5536.  
  5537.   FileName$ is  the name  of an  AmigaDOS file  or the  name of  one of the
  5538.   standard devices introduced in section 5.3.  Normally the  READWRITE open
  5539.   mode is used only in connection with special devices such as a serial devi-
  5540.   ce.
  5541.  
  5542.  
  5543.   Example:
  5544.  
  5545.     OPEN FILE 2,"MyFile",APPEND
  5546.     OPEN FILE 1,"Data",READ
  5547.     OPEN FILE 7,"SER:",READWRITE    // "SER:" is the AmigaDOS serial device
  5548.     OPEN FILE 5,"lp:",WRITE         // "lp:" is the printer device
  5549.  
  5550.  
  5551.   Data is written to an ASCII file using a PRINT statement of the form:
  5552.  
  5553.     PRINT FILE FileNo: [USING Format_text:] [print_list] [mark]
  5554.  
  5555.   where FileNo is the number used in the  OPEN statement.  The rest  of the
  5556.   statement has the same form as a PRINT statement discussed in section 5.1.
  5557.  
  5558.  
  5559.   Example:
  5560.  
  5561.     PRINT FILE 1: Alfa,Text$
  5562.     PRINT FILE 5: USING "n = #### x = ##.####": n,x
  5563.  
  5564.  
  5565.   Data is written from an ASCII file using an INPUT statement of the form:
  5566.  
  5567.     INPUT FILE FileNo: variable_list [mark]
  5568.  
  5569.   where FileNo  is the  number used  in the OPEN statement. The rest of the
  5570.   statement has the same  form as  a INPUT  statement discussed  in section
  5571.   5.2.
  5572.  
  5573.  
  5574.  
  5575.  
  5576.  
  5577.                                          98
  5578.  
  5579.  
  5580.  
  5581.  
  5582.  
  5583.   Example:
  5584.  
  5585.     INPUT FILE 1: Alfa,Text$
  5586.     INPUT FILE 5: n,x
  5587.  
  5588.  
  5589.   When file operations have been completed the file must be closed by using
  5590.   a CLOSE statement of the same form as discussed in the preceding sections.
  5591.  
  5592.  
  5593.   Example: This little program will print out the whole content of a text file:
  5594.  
  5595.       DIM Line$ OF 150
  5596.  
  5597.       OPEN FILE 1,"Text",READ
  5598.       WHILE NOT EOF(1) DO
  5599.         INPUT FILE 1: Line$
  5600.         PRINT Line$
  5601.       ENDWHILE
  5602.       CLOSE FILE 1
  5603.  
  5604.     The function EOF used in the program is discussed in next section.
  5605.  
  5606.  
  5607.  
  5608.   6.4 File system related functions.
  5609.  
  5610.   A number of system functions are used in connection with files. These are
  5611.  
  5612.  
  5613.       EOF(FileNo)
  5614.  
  5615.         This function returns TRUE if the internal file pointer of the file
  5616.         opened with file number FileNo is positioned at the end of the file
  5617.         (EOF = End Of File). Otherwise it returns FALSE
  5618.  
  5619.         EOF returns TRUE as soon as the last  data item  are read  from the
  5620.         file. If an empty file is opened a call to EOF will return TRUE be-
  5621.         fore any reading at all.
  5622.  
  5623.         The following code fraction shows a safe way to read the whole con-
  5624.         tent of a (possibly empty) file
  5625.  
  5626.             OPEN FILE 1,"Name",READ
  5627.             WHILE NOT EOF(1) DO
  5628.                 :
  5629.               <do your reading>
  5630.                 :
  5631.             ENDWHILE
  5632.             CLOSE FILE 1
  5633.  
  5634.                                          99
  5635.  
  5636.  
  5637.  
  5638.  
  5639.  
  5640.  
  5641.  
  5642.       FREEFILE
  5643.  
  5644.         Returns the next available file number. This function is useful in li-
  5645.         brary procedures/functions which are to be used in various programs.
  5646.  
  5647.         Example:
  5648.  
  5649.           DIM FileNo OF SHORT
  5650.  
  5651.           FileNo:=FREEFILE
  5652.           OPEN FILE FileNo,FileName$,APPEND
  5653.             :
  5654.  
  5655.  
  5656.       GET$(FileNo,NumberOfCharaters)
  5657.  
  5658.         This string function fetches NumberOfCharaters characters  from the
  5659.         file opened with file number FileNo. The length of the string retur-
  5660.         ned will be NumberOfCharaters unless the end of file is reached first.
  5661.         In this case the string will only be those characters retrieved prior
  5662.         to the end of file.
  5663.  
  5664.         Example: This little program can be used to make a copy of any file
  5665.           (even a binary file which is not a Comal file)
  5666.  
  5667.             DIM Block$ OF 1000
  5668.  
  5669.             OPEN FILE 1,Source$,READ
  5670.             OPEN FILE 2,Destination$,WRITE
  5671.             WHILE NOT EOF(1)
  5672.               Block$=GET$(1,1000)
  5673.               PRINT FILE 2: Block$,
  5674.             ENDWHILE
  5675.             CLOSE
  5676.  
  5677.           Note the comma at the end of the PRINT FILE statement!
  5678.  
  5679.  
  5680.   6.5 READ and DATA statements.
  5681.  
  5682.   The READ  statement is  used to  read internal data stored in one or more
  5683.   data statements.
  5684.  
  5685.   The format of the READ statement is:
  5686.  
  5687.     READ read_list
  5688.  
  5689.   where read_list is one or more variables separated by commas (,).
  5690.  
  5691.                                          100
  5692.  
  5693.  
  5694.  
  5695.  
  5696.  
  5697.  
  5698.   When a READ statemet is executed the variables in the  READ statement are
  5699.   assigned values from the internal data queue formed by DATA statements in
  5700.   the program.
  5701.  
  5702.   The format of a DATA statement is:
  5703.  
  5704.     DATA data_list
  5705.  
  5706.   where data_list is one ore more number or string expressions separated by
  5707.   commas (,).
  5708.  
  5709.  
  5710.   Example: After  the execution of the DATA statement in the following pro-
  5711.     gram fraction the variable a will have the value 5, b the value 7, c the
  5712.     value 3 and t$ the value "A string" (without the quotes).
  5713.  
  5714.       READ a,t$,b,c
  5715.  
  5716.         :
  5717.  
  5718.       DATA 5
  5719.       DATA "A string",7,3
  5720.  
  5721.  
  5722.   It is possible to fill a whole array in one read.
  5723.  
  5724.  
  5725.   Example: The following two program fractions are equivalent
  5726.  
  5727.       DIM a(3,4)
  5728.  
  5729.       FOR i:=1 TO 3 DO
  5730.         FOR j:=1 TO 4 DO
  5731.           READ a(,)
  5732.         ENDFOR j
  5733.       ENDFOR i
  5734.  
  5735.         :
  5736.         :
  5737.  
  5738.       DATA 1,2,3,4
  5739.       DATA 5,6,7,8
  5740.       DATA 9,10,11,12
  5741.  
  5742.     and
  5743.  
  5744.       DIM a(3,4)
  5745.  
  5746.       READ a(,)
  5747.  
  5748.                                          101
  5749.  
  5750.  
  5751.  
  5752.  
  5753.  
  5754.  
  5755.         :
  5756.         :
  5757.  
  5758.       DATA 1,2,3,4
  5759.       DATA 5,6,7,8
  5760.       DATA 9,10,11,12
  5761.  
  5762.  
  5763.   The values are read one by one in the order the DATA constants are placed
  5764.   in the program. It is possible to change  this order  by using  a RESTORE
  5765.   statement of the form:
  5766.  
  5767.       RESTORE label
  5768.  
  5769.   where label is a label is defined in a label line (see section 2.3.1).
  5770.  
  5771.  
  5772.   Example:
  5773.  
  5774.       READ a,b
  5775.       RESTORE d
  5776.       READ c
  5777.  
  5778.       DATA 1
  5779.       d:
  5780.       DATA 2
  5781.  
  5782.  
  5783.   If you  are trying to read beyond the last data constant in the queue the
  5784.   program will stop with an error message. It is possible to test for the end
  5785.   of the  data queue  by using the function EOD (End Of Data). The function
  5786.   returns true (1) if there is no more data in the queue. Otherwise it returns
  5787.   false (0).
  5788.  
  5789.   The READ  and DATA statements are useful to initialize arrays or structu-
  5790.   res.
  5791.  
  5792.  
  5793.   Example: The  NewWindow structure  used to  open an  Intuition window can
  5794.     be initialized in this way:
  5795.  
  5796.       DIM NewWindow OF NewWindow
  5797.  
  5798.       READ NewWindow
  5799.  
  5800.         :
  5801.  
  5802.       DATA 10,20,400,100,-1,-1  // Potition, size and pen colors
  5803.       DATA 0                    // No IDCMP flags
  5804.  
  5805.                                          102
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  
  5811.       DATA WINDOWSIZING BITOR WINDOWDEPTH BITOR WINDOWDRAG
  5812.       DATA 0,0                  // Gadget and image
  5813.       DATA ADR("My window")     // Window title
  5814.       DATA 0,0                  // Screen and bitmap
  5815.       DATA 100,40,640,200       // Max and min size
  5816.       DATA WBENCHSCREEN         // Type
  5817.  
  5818.         :
  5819.  
  5820.  
  5821.  
  5822.   7 Miscellaneous statements, procedures and functions.
  5823.   
  5824.  
  5825.   7.1 DOS statements and functions.
  5826.  
  5827.   A number  of statements  can be  used to execute AmigaDOS commands. These
  5828.   statements are:
  5829.  
  5830.     CAT
  5831.  
  5832.       CAT is synonymous for DIR. CAT is relisted as DIR.
  5833.  
  5834.  
  5835.     CD
  5836.  
  5837.       CD is synonymous for CHDIR. CD is relisted as CHDIR.
  5838.  
  5839.  
  5840.     CHDIR
  5841.  
  5842.       Change the current directory. The format of the statement is:
  5843.  
  5844.         CHDIR path
  5845.  
  5846.       where path is a string expression.
  5847.  
  5848.       The statement works as the shell command CHDIR.
  5849.  
  5850.       Example:
  5851.  
  5852.         CHDIR "Demos"
  5853.         CHDIR "/"
  5854.         CHDIR Path$+"/Example"
  5855.  
  5856.     COPY
  5857.  
  5858.       Make a copy of a file. The format of the statement is:
  5859.  
  5860.         COPY OldFile,NewFile
  5861.  
  5862.                                          103
  5863.  
  5864.  
  5865.  
  5866.  
  5867.  
  5868.  
  5869.       where OldFile and NewFile are string expressions.
  5870.  
  5871.       The statement works as  the shell  command COPY  except that  the new
  5872.       name must be specified.
  5873.  
  5874.       Example:
  5875.  
  5876.         COPY "Demos/Hanoi","Ram:Hanoi"
  5877.  
  5878.  
  5879.     DELETE
  5880.  
  5881.       Remove a file from disk. The format of the statement is:
  5882.  
  5883.         DELETE FileName
  5884.  
  5885.       where FileName is a string expression.
  5886.  
  5887.       Example:
  5888.  
  5889.         DELETE "ram:Temp"
  5890.  
  5891.  
  5892.     DIR
  5893.  
  5894.       Output a  directory list  of a volume or directory. The format of the
  5895.       statement is
  5896.  
  5897.         DIR path
  5898.  
  5899.       where path is a string expression.
  5900.  
  5901.       The statement works as the shell command DIR.
  5902.  
  5903.       Example:
  5904.         DIR                 // The current directory is listed
  5905.         DIR "Modules"       // The directory Modules is listed
  5906.         DIR "df0:"+Drawer$
  5907.         DIR DIR$            // Same as just DIR
  5908.  
  5909.  
  5910.     DIR$
  5911.  
  5912.       String function returning the complete path of the current directory.
  5913.       The path string will always end with a colon (:) or a slash (/).
  5914.  
  5915.       Example:
  5916.         PRINT DIR$
  5917.         Path$:=DIR$
  5918.  
  5919.                                          104
  5920.  
  5921.  
  5922.  
  5923.  
  5924.  
  5925.  
  5926.  
  5927.     MAKEDIR
  5928.  
  5929.       Synonymous for MKDIR. MAKEDIR is relisted as MKDIR.
  5930.  
  5931.  
  5932.     MKDIR
  5933.  
  5934.       Statement used  to create  a new subdirectory (drawer). The format of
  5935.       the statement is
  5936.  
  5937.         MKDIR name
  5938.  
  5939.       where name is a string expression.
  5940.  
  5941.       The statement works as the shell command MAKEDIR.
  5942.  
  5943.       Example:
  5944.  
  5945.         MKDIR "Comal:AsciiFiles"
  5946.  
  5947.  
  5948.     PASS
  5949.  
  5950.       Statement used to execute shell commands directly. The format is
  5951.  
  5952.         PASS command
  5953.  
  5954.       where command is a string expression.  As a  result of  executing the
  5955.       command a  window will  open in  the Workbench screen and the command
  5956.       will be executed with this window as the output window. After the exe-
  5957.       cution of  the command  you will  be requested to press enter to con-
  5958.       tinue.
  5959.  
  5960.       If the  command string  commadn is  the empty  string a  new Shell is
  5961.       opened. Type  ENDCLI (or  press the close gadget in WB 2.x) to return
  5962.       to your Comal program.
  5963.  
  5964.       Example:
  5965.  
  5966.         PASS "RELABEL df0: NewName"
  5967.         PASS ""
  5968.  
  5969.  
  5970.     RENAME
  5971.  
  5972.       Statement used to give  a disk  file a  new name.  The format  of the
  5973.       statement is:
  5974.  
  5975.  
  5976.                                          105
  5977.  
  5978.  
  5979.  
  5980.  
  5981.  
  5982.         COPY OldName,NewName
  5983.  
  5984.       where OldName and NewName are string expressions.
  5985.  
  5986.       The statement works as the shell command RENAME.
  5987.  
  5988.       Example:
  5989.  
  5990.         RENAME "Demos/Hanoi","Demos/Towers"
  5991.  
  5992.  
  5993.     UNIT
  5994.  
  5995.       Synonymous for CHDIR. UNIT is relisted as CHDIR.
  5996.  
  5997.  
  5998.     UNIT$
  5999.  
  6000.       String function  returning the name of the volume containing the cur-
  6001.       rent directory.
  6002.  
  6003.       Example:
  6004.  
  6005.         PRINT UNIT$
  6006.         Volume$:=UNIT$
  6007.  
  6008.  
  6009.   7.2 Time related statements and functions.
  6010.  
  6011.  
  6012.     DATE$
  6013.  
  6014.       String function returning the current date. The string returned has the
  6015.       format yyyy-mm-dd.
  6016.  
  6017.  
  6018.     TIME$
  6019.  
  6020.       String function returning the current time. The string returned has the
  6021.       format hh:mm:ss.
  6022.  
  6023.  
  6024.     TIMER
  6025.  
  6026.       Statement used to set the value of an internal constant running timer.
  6027.  
  6028.       Example:
  6029.  
  6030.         TIMER 0         // Reset the timer
  6031.  
  6032.  
  6033.                                          106
  6034.  
  6035.  
  6036.  
  6037.  
  6038.  
  6039.  
  6040.     TIMER
  6041.  
  6042.       Number function used the return the current value of the internal ti-
  6043.       mer.
  6044.  
  6045.       Example:
  6046.  
  6047.         PRINT TIMER
  6048.  
  6049.  
  6050.     WAIT
  6051.  
  6052.       Statement used  to make  your process sleep. The format of the state-
  6053.       ment is:
  6054.  
  6055.         WAIT [delaylength]
  6056.  
  6057.       where delaylength is a number expression.
  6058.  
  6059.       If delaylength is specified the process will sleep for the specified num-
  6060.       ber of seconds. If no delaylength is specified the process will sleep
  6061.       until an event occurs (for instance a key is pressed).
  6062.  
  6063.       Example:
  6064.  
  6065.         WAIT 5                    // Sleep in 5 seconds
  6066.         WHILE KEY$="" DO WAIT
  6067.  
  6068.  
  6069.  
  6070.   7.3 Random numbers.
  6071.  
  6072.   The function RND is used to generate pseudo  random numbers.  The are two
  6073.   forms of the function RND:
  6074.  
  6075.     RND
  6076.  
  6077.       Used without  arguments the  function RND  returns a (pseudo) randaom
  6078.       number in the interval [0;1[ (1 not included).
  6079.  
  6080.  
  6081.     RND(min,max)
  6082.  
  6083.       Used with arguments an  integer random  number greater  than or equal
  6084.       min and less than or equal max is returned.
  6085.  
  6086.  
  6087.   The random  numbers are read from a random number table (the table values
  6088.   are calculated one by one). To make Comal start a new place in this table
  6089.  
  6090.                                          107
  6091.  
  6092.  
  6093.  
  6094.  
  6095.  
  6096.   the  RANDOMIZE  statement  may  be  used.  The  format  of  the RANDOMIZE
  6097.   statement is
  6098.  
  6099.     RANDOMIZE [seed]
  6100.  
  6101.  
  6102.   If seed (a numeric expression) is not present the Amiga timer is  used to
  6103.   generate the seed.
  6104.  
  6105.  
  6106.   Example: The  following program  will return  the same  random number se-
  6107.     quence each time it is run:
  6108.  
  6109.       RANDOMIZE 100
  6110.  
  6111.       LOOP 10 TIMES
  6112.         PRINT RND
  6113.       ENDLOOP
  6114.  
  6115.  
  6116.  
  6117.   7.4 STOP and END statements.
  6118.  
  6119.   A Comal program will stop after the last statement of the program  is ex-
  6120.   ecuted. To  make the  program stop before the last statement the STOP and
  6121.   END statements may be used. The format of these statements is:
  6122.  
  6123.     STOP [message]
  6124.     END [message]
  6125.  
  6126.   where message is a string expression whose value is printed in the status
  6127.   line of the editor.
  6128.  
  6129.   The  most  importent  difference  between  the STOP and END statements is
  6130.   that the program execution cannot be continued after execution of the END
  6131.   statements.
  6132.  
  6133.   If the STOP statement is executed the cursor of the editor is placed after
  6134.   the STOP and the  message STOP  statement is  executed is  printed in the
  6135.   status line (unless message is present).
  6136.  
  6137.  
  6138.   Example:
  6139.  
  6140.     STOP "Error while opening the file"
  6141.     END
  6142.  
  6143.  
  6144.  
  6145.  
  6146.  
  6147.                                          108
  6148.  
  6149.  
  6150.  
  6151.  
  6152.  
  6153.   7.5 Interrupt procedures.
  6154.  
  6155.   It is possible to make interrupt procedures in Comal. An interrupt procedure
  6156.   is a procedure with the format:
  6157.  
  6158.     PROC Interrupt(SigMask OF ULONG) CLOSED
  6159.  
  6160.  
  6161.   To activate the interrupt procedure a call must be made to the Comal pro-
  6162.   cedure ADDINTERRUPT:
  6163.  
  6164.     ADDINTERRUPT(Interrupt(),SigMask)
  6165.  
  6166.   where the  parameter SigMask is a mask containing the signals that should
  6167.   cause interrupt (more about signals in the Amiga system manual).
  6168.  
  6169.   To deactivate the interrupt procedure a  call must  be made  to the Comal
  6170.   procedure REMINTERRUPT:
  6171.  
  6172.     REMINTERRUPT(Interrupt())
  6173.  
  6174.  
  6175.  
  6176.   7.6 Mathematical functions.
  6177.  
  6178.  
  6179.     ABS         absolute value
  6180.  
  6181.       ABS(x) returns the absolute value (numerical value) of the argument x
  6182.       which may be any real number.
  6183.  
  6184.  
  6185.     ACS         arccosine
  6186.  
  6187.       ACS(x) returns the arccosine in radians of the argument x  which is a
  6188.       real number in the range from -1 to 1.
  6189.  
  6190.  
  6191.     ASN         arcsine
  6192.  
  6193.       ASN(x) returns  the arcsine  in radians  of the argument x  is a real
  6194.       number in the range from -1 to 1.
  6195.  
  6196.  
  6197.     ATN         arctangent
  6198.  
  6199.       ATN(x) returns the arccosine in radians of the  argument x  which may
  6200.       be any real number.
  6201.  
  6202.  
  6203.  
  6204.                                          109
  6205.  
  6206.  
  6207.  
  6208.  
  6209.  
  6210.     COS         cosine
  6211.  
  6212.       COS(x) returns the cosine of the argument x measured in radians.
  6213.  
  6214.  
  6215.     EXP(x)      natural exponential function
  6216.  
  6217.       EXP(x) returns the number e (=2.718281828..) raised to the power of the
  6218.       argument x.
  6219.  
  6220.  
  6221.     FLOAT
  6222.  
  6223.       FLOAT(i) returns a floating point number equalto the argument i which
  6224.       is normally an integer (but may be any number).
  6225.  
  6226.  
  6227.     INT
  6228.  
  6229.       INT(x) returns the largest integer integer which is less than or equal
  6230.       to the argument x.
  6231.  
  6232.  
  6233.     LOG         natural logarithm
  6234.  
  6235.       LOG(x) returns the natural logarithm of the argument x which is a po-
  6236.       sitive real number.
  6237.  
  6238.  
  6239.     PI
  6240.  
  6241.       PI is a constant function returning the number pi (=3.1415592655...).
  6242.  
  6243.  
  6244.     ROUND
  6245.  
  6246.       ROUND(x) returns the integer which is closest to the argument x.
  6247.  
  6248.  
  6249.     SGN         sign
  6250.  
  6251.       SGN(x) returns -1 if the argument x is negative, 0 if it is zero and +1
  6252.       if x is positive.
  6253.  
  6254.  
  6255.     SIN         sine
  6256.  
  6257.       SIN(x) returns the sine of the argument x measured in radians.
  6258.  
  6259.  
  6260.  
  6261.                                          110
  6262.  
  6263.  
  6264.  
  6265.  
  6266.  
  6267.     SQR         square root
  6268.  
  6269.       SQR(x) returns the square root of a non negative argument x.
  6270.  
  6271.  
  6272.     TAN         tangent
  6273.  
  6274.       TAN(x) returns the tangent of the argument x measured in radians.
  6275.  
  6276.  
  6277.  
  6278.   7.7 Functions involving strings.
  6279.  
  6280.  
  6281.     CHR$
  6282.  
  6283.       CHR$(x) returns a string containing the character with ASCII value x.
  6284.  
  6285.  
  6286.     LEN         string length
  6287.  
  6288.       LEN(t$) returns the length (number of character) of the string expres-
  6289.       sion used as argument.
  6290.  
  6291.  
  6292.     ORD         ordinal value
  6293.  
  6294.       ORD(t$) returns  an integer representing the ASCII value of the first
  6295.       character of the string expression used as argument. An error will re-
  6296.       sult if the empty string is used as argument.
  6297.  
  6298.  
  6299.     SPC$
  6300.  
  6301.       SPC$(n) returns  the number of blanks (spaces) specified by the argu-
  6302.       ment n.
  6303.  
  6304.  
  6305.     STR$
  6306.  
  6307.       STR$(num) returns the string equivalent of the numeric  argument num.
  6308.       The number of significant digits are set by the DIGITS statement.
  6309.  
  6310.       STR$(format$,num) returns  the string  equivalent of  the numeric ar-
  6311.       gument num. The string argument format$  specifies the  format of the
  6312.       string equivalent.  See description of PRINT USING in section 5.1 for
  6313.       further details.
  6314.  
  6315.       Example: The output from
  6316.  
  6317.  
  6318.                                          111
  6319.  
  6320.  
  6321.  
  6322.  
  6323.  
  6324.           PRINT STR$("#.###",pi)
  6325.  
  6326.         will be
  6327.  
  6328.           3.142
  6329.  
  6330.  
  6331.     VAL
  6332.  
  6333.       VAL(t$) returns the numeric equivalent of a string representing a num-
  6334.       ber. VAL and STR$ can be concidered as inverse of each other.
  6335.  
  6336.  
  6337.  
  6338.   7.8 Other functions.
  6339.  
  6340.  
  6341.     ADR
  6342.  
  6343.       Function returning the address of the data field of a variable, the code
  6344.       of a procedure/function or the address of the text in a text constant.
  6345.  
  6346.       Example:
  6347.  
  6348.         ADR(NewWindow)
  6349.         ADR("My window")
  6350.  
  6351.     FREE
  6352.  
  6353.       FREE returns the number of free bytes in the work space.
  6354.  
  6355.  
  6356.     SIZE
  6357.  
  6358.       SIZE(var) returns the number of bytes occupied byt the variable var.
  6359.  
  6360.  
  6361.  
  6362.   8 Objects.
  6363.  
  6364.   Very often a computer program can  be viewed  of as  a model  of the real
  6365.   world. In these cases a very powerful program design strategi is to base the
  6366.   structures of the program on the structures of the part of the world being
  6367.   modeled. For  each object  in the real world we should try to construct a
  6368.   corresponding computational object. Such a design strategi is called Object
  6369.   Oriented Programming design strategi (or short OOP).
  6370.  
  6371.   OOP is still rather unknown and section 8.1 is an introduction to this pro-
  6372.   gramming strategi. The sections 8.2-8.4 contains a more formal description
  6373.   of objects.
  6374.  
  6375.                                          112
  6376.  
  6377.  
  6378.  
  6379.  
  6380.  
  6381.  
  6382.  
  6383.   8.1 Introduction to OOP.
  6384.  
  6385.   As an  example to  OOP we  are going to make a simple model of a bank ac-
  6386.   count. A bank account is identified by a number (an ID code),  there is a
  6387.   balance and an interest. All together these quantities are characterizing a
  6388.   specific bank account and it would be natural to put them into a structure:
  6389.  
  6390.     STRUC BankAccount
  6391.       Id OF ULONG
  6392.       Balance OF FLOAT
  6393.       Interrest OF FLOAT
  6394.     ENDSTRUC BankAccount
  6395.  
  6396.  
  6397.   Operations can be made on a bank account. In our simple model this is de-
  6398.   positing and  withdrawal of money which can be implemented by a procedure
  6399.   and a function:
  6400.  
  6401.  
  6402.     PROC Deposit(REF Account OF BankAccount,Amount)
  6403.       Account.Balance:+Amount
  6404.     ENDPROC Deposit
  6405.  
  6406.     FUNC Withdraw(REF Account OF BankAccount,Amount) OF SHORT
  6407.       IF Account.Balance-Amount>=0 THEN
  6408.         Account.Balance:-Amount
  6409.         RETURN TRUE
  6410.       ELSE
  6411.         RETURN FALSE
  6412.       ENDIF
  6413.     UNDFUNC Withdraw
  6414.  
  6415.  
  6416.   The function Withdraw returns true if  there is  enough money  on the ac-
  6417.   count to accomodate the withdrawal. Otherwise it returns false.
  6418.  
  6419.   With  these  definitions  bank  accounts  can be created by executing DIM
  6420.   statements:
  6421.  
  6422.     DIM MyAccount OF BankAccount
  6423.     DIM YourAccount OF BankAccount
  6424.  
  6425.   and operations can be made through the procedure Deposit and the function
  6426.   Withdraw:
  6427.  
  6428.     Deposit(MyAccount,1000)
  6429.  
  6430.     IF Withdraw(YourAccount,1750) THEN
  6431.  
  6432.                                          113
  6433.  
  6434.  
  6435.  
  6436.  
  6437.  
  6438.       PRINT "New balance: ",YourAccount.Balance
  6439.     ELSE
  6440.       PRINT "Insufficient founds"
  6441.       PRINT "Balance is: ",YourAccount.Balance
  6442.     ENDIF
  6443.  
  6444.  
  6445.   The operations  Deposit and  Withdraw are  closely bound to the structure
  6446.   BankAccount and it would be natural to put them into the structure defini-
  6447.   tion itself. This is in fact possible and can be done by defining BankAc-
  6448.   count like:
  6449.  
  6450.     STRUC BankAccount
  6451.       Id OF ULONG
  6452.       Balance OF FLOAT
  6453.       Interrest OF FLOAT
  6454.  
  6455.       PROC Deposit(Amount)
  6456.         Balance:+Amount
  6457.       ENDPROC Deposit
  6458.  
  6459.       FUNC Withdraw(Amount) OF SHORT
  6460.         IF Balance-Amount>=0 THEN
  6461.           Balance:-Amount
  6462.           RETURN TRUE
  6463.         ELSE
  6464.           RETURN FALSE
  6465.         ENDIF
  6466.       UNDFUNC Withdraw
  6467.  
  6468.     ENDSTRUC BankAccount
  6469.  
  6470.  
  6471.   Procedures and functions defined inside a structure are  sometimes called
  6472.   methods. Methods cannot be closed but are otherwise normal procedures and
  6473.   functions.
  6474.  
  6475.   With this new definition bank accounts are still created by executing DIM
  6476.   statements:
  6477.  
  6478.     DIM MyAccount OF BankAccount
  6479.     DIM YourAccount OF BankAccount
  6480.  
  6481.   and operations can be made through the metods using the dot notation:
  6482.  
  6483.     MyAccount.Deposit(1000)
  6484.  
  6485.     IF YourAccount.Withdraw(1750) THEN
  6486.       PRINT "New balance: ",YourAccount.Balance
  6487.     ELSE
  6488.  
  6489.                                          114
  6490.  
  6491.  
  6492.  
  6493.  
  6494.  
  6495.       PRINT "Insufficient founds"
  6496.       PRINT "Balance is: ",YourAccount.Balance
  6497.     ENDIF
  6498.  
  6499.  
  6500.   By using  methods everything  that has to do with the bank account is put
  6501.   into the structure definition. This is callded encapsulation and is one of the
  6502.   central elements  in OOP. Another important element is the use of the in-
  6503.   heritance mechanism to conveniently derive new types from existing types.
  6504.  
  6505.   A cash credit is a bank account where the balance is allowed to be negati-
  6506.   ve (until some predefined negative value). Apart from this it shares all the
  6507.   proporties of a normal bank account. In making a model of a cash credit it
  6508.   would be  natural to  try to  reuse BankAccount.  This may be done in the
  6509.   following way where BankAccount is inherited:
  6510.  
  6511.     STRUC CashCredit
  6512.       INHERIT BankAccount
  6513.  
  6514.       DIM MinBalance OF FLOAT
  6515.  
  6516.       FUNC Withdraw(Amount) OF SHORT
  6517.         IF Balance-Amount>=0 THEN
  6518.           Balance:-Amount
  6519.           RETURN TRUE
  6520.         ELSE
  6521.           RETURN FALSE
  6522.         ENDIF
  6523.       UNDFUNC Withdraw
  6524.  
  6525.     ENDSTRUC CashCredit
  6526.  
  6527.  
  6528.   This new definition of the bank account type can be used like the old one
  6529.   and at the same time:
  6530.  
  6531.     DIM MyAccount OF BankAccount
  6532.     DIM YourAccount OF BankAccount
  6533.     DIM Cash OF CashCredit
  6534.  
  6535.     MyAccount.Deposit(1000)
  6536.     Cash.Deposit(2000)
  6537.  
  6538.     IF Cash.Withdraw(1750) THEN
  6539.       PRINT "New balance: ",Cash.Balance
  6540.     ELSE
  6541.       PRINT "Insufficient founds or illegal password"
  6542.       PRINT "Balance is: ",Cash.Balance
  6543.     ENDIF
  6544.  
  6545.  
  6546.                                          115
  6547.  
  6548.  
  6549.  
  6550.  
  6551.  
  6552.  
  6553.   Note that  the new function Withdraw in CashCredit overloads the original
  6554.   Withdraw function in BankAccount. All other fields or  methods of BankAc-
  6555.   count are inherited and can be used as if they were defined inside the new
  6556.   type CashCredit.
  6557.  
  6558.   There is another way to reuse BankAccount in the new CashCredit. First we
  6559.   have to redefine the structure BankAccount:
  6560.  
  6561.     STRUC BankAccount
  6562.       Id OF ULONG
  6563.       Balance OF FLOAT
  6564.       Interrest OF FLOAT
  6565.  
  6566.       PROC Deposit(Amount)
  6567.         Balance:+Amount
  6568.       ENDPROC Deposit
  6569.  
  6570.       FUNC Withdraw(Amount) OF SHORT
  6571.         Balance:-Amount
  6572.         IF Proceed THEN
  6573.           RETURN TRUE
  6574.         ELSE
  6575.           Balance:+Amount
  6576.           RETURN FALSE
  6577.         ENDIF
  6578.       UNDFUNC Withdraw
  6579.  
  6580.       FUNC Proceed OF SHORT VIRTUAL
  6581.         RETURN Balance>=0
  6582.       ENDFUNC Proceed
  6583.  
  6584.     ENDSTRUC BankAccount
  6585.  
  6586.  
  6587.   The legitimacy of the withdraw transaction is tested by the function Pro-
  6588.   ceed which is declared as VIRTUAL. The meaning of this will be clear soon.
  6589.   Note that  allthough BankAccount has been redefined all the code that has
  6590.   used BankAccount until now need not be rewritten.
  6591.  
  6592.   Now the CashCredit structure can be defined in this way:
  6593.  
  6594.     STRUC CashCredit
  6595.       INHERIT BankAccount
  6596.  
  6597.       DIM MinBalance OF FLOAT
  6598.  
  6599.       FUNC Proceed OF SHORT
  6600.         RETURN Balance>=MinBalance
  6601.       ENDFUNC Proceed
  6602.  
  6603.                                          116
  6604.  
  6605.  
  6606.  
  6607.  
  6608.  
  6609.  
  6610.     ENDSTRUC CashCredit
  6611.  
  6612.  
  6613.   To se how this works let  us make  one normal  bank account  and one cash
  6614.   credit by executing the statements:
  6615.  
  6616.     DIM Account OF BankAccount
  6617.     DIM Cash OF CashCredit
  6618.  
  6619.  
  6620.   If the statement
  6621.  
  6622.     IF Cash.Withdraw(750) THEN
  6623.  
  6624.   is executed  the method  Withdraw of the structure BankAccount is called.
  6625.   Inside this method another method Proceed is activated. But since Proceed
  6626.   in BankAccount is declared as VIRTUAL it is not this one that is called. In
  6627.   stead the method Proceed defined in CashCredit is called and this version
  6628.   of Proceed compares Balance with MinBalance in stead of comparing it with
  6629.   zero.
  6630.  
  6631.   On the other hand, if the statement
  6632.  
  6633.     IF Account.Withdraw(750) THEN
  6634.  
  6635.   is executed the method Withdraw of the structure Account is again called.
  6636.   But this time the object BankAccount has no descendants and it is the ori-
  6637.   ginal method Proceed inside BankAccount that is activated.
  6638.  
  6639.   As a final example let us define a special password-protected bank account
  6640.   where a  password has  to be  supplied to  withdraw money. This new pass-
  6641.   word-protected bank account shares all the properties of  the simple bank
  6642.   account. These properties are inherited from BankAccount in the following
  6643.   definition of ProtectAccount:
  6644.  
  6645.     STRUC ProtectAccount
  6646.       INHERIT BankAccount
  6647.  
  6648.       DIM Password$ OF 10
  6649.  
  6650.       FUNC Proceed OF SHORT
  6651.         LOCAL pw$ OF 10
  6652.  
  6653.         INPUT "Enter password: ":pw$
  6654.         IF pw$=Password$ THEN
  6655.           RETURN BankAccount.Proceed
  6656.         ELSE
  6657.           PRINT "Illegal password"
  6658.           RETURN FALSE
  6659.  
  6660.                                          117
  6661.  
  6662.  
  6663.  
  6664.  
  6665.  
  6666.         ENDIF
  6667.       UNDFUNC Proceed
  6668.  
  6669.     ENDSTRUC BankAccount
  6670.  
  6671.  
  6672.   8.2 Methods.
  6673.  
  6674.   An object type is a STRUC type (discussed in section 1.3.2) extended with
  6675.   one or more procedures or functions. The general format of an object type
  6676.   definition is
  6677.  
  6678.     STRUC Identifier
  6679.  
  6680.       [USE statements]
  6681.  
  6682.       DeclarationStatements
  6683.  
  6684.     ENDSTRUC Identifier
  6685.  
  6686.   where DeclarationStatements is one or more of the following
  6687.  
  6688.     - structure DIM statement (see section 1.3.2)
  6689.  
  6690.     - open procedure
  6691.  
  6692.     - open function
  6693.  
  6694.  
  6695.   Procedures and functions in  an object  type are  called methods. Methods
  6696.   must be open but are otherwise normal procedures or functions.
  6697.  
  6698.  
  6699.   Example:
  6700.  
  6701.     STRUC Person
  6702.       DIM FirstName$ OF 20
  6703.       DIM LastName$ OF 20
  6704.       DIM Address$ OF 30
  6705.       DIM City$ OF 20
  6706.       DIM Age of UBYTE
  6707.  
  6708.       PROC Input
  6709.         INPUT "First name: ": FirstName$
  6710.         INPUT "Last name:  ": LastName$
  6711.         INPUT "Address:    ": Address$
  6712.         INPUT "City:       ": City$
  6713.         INPUT "Age:        ": Age
  6714.       ENDPROC Input
  6715.  
  6716.  
  6717.                                          118
  6718.  
  6719.  
  6720.  
  6721.  
  6722.  
  6723.       PROC Print
  6724.         PRINT "First name: ", FirstName$
  6725.         PRINT "Last name:  ", LastName$
  6726.         PRINT "Address:    ", Address$
  6727.         PRINT "City:       ", City$
  6728.         PRINT "Age:        ", Age
  6729.       ENDPROC Print
  6730.  
  6731.     ENDSTRUC Person
  6732.  
  6733.  
  6734.   A object  variable or  a pointer  to an  object must dimensioned in a DIM
  6735.   statement as normal data structures discussed in section 1.3.
  6736.  
  6737.  
  6738.   Example:
  6739.  
  6740.     DIM Member OF Person
  6741.     DIM Club(100) OF Person
  6742.     DIM PersonPtr OF POINTER TO Person
  6743.  
  6744.     ALLOCATE(PersonPtr)
  6745.  
  6746.  
  6747.   Methods are activated by using the dot notation on the variable.
  6748.  
  6749.  
  6750.   Example:
  6751.  
  6752.     FOR i:=1 TO 100
  6753.       Club(i).Print
  6754.     ENDFOR i
  6755.  
  6756.     PersonPtr@.Input
  6757.  
  6758.  
  6759.   The scope of a method is the fields and the other methods inside the actual
  6760.   object.
  6761.  
  6762.  
  6763.   Example: The  scope of  Club(23).Print is the method Input and the fields
  6764.     FrstName$, LastName$, Address$, City$ and Age of Club(23).
  6765.  
  6766.  
  6767.   An object type is a true extension of  the data  structure STRUC  so that
  6768.   everything that  can be  done with  a data  structure can be done with an
  6769.   object type.
  6770.  
  6771.  
  6772.  
  6773.  
  6774.                                          119
  6775.  
  6776.  
  6777.  
  6778.  
  6779.  
  6780.   8.3 Inheritance.
  6781.  
  6782.   In the definition of an object type it is possible to inherit  fields and
  6783.   methods from  a previous defined object types. This is done by placing an
  6784.   INHERIT line in the start of the structure definition.
  6785.  
  6786.  
  6787.   Example:  In a school you have pupils and teachers. They are  all persons
  6788.     but have different additional properties. Pupils are members of a class
  6789.     and have parents, while the teachers teaches in  special subjects (like
  6790.     mathematics, computer sience, physics etc.) and they have their monthly
  6791.     salary.
  6792.  
  6793.     Two object types Pupil and Teacher can be defined in this way:
  6794.  
  6795.       STRUC Pupil
  6796.         INHERIT Person
  6797.  
  6798.         DIM Class OF BYTE
  6799.         DIM Mother$ OF 30
  6800.         DIM Father$ OF 30
  6801.  
  6802.         PROC Print
  6803.           Person.Print
  6804.           PRINT
  6805.           PRINT "Class:  ",Class
  6806.           PRINT "Mother: ",Mother$
  6807.           PRINT "Father: ",Father$
  6808.         ENDPROC Print
  6809.  
  6810.       ENDSTRUC Pupil
  6811.  
  6812.       STRUC Teacher
  6813.         INHERIT Person
  6814.  
  6815.         DIM Subject OF UBYTE
  6816.         DIM Salary OF FLOAT
  6817.  
  6818.         PROC Print
  6819.           Person.Print
  6820.           PRINT
  6821.           PRINT "Subject: ",Subject
  6822.           PRINT "Salary:  ",Salary
  6823.         ENDPROC Print
  6824.  
  6825.       ENDSTRUC Teacher
  6826.  
  6827.  
  6828.   All the fields and all the methods of the inherited are accessible from the
  6829.   descendant object type and from the outside world as if they were directly
  6830.  
  6831.                                          120
  6832.  
  6833.  
  6834.  
  6835.  
  6836.  
  6837.   defined in this object type. If a method in the descendant object has the
  6838.   same name as a method in the ancestor object, the child method will over-
  6839.   load the method in the ancestor object. This is the  case with  the Print
  6840.   method in  the example.  The overloaded  method may  be accessed by using
  6841.   the dot notation.
  6842.  
  6843.  
  6844.   Example: A general stack type can be made in this way:
  6845.  
  6846.       STRUC Stack
  6847.         DIM StackTop OF NodePtr
  6848.  
  6849.         PROC Push(REF Element OF NodePtr)
  6850.           Element@.Next:=StackTop
  6851.           StackTop:=Element
  6852.         ENDPROC Push
  6853.  
  6854.         PROC Pop(REF Element OF NodePtr)
  6855.           Element:=StackTop
  6856.           IF StackTop<>0 THEN
  6857.             StackTop:=StackTop@.Next
  6858.         ENDPROC
  6859.       ENDSTRUC Stack
  6860.  
  6861.       STRUC StackNode
  6862.         DIM Next OF POINTER TO StackNode
  6863.       ENDSTRUC StackNode
  6864.  
  6865.       TYPE NodePtr=POINTER TO StackNode
  6866.  
  6867.  
  6868.     To store a someting on the stack, for example a long integer, we can de-
  6869.     fine a NumberNode:
  6870.  
  6871.       STRUC NumberNode
  6872.         INHERIT StackNode
  6873.         DIM Num OF LONG
  6874.       ENDSTRUC NumberNode
  6875.  
  6876.     and then execute statements like:
  6877.  
  6878.       DIM Stack OF Stack
  6879.       DIM NumPtr OF POINTER TO NumberNode
  6880.  
  6881.       ALLOCATE(NumPtr)
  6882.       Stack.Pusk(NumPtr)
  6883.  
  6884.     The elements  of the  stack need not all be of the same type. They only
  6885.     need to be objects that are descendants of the StackNode object.
  6886.  
  6887.  
  6888.                                          121
  6889.  
  6890.  
  6891.  
  6892.  
  6893.  
  6894.  
  6895.   A structure A is assignment compatible to a structure B, i.e. an assignment
  6896.   of the form A:=B can be made, if A and B have the same type or if A's ty-
  6897.   pe is the ancestor of B's  type. That's  why the  variable NumPtr  in the
  6898.   example can  be used as the actual parameter to the formal parameter Ele-
  6899.   ment in the method Push.
  6900.  
  6901.  
  6902.   8.4 Virtual methods.
  6903.  
  6904.   If the Print method was called from the Input method in the  Pupil object
  6905.   in the section 9.3, it would have been the ancestors Print method, i.e. the
  6906.   fields of the descendant (Class, Mother$ and Father$) would not be printed.
  6907.  
  6908.   It is possible to force the system to call the method of the youngest des-
  6909.   cendant (if any) by specifying the method as virtual. A virtual method is
  6910.   defined by using a procedure/function head of the form:
  6911.  
  6912.     PROC func_name[(formal_parameter_list)] VIRTUAL
  6913.  
  6914.   or 
  6915.  
  6916.     FUNC func_name[(formal_parameter_list)] [OF NumType] VIRTUAL
  6917.  
  6918.   Example: This example shows a definition of different figures constituing a
  6919.     class hierarchy. The point is the base figure. The circle and the ractangle
  6920.     shares proporties with this but each one has its own characteristics:
  6921.  
  6922.     STRUC Point
  6923.       USE Graphics
  6924.  
  6925.       DIM PosX OF FLOAT, PosY OF FLOAT
  6926.       DIM FigureColor OF BYTE
  6927.  
  6928.       PROC Init(x,y,Color OF BYTE)
  6929.         PosX:=x; PosY:=y
  6930.         FigureColor:=Color
  6931.         pencolor(FigureColor)
  6932.         moveto(x,y)
  6933.         Draw
  6934.       ENDPROC Init
  6935.  
  6936.       PROC Move(dx,dy)
  6937.         pencolor(0)
  6938.         moveto(PosX,PosY)
  6939.         Draw
  6940.         pencolor(FigureColor)
  6941.         PosX:+dx; PosY:+dy
  6942.         moveto(PosX,PosY)
  6943.         Draw
  6944.  
  6945.                                          122
  6946.  
  6947.  
  6948.  
  6949.  
  6950.  
  6951.       ENDPROC Move
  6952.  
  6953.       PROC Draw VIRTUAL   // Virtual method
  6954.         plot(PosX,PosY)   // Defines the form of the figure
  6955.       ENDPROC Draw
  6956.  
  6957.     ENDSTRUC Point
  6958.  
  6959.     STRUC Circle
  6960.       INHERIT Point
  6961.  
  6962.       USE Graphics
  6963.  
  6964.       DIM Radius OF FLOAT
  6965.  
  6966.       PROC Init(x,y,Color OF BYTE,R)
  6967.         Radius:=R
  6968.         Point.Init(x,y,Color)
  6969.       ENDPROC Init
  6970.  
  6971.       PROC Draw
  6972.         circle(PosX,PosY,Radius)
  6973.       ENDPROC Draw
  6974.     ENDSTRUC Circle
  6975.  
  6976.     STRUC Rectangle
  6977.       INHERIT Point
  6978.  
  6979.       USE Graphics
  6980.  
  6981.       DIM Height OF FLOAT, Width OF FLOAT
  6982.  
  6983.       PROC Init(x,y,Color OF BYTE,h,w)
  6984.         Height:=h
  6985.         Width:=w
  6986.         Point.Init(x,y,Color)
  6987.       ENDPROC Init
  6988.  
  6989.       PROC Draw
  6990.         draw(Width,0)
  6991.         draw(0,Height)
  6992.         draw(-Width,0)
  6993.         draw(0,-Height)
  6994.       ENDPROC Draw
  6995.  
  6996.     ENDSTRUC Rectangle
  6997.  
  6998.  
  6999.     STRUC Square
  7000.       INHERIT Rectangle
  7001.  
  7002.                                          123
  7003.  
  7004.  
  7005.  
  7006.  
  7007.  
  7008.  
  7009.       PROC Init(x,y,Color OF BYTE,s)
  7010.         Rectangle.Init(x,y,Color,s,s)
  7011.       ENDPROC Init
  7012.  
  7013.     ENDSTRUC Square
  7014.  
  7015.  
  7016.   If you are using pointers to structures containing virtual methods it may be
  7017.   necessary to store a method table in the data field of the structure. You
  7018.   have to tell Comal that you want this table by using the line
  7019.  
  7020.     METHODTABLE
  7021.  
  7022.   in the start of the structure.
  7023.  
  7024.  
  7025.   Example: This structure is the ScreenClass defined in the module CITScreen:
  7026.  
  7027.  
  7028.     STRUC ScreenClass
  7029.       METHODTABLE
  7030.  
  7031.       FUNC CreateObject(REF Screen OF Screen) OF SHORT VIRTUAL
  7032.         RETURN TRUE
  7033.       ENDFUNC CreateObject
  7034.  
  7035.       PROC DeleteObject(REF Screen OF Screen) VIRTUAL
  7036.       ENDPROC DeleteObject
  7037.  
  7038.     ENDSTRUC ScreenClass
  7039.  
  7040.  
  7041.  
  7042.   NOTE: If a method table is stored in the  data field  you cannot  use the
  7043.   structure in a call to an external (C programmed) routine (for instance a
  7044.   system routine).
  7045.  
  7046.  
  7047.   8.5 Constructors.
  7048.  
  7049.   Sometimes an object needs to be initialized before it can be used.
  7050.  
  7051.  
  7052.   Example:  One of the basic structures of the Amiga operating system is the
  7053.     List structure:
  7054.  
  7055.       STRUC List
  7056.         DIM lh_Head OF POINTER TO Node
  7057.         DIM lh_Tail OF POINTER TO Node
  7058.  
  7059.                                          124
  7060.  
  7061.  
  7062.  
  7063.  
  7064.  
  7065.         DIM lh_TailPred OF POINTER TO Node
  7066.         DIM lh_Type OF UBYTE
  7067.         DIM lh_pad OF UBYTE
  7068.       ENDSTRUC List
  7069.  
  7070.     which is a double ended list used to store nodes of the form:
  7071.  
  7072.       STRUC Node
  7073.         DIM ln_Succ OF POINTER TO Node
  7074.         DIM ln_Pred OF POINTER TO Node
  7075.         DIM ln_Type OF BYTE
  7076.         DIM ln_Pri OF BYTE
  7077.         DIM ln_Name OF ULONG
  7078.       ENDSTRUC Node
  7079.  
  7080.     Before the list can be used it has to be initialized to an empty list by
  7081.     executing statements like:
  7082.  
  7083.       lh_Head:=ADR(lh_Tail)
  7084.       lh_TailPred:=ADR(lh_Head)
  7085.       lh_Tail:=0
  7086.  
  7087.  
  7088.   If the initiatization of an object does not require parameters (like the ini-
  7089.   tialization of List in the example) it can be put into a method that is de-
  7090.   clared as a constructor method. A constructor method  is a  method with a
  7091.   head of the form:
  7092.  
  7093.     FUNC func_name CONSTRUCTOR
  7094.  
  7095.  
  7096.   Such a method is called automatically when the object is created as a static
  7097.   variable in a DIM or LOCAL statement or is created as a  dynamic variable
  7098.   by executing the ALLOCATE procedure.
  7099.  
  7100.   A constructor returns a SHORT integer value to be considered as a boolean
  7101.   value. TRUE (=1) if the initialization succeded. FALSE (=0) otherwise.
  7102.  
  7103.   Example:  A smarter definition of the List object is the following:
  7104.  
  7105.       STRUC List
  7106.         DIM lh_Head OF POINTER TO Node
  7107.         DIM lh_Tail OF POINTER TO Node
  7108.         DIM lh_TailPred OF POINTER TO Node
  7109.         DIM lh_Type OF UBYTE
  7110.         DIM lh_pad OF UBYTE
  7111.  
  7112.         FUNC New CONSTRUCTOR
  7113.           lh_Head:=ADR(lh_Tail)
  7114.           lh_TailPred:=ADR(lh_Head)
  7115.  
  7116.                                          125
  7117.  
  7118.  
  7119.  
  7120.  
  7121.  
  7122.           lh_Tail:=0
  7123.           RETURN TRUE
  7124.         ENDFUNC New
  7125.  
  7126.       ENDSTRUC List
  7127.  
  7128.     The List in the module ExecLists  found in  the directory SystemModules
  7129.     is defined in this way.
  7130.  
  7131.  
  7132.   If a field is an object containing a constructor this constructor is called,
  7133.   too. If an object  inherits other  objects all  the ancestors constructor
  7134.   methods are called when an object of that type is created. But you should
  7135.   note that the virtual method calling mechanism does  not function  at the
  7136.   initialization time (the descendants are not initialized until after all the
  7137.   ancestors have been initialized).
  7138.  
  7139.   If a constructor returns FALSE, all the destructors (see next section) of
  7140.   the sub objects (fields or inherited objects) that has been successfully ini-
  7141.   tialized, will be called.
  7142.  
  7143.  
  7144.  
  7145.   8.6 Destructors.
  7146.  
  7147.   If an object needs to do some cleaning up before its data fields are remo-
  7148.   ved you  can declare  a method  as a destructor. A destructor method is a
  7149.   method of the form:
  7150.  
  7151.     PROC proc_name DESTRUCTOR
  7152.  
  7153.  
  7154.   Such a  method is  called whenever  the memory  used by  the objects data
  7155.   field is  removed. This  will be the case if DEALLOCATE is called or at a
  7156.   return from a procedure or function (if the object is a local variable). But
  7157.   a constructor may also be called when all the variables are cleared, i.e af-
  7158.   ter the program has stopped!
  7159.  
  7160.   Because destructors are called in many different sitiuations a destructor
  7161.   method should be as short as possible, it should do no IO and it should be
  7162.   free of errors!
  7163.  
  7164.   The best way to develop constructors is to  first activate  them manually
  7165.   (leave  out  the  word  CONSTRUCTOR).  Then, when you think it works, add
  7166.   the word CONSTRUCTOR.
  7167.  
  7168.  
  7169.   Example: One of the basic elements of the  Amiga multy  tasking system is
  7170.     the message  port. A message port consists of a list node (such that it
  7171.     can be put into the list of public ports if desired) and some fields.
  7172.  
  7173.                                          126
  7174.  
  7175.  
  7176.  
  7177.  
  7178.  
  7179.  
  7180.     One of the fields contains the number of a signal bit that has to be allo-
  7181.     cated when  the port  is created  and it has to be deallocated when the
  7182.     port is removed. Another field is a list where messages  can be placed.
  7183.     Also this has to be initialized.
  7184.  
  7185.     The alocation of a signal bit can be done in a constructor and the deal-
  7186.     location in a destructor. A message port can be defined in this way:
  7187.  
  7188.       STRUC MsgPort
  7189.         INHERIT Node
  7190.  
  7191.         USE ExecLibrary
  7192.         USE ExecLists
  7193.  
  7194.         DIM mp_Flags OF UBYTE
  7195.         DIM mp_SigBit OF BYTE
  7196.         DIM mp_SigTask OF ULONG
  7197.         DIM mp_MsgList OF List
  7198.  
  7199.         FUNC Init CONSTRUCTOR
  7200.           ln_Type:=NT_MSGPORT
  7201.           mp_SigTask:=FindTask($0)
  7202.           mp_SigBit:=AllocSignal(-1)
  7203.           RETURN mp_SigBit>=0         // No signals if mp_SigBit<0
  7204.         ENDFUNC Init
  7205.  
  7206.         PROC Delete DESTRUCTOR
  7207.           IF ln_Name<>0 THEN
  7208.             RemPort(ADR(Node))
  7209.             ln_Name:=0
  7210.           ENDIF
  7211.           IF mp_SigBit>=0 THEN
  7212.             FreeSignal(mp_SigBit)
  7213.           ENDIF
  7214.         ENDPROC Delete
  7215.  
  7216.       ENDSTRUC MsgPort
  7217.  
  7218.     Note that the list mp_MsgList is not initialized in the constructor shown.
  7219.     But this list is imported from the module ExecLists and the list in this
  7220.     moule contains a constructor that will do the initialization.
  7221.  
  7222.  
  7223.  
  7224.   9 Modules.
  7225.  
  7226.   A module is a  program structure  used to  devide a  program into smaller
  7227.   parts. A module contains variables, procedures, functions and type defini-
  7228.   tions that can be use outside the module.
  7229.  
  7230.                                          127
  7231.  
  7232.  
  7233.  
  7234.  
  7235.  
  7236.  
  7237.  
  7238.   9.1 Making modules.
  7239.  
  7240.   A module has the form:
  7241.  
  7242.     MODULE ModuleName
  7243.  
  7244.       [USE statements]
  7245.  
  7246.       [EXPORT statements]
  7247.  
  7248.       <normal program lines>
  7249.  
  7250.     ENDMODULE ModuleName
  7251.  
  7252.  
  7253.   Example:
  7254.  
  7255.       MODULE Hyperbolic
  7256.  
  7257.         EXPORT sinh,cosh
  7258.  
  7259.         FUNC sinh(x)
  7260.           RETURN (EXP(x)-EXP(-x))/2
  7261.         ENDFUNC sinh
  7262.  
  7263.         FUNC cosh(x)
  7264.           RETURN (EXP(x)+EXP(-x))/2
  7265.         ENDFUNC cosh
  7266.  
  7267.       ENDMODULE Hyperbolic
  7268.  
  7269.  
  7270.   All procedures, functions and variables are strictly local to the module. On-
  7271.   ly those  names that  are exported  in EXPORT statements can be used out-
  7272.   side the module. An EXPORT statement has the form:
  7273.  
  7274.     EXPORT ExportList
  7275.  
  7276.   where ExportList is one or more of the following separated by commas (,):
  7277.  
  7278.     Identifier [AS ExportName]
  7279.  
  7280.  
  7281.   If the AS part is present the ExportName is used in references to the ex-
  7282.   ported element. Otherwise it is referenced by the name used inside the mo-
  7283.   dule itself.
  7284.  
  7285.  
  7286.  
  7287.                                          128
  7288.  
  7289.  
  7290.  
  7291.  
  7292.  
  7293.   Example: If the EXPORT statement in the previous example is changed to
  7294.  
  7295.       EXPORT sinh,sinh AS SINH,cosh,cosh AS COSH
  7296.  
  7297.     both sinh and SINH can be used to refer to the sinh function (and similar
  7298.     for cosh).
  7299.  
  7300.  
  7301.   It is possible to export names that are imported from other modules. This is
  7302.   called re-export.
  7303.  
  7304.   A module can be placed in the program that uses the module (local module)
  7305.   or it can be placed in a separate disk file (external modules). There is no
  7306.   limit to the number of modules that can be placed  in a  program or  in a
  7307.   disk file.
  7308.  
  7309.   An external module is best made by first make it as a local module. Then,
  7310.   when you think it works, store it on disk in code form  (open a  new pro-
  7311.   ject, use  the clipboard  to move  the module to the new project and then
  7312.   save the module using the Save item in the Program menu).
  7313.  
  7314.  
  7315.  
  7316.   9.2 Using modules.
  7317.  
  7318.   The exported names in a module (including type names) are made accessible
  7319.   by a USE statement. A USE statement has form:
  7320.  
  7321.     USE ModuleName [FROM FileName]
  7322.  
  7323.  
  7324.   Example:
  7325.  
  7326.     USE System
  7327.     USE Hyperbolic FROM MathModule
  7328.  
  7329.  
  7330.   All USE  statements are  executed at the scanning time. If the USE state-
  7331.   ment is used without the FROM part the system searches for the  module in
  7332.   the following way:
  7333.  
  7334.     1. among the local modules
  7335.     2. in a file Comal:Modules/ModuleName.mod (if it exists)
  7336.     3. in a file Comal:SystemModules/ModuleName.mod (if it exists)
  7337.     4. in a file Comal:Modules/ModuleName (mashine coded module)
  7338.     5. in a file Comal:SystemModules/ModuleName (mashine coded module)
  7339.  
  7340.  
  7341.   If the file in 2. or 3. is found there must be one module by name Module-
  7342.   Name in this file.
  7343.  
  7344.                                          129
  7345.  
  7346.  
  7347.  
  7348.  
  7349.  
  7350.  
  7351.   If the second form of the USE statement is used, the specified file is loa-
  7352.   ded and  if it  is a Comal module (.mod file) there must be one module by
  7353.   name ModuleName in this file.
  7354.  
  7355.   A USE statement can be placed in a program, in an object, in a closed pro-
  7356.   cedure or function or in a module, and all the type names and all the ex-
  7357.   ported names in the module used can be accessed in  the scope  of the USE
  7358.   statement.
  7359.  
  7360.  
  7361.   9.3 Signal procedures.
  7362.  
  7363.   It is  possible to  make the module recieve messages about changes in the
  7364.   system. These messages are send as signal numbers to a procedure declared
  7365.   as a signal procedure.
  7366.  
  7367.   The head of a signal procedure has the form:
  7368.  
  7369.     PROC ProcName(Sig OF LONG) SIGNAL
  7370.  
  7371.  
  7372.   Example:
  7373.  
  7374.       PROC Signal(s OF LONG) SIGNAL
  7375.         CASE s OF
  7376.         WHEN SIG_DISCARD
  7377.           CleanUp
  7378.         OTHERWISE
  7379.           // No action
  7380.         ENDCASE
  7381.       ENDPROC Signal
  7382.  
  7383.  
  7384.   The signal numbers send and their meanings are:
  7385.  
  7386.     SIG_CLOSE (1)       send if interpreter is going to close
  7387.     SIG_DISCARD (2)     send if the module is being removed
  7388.     SIG_CLEAR (3)       send if all variables in main program are cleared
  7389.     SIG_RUN (4)         send before execution starts
  7390.     SIG_STOP (5)        send at program stop that can be continued
  7391.     SIG_END (6)         send at program stop that cannot be continued
  7392.     SIG_STARTTRACE (7)  send at change to trace mode
  7393.     SIG_STOPTRACE (8)   send if trace mode ends
  7394.     SIG_STEP (9)        send if a step is executed in trace mode
  7395.     SIG_CONTINUE (10)   send if program execution continues after stop
  7396.  
  7397.  
  7398.   The symbolic names used are defined in the System module.
  7399.  
  7400.  
  7401.                                          130
  7402.  
  7403.  
  7404.  
  7405.  
  7406.  
  7407.   NOTE! Signal  numbers send to a module should not be confused with signal
  7408.   numbers used in the Amiga operating system.
  7409.  
  7410.  
  7411.  
  7412.   10 Description of the standard modules.
  7413.  
  7414.   In the directory SystemModules a number of useful modules are  found. The
  7415.   content of some of these modules will be described in this section.
  7416.  
  7417.  
  7418.   10.1 The System modules.
  7419.  
  7420.   As is the case with other implementations of Comal the system module con-
  7421.   tains implementation dependent stuff.  In this  implementation the system
  7422.   module is  devided into two parts: A module written in Comal by name Sys-
  7423.   tem, and a machine coded module by name SystemCode.
  7424.  
  7425.  
  7426.   10.1.1 SystemCode.
  7427.  
  7428.   This module contains the following procedures and functions:
  7429.  
  7430.  
  7431.     FUNC ComalStrucAdr OF ULONG
  7432.  
  7433.       Returns the address of the ComalStruc (see description  of the System
  7434.       module in next section).
  7435.  
  7436.  
  7437.     FUNC CharArrayToString$(Array OF ULONG)
  7438.  
  7439.       Converts a null terminated array of characters into a Comal string.
  7440.  
  7441.  
  7442.     FUNC ComalWait(SignalMask OF ULONG) OF ULONG
  7443.  
  7444.       This function is used like the function Wait in the Exec library of the
  7445.       Amiga operating system.
  7446.  
  7447.       The function OR's all the Comal signals to the actual parameter Signal-
  7448.       Mask and  then calls  Wait. Among  other things this means that it is
  7449.       possible to break a Comal program that has called ComalWait (this can-
  7450.       not be done if Wait is called!)
  7451.  
  7452.       The return value is a mask containing the signals that caused the re-
  7453.       turn (and this may be one of the Comal signals).
  7454.  
  7455.  
  7456.  
  7457.  
  7458.                                          131
  7459.  
  7460.  
  7461.  
  7462.  
  7463.  
  7464.     FUNC SysLibVersion OF USHORT
  7465.  
  7466.       Returns the current version of your system.
  7467.  
  7468.  
  7469.     FUNC LockComalWindow OF ULONG
  7470.  
  7471.       Get a shared lock for the standard IO window. The  return value  is a
  7472.       pointer to the standard IO window.
  7473.  
  7474.  
  7475.     PROC UnlockComalWindow
  7476.  
  7477.       Call this  procedure when  the pointer returned by LockComalWindow is
  7478.       not needed any longer.
  7479.  
  7480.  
  7481.     PROC AddSignal(SigMask OF ULONG)
  7482.  
  7483.       Call this routine if you want one or more signals to be a Comal signal.
  7484.       The arrival  of a Comal signal will cause ComalWait to return and the
  7485.       sleep state started by the WAIT statement (see sectio 7.2) will be ter-
  7486.       minated. The actual parameter is a mask of signals.
  7487.  
  7488.  
  7489.     PROC RemSignal(SigMask OF ULONG)
  7490.  
  7491.       Removes a Comal signal added by AddSignal.
  7492.  
  7493.  
  7494.     PROC AddComalDevice(IoDevice OF ULONG)
  7495.  
  7496.       Call this procedure if you want to add a new IO device to the list of
  7497.       standard devices (like "ds:", "kb:" and "lp:"). The actual parameter must
  7498.       be a pointer to an initialized device structure.
  7499.  
  7500.  
  7501.     PROC RemComalDevice(IoDevice OF ULONG)
  7502.  
  7503.       Call this with a pointer to the IO device you want to remove from the
  7504.       list of IO devices.
  7505.  
  7506.  
  7507.     PROC AddExcept(ExceptStruc OF ULONG)
  7508.  
  7509.       Call this procedure if you want to add an exception routine to the list
  7510.       of exception  routines. The  actual parameter must be a pointer to an
  7511.       initialized exception structure.
  7512.  
  7513.  
  7514.  
  7515.                                          132
  7516.  
  7517.  
  7518.  
  7519.  
  7520.  
  7521.     PROC RemExcept(ExceptStruc OF ULONG)
  7522.  
  7523.       Call this with a pointer to the exception structure you want to remove
  7524.       from the list of exception routines.
  7525.  
  7526.  
  7527.   Although it  is possible to use a Comal procedure as an exception routine
  7528.   the last two routines are normally not used from Comal. Use the procedures
  7529.   ADDINTERRUPT and REMINTERRUPT in stead (see section 7.5).
  7530.  
  7531.  
  7532.   10.1.2 System.
  7533.  
  7534.   The System  module uses  the SystemCode  module from  where the functions
  7535.   CharArrayToString$ and ComalWait is re-exported. One routine is exported:
  7536.  
  7537.     FUNC ComalPath$
  7538.  
  7539.       Returns a string containing the complete path of your comal system.
  7540.  
  7541.  
  7542.   In this module the Comal structure is defined:
  7543.  
  7544.     STRUC ComalStruc
  7545.       DIM BreakFlags OF UBYTE
  7546.       DIM SecBreakFlags OF UBYTE
  7547.       DIM Flags OF USHORT
  7548.       DIM CurrWorkBottom OF POINTER TO UBYTE
  7549.       DIM CurrWorkTop OF POINTER TO UBYTE
  7550.       DIM MinStack OF POINTER TO UBYTE
  7551.       DIM IO_Screen OF POINTER TO Screen
  7552.       DIM CommPort OF POINTER TO MsgPort
  7553.       DIM AsciiId OF POINTER TO UBYTE
  7554.       DIM MainPrgBuf OF POINTER TO PrgBuf
  7555.       DIM PrgEnv OF POINTER TO PrgEnv
  7556.       DIM WorkStart OF ULONG
  7557.       DIM WorkEnd OF ULONG
  7558.       DIM WorkLength OF ULONG
  7559.       DIM SortTable OF POINTER TO UBYTE
  7560.       DIM ComalPath OF POINTER TO UBYTE
  7561.     ENDSTRUC ComalStruc
  7562.  
  7563.  
  7564.   Only a few fields are of interest for Comal programmers:
  7565.  
  7566.     IO_Screen
  7567.  
  7568.       A pointer to the screen where all windows should be placed. This poin-
  7569.       ter is non zero even if the screen is the Workbench screen.
  7570.  
  7571.  
  7572.                                          133
  7573.  
  7574.  
  7575.  
  7576.  
  7577.  
  7578.  
  7579.     CommPort
  7580.  
  7581.       If non zero this is a pointer to a message port allocated for you.
  7582.  
  7583.  
  7584.     AsciiId
  7585.  
  7586.       This is a pointer to a null terminated array of characters that identi-
  7587.       fies this interpreter process.
  7588.  
  7589.  
  7590.     SortTable
  7591.  
  7592.       This is a pointer to a table of sort values used when strings are com-
  7593.       pared. Normally it is filled with the ASCII values.
  7594.  
  7595.       It is  possible to change the content of the table (do not change the
  7596.       pointer itself!) with other sorting values.
  7597.  
  7598.       Example: By using this little code upper and lower case  letters will
  7599.         have the same sorting values:
  7600.  
  7601.           FOR i:=ORD("a") TO ORD("z") DO
  7602.             ComalStruc@.SortTable(i):=i-32
  7603.           ENDFOR i
  7604.  
  7605.  
  7606.     ComalPath
  7607.  
  7608.       This is a pointer to a null terminated string containing the complete
  7609.       path of your comal system.
  7610.  
  7611.  
  7612.   A pointer ComalStruc to the Comal structure is exported.
  7613.  
  7614.   The following useful types are defined in the module:
  7615.  
  7616.     TYPE BOOL=BYTE
  7617.     TYPE bool=BYTE
  7618.     TYPE WORD=SHORT
  7619.     TYPE word=SHORT
  7620.     TYPE UWORD=USHORT
  7621.     TYPE uword=USHORT
  7622.  
  7623.  
  7624.   The signal numbers SIG_CLOSE,  SIG_DISCARD  etc.  (see  section  9.3) and
  7625.   the memory  types MEMF_PUBLIC  etc. (see section 1.4) are defined and ex-
  7626.   ported from the module.
  7627.  
  7628.  
  7629.                                          134
  7630.  
  7631.  
  7632.  
  7633.  
  7634.  
  7635.  
  7636.   10.2 The graphics modules.
  7637.  
  7638.   Two graphics modules Graphics and Turtle can be used.
  7639.  
  7640.  
  7641.   10.2.1 Graphics.
  7642.  
  7643.   This module is compatibal with graphics modules (packages) found in other
  7644.   implementations  of  Comal  (UniComal  for  the  C64  and PC'c and Amiga-
  7645.   COMAL v. 2.x).
  7646.  
  7647.  
  7648.   The Graphics module contains:
  7649.  
  7650.  
  7651.     PROC arc(c1,c2,r,start_angle,arc)
  7652.  
  7653.       The procedure causes an arc to be drawn with its center at (c1,c2) and
  7654.       with a radius r. The arc has the length arc degrees starting with the
  7655.       angle start_angle.
  7656.  
  7657.       Exampel:
  7658.  
  7659.         arc(100,100,50,45,90)
  7660.         arc(x0,y0,r,v,2*v)
  7661.  
  7662.  
  7663.     PROC background(color)
  7664.  
  7665.       This procedure sets the back ground color to the value of the parame-
  7666.       ter color.
  7667.  
  7668.       Exampel:
  7669.  
  7670.         background(3) // Set back ground color to blue (red in WB 1.3)
  7671.  
  7672.  
  7673.     PROC circle(c1,c2,r)
  7674.  
  7675.       Draws a circle with its center at (c1,c2) and with radius r. The drawn
  7676.       figure will not be a round circle unless a suitable relation between the
  7677.       vertical and horizontal units has been chosen (window procedure).
  7678.     
  7679.       The current pen position is unchanged.
  7680.  
  7681.       Exampel:
  7682.  
  7683.         window(-160,160,-100,100)
  7684.         circle(0,0,50)              // Draw a "circular" circle.
  7685.  
  7686.                                          135
  7687.  
  7688.  
  7689.  
  7690.  
  7691.  
  7692.  
  7693.  
  7694.     PROC clear
  7695.  
  7696.       Clears the window inside the current drawing region set by the proce-
  7697.       dure clip.
  7698.  
  7699.  
  7700.     PROC clearscreen
  7701.  
  7702.       Clears the window inside the current viewport frame set by the proce-
  7703.       dure viewport.
  7704.  
  7705.  
  7706.     PROC clip(xmin,xmax,ymin,ymax)
  7707.  
  7708.       The procedure clip defines a working region expressed in window coor-
  7709.       dinates (se window procedure). All drawings (clear, fill, draw, ....) can-
  7710.       not be seen outside this region.
  7711.  
  7712.       Exampel:
  7713.  
  7714.         clip(2.5,4.7,-2,0)
  7715.         clip(0,cx,cy,cy+10)
  7716.  
  7717.  
  7718.     FUNC depth
  7719.  
  7720.       Function that returns the depth of the graphics window (the number of
  7721.       bitmaps in the window).
  7722.  
  7723.       If the depth is 2, there are four colors with numbers 0-3. The number
  7724.       of colors can always be calculated as
  7725.  
  7726.         colornumber:=2^depth
  7727.  
  7728.  
  7729.     PROC draw(x,y)
  7730.  
  7731.       Draws a  line from the current pen position (x0,y0) to the point with
  7732.       coordinates (x0+x,y0+y).
  7733.     
  7734.       The new pen position is the point with coordinates (x0+x,y0+y).
  7735.  
  7736.       Exampel:
  7737.  
  7738.         draw(0,100)  // Draws a vertical line of length 101
  7739.  
  7740.  
  7741.  
  7742.  
  7743.                                          136
  7744.  
  7745.  
  7746.  
  7747.  
  7748.  
  7749.     PROC drawto(x,y)
  7750.  
  7751.       Draws a line from the current pen position (x0,y0) to  the point with
  7752.       coordinates (x,y).
  7753.     
  7754.       The new pen position is the point with coordinates (x,y).
  7755.  
  7756.  
  7757.     PROC fill(x,y)
  7758.  
  7759.       Fills an area with the current pencolor. The area to be filled must con-
  7760.       tain the point (x,y) and be bounded by either a curve in a color diffe-
  7761.       rent from the background color or by the frame set by the clip.
  7762.     
  7763.       The current pen position is unchanged.
  7764.  
  7765.       Exampel:
  7766.         pencolor(1)
  7767.         circle(300,100,50)  // Draw a circle with pencolor 1
  7768.         pencolor(2)
  7769.         fill(300,100)       // .. and fill with pencolor 2
  7770.  
  7771.  
  7772.     FUNC getcolor(x,y)
  7773.  
  7774.       Return color of the point with coordinates (x,y).
  7775.     
  7776.       The current pen position is unchanged.
  7777.  
  7778.  
  7779.     FUNC getrgb(color_register)
  7780.  
  7781.       Returns the color of the specified color register. Written as a hexade-
  7782.       cimal number the content is of the form
  7783.  
  7784.         $0rgb
  7785.  
  7786.       where r, g and b are  the content  of the  red, green  and blue color
  7787.       (four bits for each color).
  7788.  
  7789.       If the graphics system is not opned the value -1 is returned.
  7790.              
  7791.  
  7792.     PROC graphicscreen(Window)
  7793.  
  7794.       Opens the graphics system. If the actual parameter is zero the standard
  7795.       IO-window will be used as the graphics window. If the parameter is non
  7796.       zero it  must be the address of a window and this window will be used
  7797.       as the graphics window.
  7798.  
  7799.  
  7800.                                          137
  7801.  
  7802.  
  7803.  
  7804.  
  7805.  
  7806.       This procedure must be called before any of the graphics routines are
  7807.       called. When  the graphics  system is opned the command window or the
  7808.       graphics window may be brought in front by pressing <Shift>+<F1>.
  7809.       
  7810.  
  7811.     FUNC height
  7812.  
  7813.       Returns the height of the graphics window in pixels
  7814.     
  7815.  
  7816.     FUNC inq(no)
  7817.  
  7818.       The function inq returns certain of the internal variable of the gra-
  7819.       phics system. The parameter no must be an integral number in the ran-
  7820.       ge 0-33. The meaning of the returned value can be found in the follo-
  7821.       wing table:
  7822.  
  7823.       number    information about     range     Affected by
  7824.         0       graphics mode         0/1       graphicscreen
  7825.         1
  7826.         2       text background       0-        textbackground
  7827.         3       text color            0-        pencolor
  7828.         4
  7829.         5       graphics backgruond   0-        background
  7830.         6       pen color             0-        pencolor
  7831.         7       graphics text width   8/10      textstyle
  7832.         8       graphics text height  8/10      textstyle
  7833.         9       gr. text direction    0         (dir. cannot be changed)
  7834.        10       graphics text mode    0/1       textstyle
  7835.        11
  7836.        12       pen inside dr. frame  0/1       most drawing procs
  7837.        13                             1
  7838.        14                             0
  7839.        15       wrapping active       0         (wrap not implemented)
  7840.        16       pen down              1         only changed in Turtle
  7841.        17       x-position            0-width   most drawing procs
  7842.        18       y-position            0-height  most drawing procs
  7843.        19       viewport xmin         0-width   viewport
  7844.        20       viewport xmax         0-width   viewport
  7845.        21       viewport ymin         0-height  viewport
  7846.        22       viewport ymax         0-height  viewport
  7847.        23       vindow xmin           real no.  window
  7848.        24       vindow xmax           real no.  window
  7849.        25       vindow ymin           real no.  window
  7850.        26       vindow ymax           real no.  window
  7851.        27                             1
  7852.        28                             0
  7853.        29                             0
  7854.        30       x-ratio               (rem. 1)  window and viewport
  7855.        31       y-ratio               (rem. 2)  window and viewport
  7856.  
  7857.                                          138
  7858.  
  7859.  
  7860.  
  7861.  
  7862.  
  7863.        32                             0
  7864.        33                             0
  7865.  
  7866.       remark 1: (wdxmax-wdxmin)/(vpxmax-vpxmin)
  7867.       remark 2: (wdymax-wdymin)/(vpymax-vpymin)
  7868.  
  7869.  
  7870.     PROC interiorcolor(color)
  7871.  
  7872.       Subsequent calls to the procedure polygon uses the parameter color to
  7873.       fill out the interior of the polygon.
  7874.  
  7875.       Exampel:
  7876.  
  7877.         interiorcolor(2)    // Fill with black
  7878.         interiorcolor(-1)   // No filling
  7879.  
  7880.  
  7881.     PROC loadscreen(name$)
  7882.  
  7883.       The procedure causes an ILBM-picture previous stored by  Comal (save-
  7884.       screen and  SaveWindow procedures) or by another program (like DeLuxe
  7885.       Paint) to be fetched from disk and placed in the graphics window.
  7886.  
  7887.       Exampel:
  7888.  
  7889.         loadscreen("MandelBrot.ilbm")
  7890.  
  7891.  
  7892.     PROC move(x,y)
  7893.  
  7894.       Moves witout drawing the pen from the current position (x0,y0) to the
  7895.       point with coordinates (x0+x,y0+y).
  7896.  
  7897.  
  7898.     PROC moveto(x,y)
  7899.  
  7900.       Moves witout drawing the pen to the point with coordinates (x,y).
  7901.  
  7902.  
  7903.     PROC noclip
  7904.  
  7905.       The procedure cancels any previously defined clip working region (set
  7906.       by the procedure clip) and restores the working region to the current
  7907.       viewport (set by the procedure viewport).
  7908.  
  7909.  
  7910.     PROC outlinecolor(color)
  7911.  
  7912.       Subsequent calls to the procedure polygon uses the parameter color as
  7913.  
  7914.                                          139
  7915.  
  7916.  
  7917.  
  7918.  
  7919.  
  7920.       the color of the edges of the polygon.
  7921.  
  7922.       Exampel:
  7923.  
  7924.         outlinecolor(3)   // Draw polygon with edges in pencolor 3
  7925.  
  7926.     PROC paint(x,y)
  7927.  
  7928.       The procedure causes a region to be filled in with the current pencolor.
  7929.       The region  to be  filled must contain the point (x,y) and it must be
  7930.       limited by the pencolor or the viewport drawing area.
  7931.     
  7932.       The current pen position is unchanged.
  7933.     
  7934.       Exampel:
  7935.  
  7936.         pencolor(1)
  7937.         moveto(0,0)
  7938.         drawto(500,150)     // Draw a black (white in WB 1.3) line
  7939.         pencolor(3)
  7940.         circle(300,100,50)  // .. a red circle
  7941.         paint(300,100)      // .. and fill the circle with blue color
  7942.  
  7943.  
  7944.     PROC palette(no)
  7945.  
  7946.       The procedure is used to set  the first  four colors  of the graphics
  7947.       screen. The colors are selected from one of three palettes:
  7948.      
  7949.         palette   color 0   color 1   color 2   color 3
  7950.         
  7951.            0       black     green      red      yellow
  7952.            1       black     magenta    cyan     white
  7953.  
  7954.       palette(-1) restores the colors to the original values.
  7955.      
  7956.       Note that  if the graphics window is placed in the IO-window (this is
  7957.       the case if the procedure graphicscreen is called with a zero as para-
  7958.       meter) all the Comal windows will change colors. The proceudre is im-
  7959.       plemented to insure compatibility with UniComals graphics module. Nor-
  7960.       mally the more general procedure setrgb should be used.
  7961.  
  7962.  
  7963.     FUNC pencolor(color)
  7964.  
  7965.       Procedure used to set the color of the pen.
  7966.  
  7967.  
  7968.  
  7969.  
  7970.  
  7971.                                          140
  7972.  
  7973.  
  7974.  
  7975.  
  7976.  
  7977.     FUNC pixelx
  7978.  
  7979.       The function returns the width of a picture element (a pixel) expressed
  7980.       in the current window units.
  7981.  
  7982.       Exampel:
  7983.         draw(2*pixelx,0)
  7984.  
  7985.  
  7986.     FUNC pixely
  7987.  
  7988.       The function returns the height of a picture element (a pixel) expressed
  7989.       in the current window units.
  7990.  
  7991.       Exampel:
  7992.  
  7993.         draw(0,pixely)
  7994.  
  7995.  
  7996.     PROCEDURE plot(x,y)
  7997.  
  7998.       The procedure places a dot at the point with coordinates (x,y).
  7999.  
  8000.       The current pen position is unchanged.
  8001.  
  8002.  
  8003.     PROC plottext(x,y,text$)
  8004.  
  8005.       The procedure causes text$ to be written in the graphics window star-
  8006.       ting at the point with coordinates (x,y).
  8007.  
  8008.       The current pen position is unchanged.
  8009.  
  8010.       Exampel:
  8011.  
  8012.         plottext(100,150,"Comal")
  8013.  
  8014.  
  8015.     PROC polygon(corners, REF x(), REF y())
  8016.  
  8017.       The procedure causes a polygon with corners vertices to be drawn. The
  8018.       coordinates of the vertices are stored in the vectors x() and y().
  8019.     
  8020.       The number of elements must be at least the value of corners.
  8021.     
  8022.       The edges (the perimeter) of the polygon is drawn in the color set by
  8023.       the procedure outlinecolor and the color of the inner region is set by
  8024.       the procedure interiorcolor (unless the interiorcolor is set to the value
  8025.       -1 in which case a transparent polygon will be drawn).
  8026.  
  8027.  
  8028.                                          141
  8029.  
  8030.  
  8031.  
  8032.  
  8033.  
  8034.       Exampel:
  8035.  
  8036.         DIM x(3), y(3)
  8037.         READ x(),y()
  8038.         interiorcolor(3)
  8039.         outlinecolor(2)
  8040.         polygon(3,x(),y()) // Draw a triangle in color 3 with edges in color 2
  8041.         DATA 150,300,450
  8042.         DATA 20,150,20
  8043.  
  8044.       NOTE: The procedure uses a routine in the Amiga graphics  library. It
  8045.       seems as  if this  procedure has a bug. If the corners of the polygon
  8046.       falls outside the graphics window the system may crash (the well known
  8047.       GURU will visit you!).
  8048.  
  8049.  
  8050.     PROC printscreen
  8051.  
  8052.       The procedure  transfers the  content of  the graphics  window to the
  8053.       printer.
  8054.  
  8055.  
  8056.     PROC savescreen(name$)
  8057.  
  8058.       The procedure causes the content of the graphics  window to  be saved
  8059.       on disk in ILBM format.
  8060.     
  8061.       Exampel:
  8062.  
  8063.         savescreen("MandelBrot.ilbm")
  8064.  
  8065.  
  8066.     PROC SaveWindow(name$,mode)
  8067.  
  8068.       The procedure  works as  savescreen above  if the  parameter mode has
  8069.       the value 0. If mode has the value 1 the window is saved in compressed
  8070.       form (using  the ByteRun1 compressing algorithm). This may reduce the
  8071.       size significantly.
  8072.  
  8073.       Exampel:
  8074.         SaveWindow("Mandelbrot.ilbm",1)
  8075.  
  8076.  
  8077.     PROC setrgb(color_register,red,green,blue)
  8078.  
  8079.       This procedure is used to set the amount of red, green and blue in the
  8080.       specified color register. The color_register is an integral number in the
  8081.       range 0-31 (this number is directly asociated to the color number used
  8082.       by the procedures pencolor, backcolor etc.) and the amount of color is
  8083.       an integral number in the range 0-15.
  8084.  
  8085.                                          142
  8086.  
  8087.  
  8088.  
  8089.  
  8090.  
  8091.  
  8092.       Exampel: After the call
  8093.        
  8094.           setrgb(1,15,0,15)
  8095.         
  8096.         color number 1 (set by pencolor procedure) has the color magenta.
  8097.        
  8098.       The colors of all the color registers may be restore to their original
  8099.       value by palette(-1).
  8100.  
  8101.  
  8102.     PROC TextAttr(attr)
  8103.  
  8104.       The procedure  defines the manner in which the printout from the pro-
  8105.       cedure TextAttr will appear on the graphics window.
  8106.  
  8107.       The following values may be used for the parameter attr:
  8108.  
  8109.          0  normal text
  8110.          1  bold
  8111.          2  italic
  8112.          4  underlined
  8113.          8  inverse
  8114.         16  only text (no background)
  8115.  
  8116.       More values can be set by adding the values.
  8117.  
  8118.       Exampel:
  8119.         TextAttr(1+2) // Print in bold and italic
  8120.  
  8121.  
  8122.     PROC textbackground(color)
  8123.  
  8124.       The procedure is used to set the background color used by the plottext
  8125.       procedure (see also textstyle).
  8126.  
  8127.  
  8128.     PROC textscreen
  8129.  
  8130.       Closes the graphics system.
  8131.  
  8132.  
  8133.     PROC textstyle(width#,height#,direction#,mode#)
  8134.  
  8135.       The proceudre  is implemented  to insure compatibility with UniComals
  8136.       graphics module and only the last parameter is significant. The meaning
  8137.       of this is:
  8138.  
  8139.          0  print without background
  8140.          1  print with background (as attr=16 in TextAttr above)
  8141.  
  8142.                                          143
  8143.  
  8144.  
  8145.  
  8146.  
  8147.  
  8148.  
  8149.  
  8150.     PROC viewport(xmin,xmax,ymin,ymax)
  8151.  
  8152.       Defines a  region of  the graphics  window in which all drawings take
  8153.       place. The parameters refer to the physical window (pixel coordinates).
  8154.  
  8155.  
  8156.     PROC viewport_to_window(vpx, vpy, REF wdx, REF wdy)
  8157.  
  8158.       The procedure maps the viewport coordinates (the physical  window co-
  8159.       ordinates) to the window coordinates (set by the window procedure).
  8160.  
  8161.  
  8162.     FUNC width
  8163.  
  8164.       The function returns the width of the graphics window in pixels.
  8165.  
  8166.  
  8167.     PROC window(xmin,xmax,ymin,ymax)
  8168.  
  8169.       The procedure defines a coordinate system in the current viewport. The
  8170.       parameter defines new coordinates for the border of the viewport.
  8171.  
  8172.  
  8173.     PROC window_to_viewport(wdx, wdy, REF vpx#, REF vpy#)
  8174.  
  8175.       The procedure converts window coordinates to  physical window coordi-
  8176.       nates (pixel coordinates).
  8177.  
  8178.  
  8179.     FUNC xcor
  8180.  
  8181.       The function returns the current x-coordinate of the pen.
  8182.  
  8183.  
  8184.     FUNC ycor
  8185.  
  8186.       The function returns the current y-coordinate of the pen.
  8187.  
  8188.  
  8189.  
  8190.   10.2.2 Turtle.
  8191.  
  8192.   This module  extends the  Graphics module with relative graphics routines
  8193.   (Turtle graphics). The modulee is written in Comal and uses all the routines
  8194.   in the Graphics module.
  8195.  
  8196.   The command  graphicscreen executes an implicit window(-160,160,-100,100)
  8197.   and draws a turtle (a small triangle) in the mittle of the window.
  8198.  
  8199.                                          144
  8200.  
  8201.  
  8202.  
  8203.  
  8204.  
  8205.  
  8206.   All procedures and functions in the Graphics module are accessible from the
  8207.   Turtle module and besides the following routines are supplied:
  8208.  
  8209.  
  8210.     PROC arcl(radius,arc_angle)
  8211.  
  8212.       The procedure  causes an arc to be drawn to the left with the parame-
  8213.       ter radius as the radius of curvature and subtending an angle arc_angle
  8214.       degrees. The starting point is the current position and the starting di-
  8215.       rection is the current direction.
  8216.  
  8217.       Both the current pen position and the current direction is changed.
  8218.  
  8219.       Exampel:
  8220.         arcl(10,90)
  8221.  
  8222.  
  8223.     PROC arcr(radius,right_arc)
  8224.  
  8225.       The procedure causes an arc to be drawn to the  right with  the para-
  8226.       meter  radius  as  the  radius  of  curvature and subtending an angle
  8227.       arc_angle degrees. The starting point is the current position and the
  8228.       starting direction is the current direction.
  8229.  
  8230.       Both the current pen position and the current direction is changed.
  8231.  
  8232.  
  8233.     PROC back(x)
  8234.  
  8235.       The procedure  moves the pen x units backwards in the current drawing
  8236.       direction.
  8237.  
  8238.       The current pen position is changed.
  8239.  
  8240.  
  8241.     PROC forward(x)
  8242.  
  8243.       The procedure moves the pen x  units forward  in the  current drawing
  8244.       direction.
  8245.  
  8246.       The current pen position is changed.
  8247.  
  8248.  
  8249.     FUNC heading
  8250.  
  8251.       The function  returns the value of the current drawing direction. The
  8252.       direction is indicated in degrees with 0 vertically upward and positive
  8253.       to the left.
  8254.     
  8255.  
  8256.                                          145
  8257.  
  8258.  
  8259.  
  8260.  
  8261.  
  8262.  
  8263.     PROC hideturtle
  8264.  
  8265.       The procedure  causes the  drawing pen (the turtle) to disappear from
  8266.       view in the window.
  8267.  
  8268.     PROC home
  8269.  
  8270.       The procedure causes the drawing pen (the turtle) to return to position
  8271.       (0,0) and with drawing direction upward.
  8272.  
  8273.  
  8274.     FUNC inq(no)
  8275.  
  8276.       The function inq returns certain of the internal variable of the gra-
  8277.       phics system. The parameter no must be an integral number in the ran-
  8278.       ge 0-33. The meaning of the returned value can be found in the follo-
  8279.       wing table:
  8280.  
  8281.       number    information about     range     Affected by
  8282.         0       graphics mode         0/1       graphicscreen
  8283.         1
  8284.         2       text background       0-        textbackground
  8285.         3       text color            0-        pencolor
  8286.         4
  8287.         5       graphics backgruond   0-        background
  8288.         6       pen color             0-        pencolor
  8289.         7       graphics text width   8/10      textstyle
  8290.         8       graphics text height  8/10      textstyle
  8291.         9       gr. text direction    0         (dir. cannot be changed)
  8292.        10       graphics text mode    0/1       textstyle
  8293.        11       dr. pen visible       0/1       hideturtle/showturtle
  8294.        12       pen inside dr. frame  0/1       most drawing procs
  8295.        13                             1
  8296.        14                             0
  8297.        15       wrapping active       0         (wrap not implemented)
  8298.        16       pen down              0/1       penup/pendown
  8299.        17       x-position            0-width   most drawing procs
  8300.        18       y-position            0-height  most drawing procs
  8301.        19       viewport xmin         0-width   viewport
  8302.        20       viewport xmax         0-width   viewport
  8303.        21       viewport ymin         0-height  viewport
  8304.        22       viewport ymax         0-height  viewport
  8305.        23       vindow xmin           real no.  window
  8306.        24       vindow xmax           real no.  window
  8307.        25       vindow ymin           real no.  window
  8308.        26       vindow ymax           real no.  window
  8309.        27                             1
  8310.        28                             0
  8311.        29       size of pen           0-        turtlesize
  8312.  
  8313.                                          146
  8314.  
  8315.  
  8316.  
  8317.  
  8318.  
  8319.        30       x-ratio               (rem. 1)  window and viewport
  8320.        31       y-ratio               (rem. 2)  window and viewport
  8321.        32                             0
  8322.        33                             0
  8323.  
  8324.       remark 1: (wdxmax-wdxmin)/(vpxmax-vpxmin)
  8325.       remark 2: (wdymax-wdymin)/(vpymax-vpymin)
  8326.  
  8327.  
  8328.     PROC left(angle)
  8329.  
  8330.       The procedure causes the drawing pen  to be  turned angle  degrees to
  8331.       the left in relation to the current drawing direction.
  8332.  
  8333.  
  8334.     PROC pendown
  8335.  
  8336.       The procedure causes the pen to be lowered. This means that the turtle
  8337.       will draw as it is moved, except for the procedures move and moveto.
  8338.  
  8339.  
  8340.     PROC penup
  8341.  
  8342.       The procedure causes the pen to be lifted. After this the pen will not
  8343.       draw when it is moved, except for the procedures draw and drawto.
  8344.  
  8345.  
  8346.     PROC right(angle)
  8347.  
  8348.       The procedure  causes the  drawing pen  to be turned angle degrees to
  8349.       the right in relation to the current drawing direction.
  8350.  
  8351.  
  8352.     PROC setheading(angle)
  8353.  
  8354.       The procedure causes the drawing direction to be set to angle degrees
  8355.       from the home direction (positive to the left).
  8356.  
  8357.  
  8358.     PROC setxy(x,y)
  8359.  
  8360.       The procedure  causes the pen to be moved to the point with coordina-
  8361.       tes (x,y). If the pen is down it acts like drawto, i.e. a line will be
  8362.       drawn. If pen is up it acts as moveto, i.e. no line will be drawn.
  8363.  
  8364.  
  8365.     PROC showturtle
  8366.  
  8367.       The procedure  causes the  drawing pen  (the turtle) to appear in the
  8368.       window.
  8369.  
  8370.                                          147
  8371.  
  8372.  
  8373.  
  8374.  
  8375.  
  8376.  
  8377.  
  8378.     PROC turtlesize(x)
  8379.  
  8380.       The procedure defines the size of the turtle.
  8381.  
  8382.  
  8383.   In the Turtle module the following abbrivations may be used:
  8384.  
  8385.  
  8386.       bk      =   back
  8387.       bg      =   background
  8388.       cs      =   clearscreen
  8389.       fd      =   forward
  8390.       ht      =   hideturtle
  8391.       lt      =   left
  8392.       pc      =   pencolor
  8393.       pd      =   pendown
  8394.       pu      =   penup
  8395.       rt      =   right
  8396.       seth    =   setheading
  8397.       st      =   showturtle
  8398.       textbg  =   textbackground
  8399.  
  8400.  
  8401.   Most programs developped to  be used  with the  Graphics module  will run
  8402.   without changes  with the  Turtle module. In some cases it is necesary to
  8403.   set the coordinate system back to the physical pixel coordinate system by
  8404.   using the line:
  8405.  
  8406.         window(0,width-1,0,height-1)
  8407.  
  8408.  
  8409.  
  8410.   10.3 Catalog.
  8411.  
  8412.   This module  treats a  directory mush like a file. The module exports the
  8413.   following procedures and functions:
  8414.  
  8415.  
  8416.     PROC OpenCatalog(Name$, REF CatId OF ULONG)
  8417.  
  8418.       Opens a volume or directory  for  subsequent  readings.  The returned
  8419.       value in CatId is used as an identifier for the catalog.
  8420.  
  8421.  
  8422.     PROC ReadCatalog(CatId OF ULONG,REF name$,REF filesize OF LONG)
  8423.  
  8424.       Read the next file/subdirectory from the catalog. If filesize=-1 this is a
  8425.       subdirectory otherwise it is the size of the file.
  8426.  
  8427.                                          148
  8428.  
  8429.  
  8430.  
  8431.  
  8432.  
  8433.  
  8434.  
  8435.     PROC CloseCatalog(number OF ULONG)
  8436.  
  8437.       Close a previosly opened catalog.
  8438.  
  8439.  
  8440.     FUNC EOC(number OF ULONG) OF BOOL
  8441.  
  8442.       Returns TRUE (=1) if no more directories. Otherwise FALSE (=0).
  8443.  
  8444.  
  8445.     PROC CloseAllCatalogs
  8446.  
  8447.       Close all catalogs opened by OpenCatalog.
  8448.  
  8449.  
  8450.  
  8451.   10.4 Bob and sprite modules.
  8452.  
  8453.   The three modules SpriteRoutines, SpriteStrucs and GelObject are  used in
  8454.   connection with gels (bobs and sprites). For normal use it is only the last
  8455.   one that has interest.
  8456.  
  8457.   The module  GelObject contains  two object  definitions VSpriteObject and
  8458.   BobObject. The use of these object are best shown by an example.
  8459.  
  8460.   Let first make a (virtual) sprite. This is done by defining an object:
  8461.  
  8462.     STRUC VirtualSprite
  8463.       INHERIT VSpriteObject
  8464.  
  8465.       PROC Create
  8466.         Init
  8467.       ENDPROC Create
  8468.  
  8469.       // Colors
  8470.       DATA $0F00,$00F0,$000F
  8471.  
  8472.       // Sprite data
  8473.       DATA 12                                   // number of lines
  8474.       //   plane 0           plane 1
  8475.       DATA %1111111111111111,%1111111111111111  // 1. line
  8476.       DATA %1111111111111111,%1100000000000011
  8477.       DATA %1111111111111111,%1100000000000011
  8478.       DATA %1111000000001111,%1100111111110011
  8479.       DATA %1111000000001111,%1100111111110011
  8480.       DATA %1111000000001111,%1100110011110011
  8481.       DATA %1111000000001111,%1100110011110011
  8482.       DATA %1111000000001111,%1100111111110011
  8483.  
  8484.                                          149
  8485.  
  8486.  
  8487.  
  8488.  
  8489.  
  8490.       DATA %1111000000001111,%1100111111110011
  8491.       DATA %1111111111111111,%1100000000000011
  8492.       DATA %1111111111111111,%1100000000000011
  8493.       DATA %1111111111111111,%1111111111111111  // 12. line
  8494.     ENDSTRUC VirtualSprite
  8495.  
  8496.  
  8497.   This object inherits the VSpriteObject and it contains a method Create and
  8498.   DATA statements defining the object.
  8499.  
  8500.   To create a sprite with a shape defined by the  DATA statements  you have
  8501.   to execute a DIM statement:
  8502.  
  8503.     DIM MySprite OF VirtualSprite
  8504.  
  8505.   and then call the methods Create and Draw:
  8506.  
  8507.     MySprite.Create
  8508.     MySprite.Draw(50,50)
  8509.  
  8510.   Now you  can see  the sprite  on the  screen. To move the sprite call the
  8511.   method Move (inherited from VSpriteObject), for instance
  8512.  
  8513.     MySprite.Move(10,10)
  8514.  
  8515.  
  8516.   At the end of your program the sprite has to be deleted:
  8517.  
  8518.     MySprite.Delete
  8519.  
  8520.  
  8521.   A bob is made in almost  the same  way. First  you have  to define  a Bob
  8522.   structure:
  8523.  
  8524.     STRUC Bob
  8525.       INHERIT BobObject
  8526.  
  8527.       PROC Create
  8528.         Init
  8529.       ENDPROC Create
  8530.  
  8531.       // Bob data
  8532.       DATA 1,9                 // Words per line and number of lines
  8533.  
  8534.       // Plane 0
  8535.       DATA %0000111111000011   // 1. line
  8536.       DATA %0011111111110011
  8537.       DATA %0011000011000011
  8538.       DATA %0000000000000000
  8539.       DATA %0000000000000000
  8540.  
  8541.                                          150
  8542.  
  8543.  
  8544.  
  8545.  
  8546.  
  8547.       DATA %0000000000000000
  8548.       DATA %1100000000110011
  8549.       DATA %1111111111000000
  8550.       DATA %0011111100000011   // 9. line
  8551.  
  8552.       // Plane 1
  8553.       DATA %0000000000000000   // 1. line
  8554.       DATA %0000000000000000
  8555.       DATA %0000000000000000
  8556.       DATA %0011110000000011
  8557.       DATA %0011111111000011
  8558.       DATA %0000001111000011
  8559.       DATA %1100000000110011
  8560.       DATA %1111111111000000
  8561.       DATA %0011111100000011   // 9. line
  8562.     ENDSTRUC Bob
  8563.  
  8564.  
  8565.   and execute a DIM statement:
  8566.  
  8567.     DIM MyBob OF Bob
  8568.  
  8569.   The rest of the program is made in the same way as for virtual sprites.
  8570.  
  8571.   You can  have as  many virtual sprite and bobs as you want on the screen.
  8572.   They are all made in the same way.  Only the  DATA statement  may be dif-
  8573.   ferent.
  8574.  
  8575.  
  8576.  
  8577.   10.5 Memory.
  8578.  
  8579.   This module is used to allocate memory from the Amiga's free memory pool.
  8580.  
  8581.   The following routines are exported:
  8582.  
  8583.  
  8584.     FUNC malloc(BlockSize OF ULONG,MemType OF ULONG) OF ULONG
  8585.  
  8586.       Allocate  a  memory  block  of  size  BlockSize  and  of type MemType
  8587.       (MEMF_PUBLIC, MEMF_CLEAR, MEMF_CHIP or MEMF_FAST).
  8588.  
  8589.       The function returns the address of  the block  or zero  if the block
  8590.       could not be allocated.
  8591.  
  8592.  
  8593.  
  8594.     PROC mfree(MemAdr OF ULONG)
  8595.  
  8596.       Free a memory block previosly allocated by malloc
  8597.  
  8598.                                          151
  8599.  
  8600.  
  8601.  
  8602.  
  8603.  
  8604.  
  8605.  
  8606.     PROC mfreeall
  8607.  
  8608.       Free all memory blocks previosly allocated by malloc
  8609.  
  8610.  
  8611.   The module contains a signal routine that calls mfreeall if the variables are
  8612.   cleared.
  8613.  
  8614.  
  8615.  
  8616.   10.6 CodeManInclude and InterpreterInclude.
  8617.  
  8618.   These modules contains definitions to be used to access Comal.CodeMan and
  8619.   Comal.Interpreter (see section V.2).
  8620.  
  8621.  
  8622.  
  8623.   10.7 StartProgram.
  8624.  
  8625.   This module exports one procedure:
  8626.  
  8627.  
  8628.     PROC StartProgram(ProgramName$)
  8629.  
  8630.       Start a Comal program as a seperate process that will terminate itself.
  8631.       The parameter must be the full path of the program that must  be sto-
  8632.       red as a code file.
  8633.  
  8634.  
  8635.   10.9 Timer.
  8636.  
  8637.   This module exports the following procedures:
  8638.  
  8639.  
  8640.     PROC TimerEvent(TimeInterval,EventProc)
  8641.  
  8642.       Start the timer. The timer runs for the specified time interval (in se-
  8643.       conds) and then you procedure EventProc is called. The event procedure
  8644.       is a procedure without parameters.
  8645.  
  8646.  
  8647.     PROC AbortTimer(EventProc)
  8648.  
  8649.       Abort a time event before timeout.
  8650.  
  8651.  
  8652.   The timer can be used to make periodic interrupts (see section 7.5).
  8653.  
  8654.  
  8655.                                          152
  8656.  
  8657.  
  8658.  
  8659.  
  8660.  
  8661.  
  8662.   10.10 SerialComm.
  8663.  
  8664.   This module is a serial communication module. The following procedures and
  8665.   functions are exported:
  8666.  
  8667.  
  8668.     FUNC chars_in_buff(direction OF BYTE) OF SHORT
  8669.  
  8670.       This function returns TRUE if there are chracters  in the  IO buffer.
  8671.       Otherwise it returns FALSE.
  8672.  
  8673.       If direction is 0 the input buffer is tested. Otherwise it is the output
  8674.       buffer (for the time being there is no  output buffer  and the return
  8675.       value with direction<>0 will always be FALSE).
  8676.  
  8677.  
  8678.     PROC clear_buff(direction OF BYTE)
  8679.  
  8680.       Clear the IO buffer. If direction is 0 the input buffer is tested. Other-
  8681.       wise it is the output buffer.
  8682.  
  8683.  
  8684.     PROC ClearTermArray
  8685.  
  8686.       Remove all break characters set by SetTermArray.
  8687.  
  8688.  
  8689.     PROC CloseSerial
  8690.  
  8691.       Close the serial device and make it available for other tasks.
  8692.  
  8693.  
  8694.     FUNC OpenSerial OF BOOL
  8695.  
  8696.       Open serial device. If success the value TRUE  is returned. Otherwise
  8697.       FALSE is returned.
  8698.  
  8699.  
  8700.     PROC receive(REF Data$,MaxChars OF LONG,MaxWait)
  8701.  
  8702.       Read MaxChars characters into th string Data$. The procedure will re-
  8703.       turn when all characters are received or MaxWait secs has elapsed.
  8704.  
  8705.  
  8706.     PROC send(Data$)
  8707.  
  8708.       Send the string Data$.
  8709.  
  8710.  
  8711.  
  8712.                                          153
  8713.  
  8714.  
  8715.  
  8716.  
  8717.  
  8718.     PROC set_mode(baud OF LONG,parity$,Len OF UBYTE,StopBits OF BYTE)
  8719.  
  8720.       Set communication parameters. The parameters are:
  8721.  
  8722.         baud:     The baud rate.
  8723.  
  8724.         parity$:  "N" = no parity
  8725.                   "E" = even parity
  8726.                   "O" = odd parity
  8727.  
  8728.         Len:      The number of bits in a word (6,7 or 8).
  8729.  
  8730.         StopBits: The number of stop bits (1 or 2).
  8731.  
  8732.  
  8733.     PROC SetTermArray(Arr OF TermArray)
  8734.  
  8735.       Set termination characters. The type TermArray is defined in the modu-
  8736.       le as
  8737.  
  8738.         TYPE TermArray=ARRAY(0..7) OF UBYTE
  8739.  
  8740.       The actual  parameter Arr should be filled with characters that is to
  8741.       break the reading. All 8 characters must be set in non increasing order.
  8742.       If less than 8 break characters is to be used (this is normal) fill the
  8743.       end of the array with the lowest value.
  8744.  
  8745.       Example:
  8746.  
  8747.         DIM Array OF TermArray
  8748.  
  8749.           :
  8750.  
  8751.         Array():=$03    // ^C
  8752.         Array(0):=$1A   // ^Z
  8753.         Array(1):=$04   // ^D
  8754.  
  8755.         SetTermArray(Array())
  8756.  
  8757.           :
  8758.  
  8759.  
  8760.  
  8761.  
  8762.   10.11 Operating system modules.
  8763.  
  8764.   A number of modules are to be used to access the operating  system routi-
  8765.   nes. These routines are devided into two groups:
  8766.  
  8767.  
  8768.  
  8769.                                          154
  8770.  
  8771.  
  8772.  
  8773.  
  8774.  
  8775.     - Library interfaces for the system routines themself. These modules are
  8776.       mashine coded modules.
  8777.  
  8778.     - Definitions necessary to call the system routines.
  8779.  
  8780.  
  8781.   10.11.1 Library interface routines.
  8782.  
  8783.   These modules are:
  8784.  
  8785.         AslLibrary
  8786.         DosLibrary
  8787.         ExecLibrary
  8788.         GadToolsLibrary
  8789.         GraphicsLibrary
  8790.         IntuitionLibrary
  8791.  
  8792.  
  8793.   The modules contains interfaces for all the routines in the corresponding
  8794.   libraries. The names and the calling conventions are exactly the same as is
  8795.   used in a C program.
  8796.  
  8797.   Example: This program opens a window and closes it again
  8798.  
  8799.     USE System    
  8800.     USE IntuitionWindow    
  8801.     USE IntuitionLibrary    
  8802.  
  8803.     DIM NewWindow OF NewWindow
  8804.     DIM Window OF POINTER TO Window    
  8805.  
  8806.     NewWindow.LeftEdge:=50
  8807.     NewWindow.TopEdge:=30
  8808.     NewWindow.Width:=300
  8809.     NewWindow.Height:=100
  8810.     NewWindow.BlockPen:=1
  8811.     NewWindow.Title:=ADR("Window demo")
  8812.     NewWindow.Screen:=ComalStruc@.IO_Screen
  8813.     NewWindow.Flags:=WINDOWDEPTH BITOR WINDOWDRAG
  8814.     NewWindow.Type:=CUSTOMSCREEN
  8815.  
  8816.     Window:=OpenWindow(ADR(NewWindow))      
  8817.     WAIT 3
  8818.     CloseWindow(Window)        
  8819.  
  8820.  
  8821.   The library interface modules will not be described in detail here. Consult a
  8822.   description of the Amiga OS system routines.
  8823.  
  8824.  
  8825.  
  8826.                                          155
  8827.  
  8828.  
  8829.  
  8830.  
  8831.  
  8832.   10.11.2 Definitions for use in the library modules.
  8833.  
  8834.   The definitions to be used in connection with calls to library routines are
  8835.   found in the following modules:
  8836.  
  8837.  
  8838.     AslInclude
  8839.  
  8840.       Structures:
  8841.         STRUC FileRequester
  8842.         STRUC FontRequester
  8843.  
  8844.       Types:
  8845.         TYPE FileReqPtr=POINTER TO FileRequester
  8846.  
  8847.       Constants:
  8848.         ASL_FuncFlag file requester tag values (FILF_DOWILDFUNC ..)
  8849.         ASL_ExtFlags1 file requester tag values (FILF1_NOFILES ..)
  8850.         ASL_FuncFlag font requester tag values  (FONF_FRONTCOLOR ...)
  8851.         requester types (ASL_FileRequest and ASL_FontRequest)
  8852.         tags for AllocAslRequestA and AslRequestA (ASL_Hail ...)
  8853.  
  8854.  
  8855.     DosAslInclude
  8856.  
  8857.       Structures:
  8858.         STRUC DateStamp
  8859.         STRUC FileInfoBlock
  8860.         STRUC AChain
  8861.         STRUC AnchorPath
  8862.  
  8863.       Types:
  8864.         TYPE FileInfoPtr=POINTER TO FileInfoBlock
  8865.         TYPE AnchorPathPtr=POINTER TO AnchorPath
  8866.  
  8867.  
  8868.     ExecLists
  8869.  
  8870.       Structures:
  8871.         STRUC Node
  8872.         STRUC List
  8873.           FUNC New CONSTRUCTOR
  8874.             Initializes the list.
  8875.  
  8876.       Constants:
  8877.         Node types (NT_TASK, NT_MESSAGE ...)
  8878.  
  8879.  
  8880.  
  8881.  
  8882.  
  8883.                                          156
  8884.  
  8885.  
  8886.  
  8887.  
  8888.  
  8889.     GadToolsInclude
  8890.  
  8891.       Structures:
  8892.         STRUC StringInfo
  8893.         STRUC Gadget
  8894.         STRUC NewGadget
  8895.         STRUC NewMenu
  8896.  
  8897.       Constants:
  8898.         Gadget types (GENERIC_KIND, BUTTON_KIND ...)
  8899.         IDCMP flags (ARROWIDCMP, BUTTONIDCMP ...)
  8900.         spacing constants (INTERWIDTH and INTERHEIGHT)
  8901.         NewGadget flags (NG_HIGHLABEL, PLACETEXT_LEFT ...)
  8902.         NewMenu types (NM_TITLE, NMITEM ...)
  8903.         return codes (GTMENU_TRIMMED ...)
  8904.         tags for tool kit functions (GTVI_NewWindow, GTVI_NWTags ...)
  8905.  
  8906.  
  8907.     Gfx
  8908.  
  8909.       Functions and procedures:
  8910.         FUNC RASSIZE(w,h)     (in fact a macro in C include files)
  8911.  
  8912.       Structures:
  8913.         STRUC RectAngle
  8914.         STRUC BitMap
  8915.  
  8916.  
  8917.     IDCMP
  8918.  
  8919.       Structures:
  8920.         STRUC IntuiMessage    (inherits Message from PortObjects)
  8921.  
  8922.       Constants:
  8923.         IDCMP classes (SIZEVERYFY, NEWSIZE ...)
  8924.         Mouse codes and key qualifiers (SELECTUP, ALTLEFT, ...)
  8925.  
  8926.  
  8927.     IntuiText
  8928.  
  8929.       Structures:
  8930.         STRUC IntuiText
  8931.         STRUC TextAttr
  8932.  
  8933.  
  8934.       Constants:
  8935.         draw modes (JAM1, JAM2, XOR)
  8936.  
  8937.  
  8938.  
  8939.  
  8940.                                          157
  8941.  
  8942.  
  8943.  
  8944.  
  8945.  
  8946.     IoObjects
  8947.  
  8948.       Structures:
  8949.  
  8950.         STRUC IoRequest
  8951.           INHERIT Message
  8952.           PROC Init Constructor
  8953.             Initializes the length of the message.
  8954.           PROC Do
  8955.             Calls DoIO in the ExecLibrary with a pointer  to the  object as
  8956.             parameter.
  8957.           PROC Send
  8958.             Calls SendIO in the ExecLibrary with a pointer to the object as
  8959.             parameter.
  8960.           PROC Abort
  8961.             Calls AbortIO in the ExecLibrary with a pointer to the object as
  8962.             parameter.
  8963.  
  8964.         STRUC IoStdReq
  8965.           INHERIT IoRequest
  8966.           PROC Init Constructor
  8967.             Initializes the length of the message.
  8968.  
  8969.  
  8970.     Layers
  8971.  
  8972.       Structures:
  8973.         STRUC Layer_Info
  8974.  
  8975.       Constants:
  8976.         Layer types etc. (LAYERSIMPLE, LAYERSMART ...)
  8977.  
  8978.  
  8979.     MenuStrucs
  8980.  
  8981.       Structures:
  8982.         STRUC Menu
  8983.         STRUC MenuItem
  8984.  
  8985.       Constans:
  8986.         menu and item flags (MENUENABLED, CHECKIT, ITEMTEXT ...)
  8987.         MENUNULL
  8988.  
  8989.  
  8990.     PortObjects
  8991.  
  8992.       Structures:
  8993.         STRUC MsgPort
  8994.           FUNC Init CONSTRUCTOR
  8995.             Makes the necessary initialization for a private port (allocates a
  8996.  
  8997.                                          158
  8998.  
  8999.  
  9000.  
  9001.  
  9002.  
  9003.             signal bit etc.).
  9004.           PROC Delete DESTRUCTOR
  9005.             Removes the port from the list of public  ports (if  the method
  9006.             Add has been called) and deallocates the signal.
  9007.           PROC Add(REF Name$,Priority OF BYTE)
  9008.             Adds the port to the list of public ports.
  9009.           PROC Wait
  9010.             Wait for a message to arrive. It is possible to break the program
  9011.             during the wait.
  9012.           FUNC Get
  9013.             The ExecLibrary function GetMsg is called with a pointer to the
  9014.             port as parameter.
  9015.           PROC Put(REF Msg OF Message)
  9016.             The ExecLibrary  procedure PutMsg  is called  with a pointer to
  9017.             the port and the message as parameter.
  9018.  
  9019.         STRUC Message
  9020.           FUNC Init CONSTRUCTOR
  9021.             Initializes the message (but no reply port is created!!).
  9022.           PROC Wait
  9023.             Waits for the message to be replied and remove the message from
  9024.             the reply port.
  9025.           PROC Reply
  9026.             Replies the message.
  9027.  
  9028.  
  9029.         Before you  can use  the message  you will  normally have to make a
  9030.         reply port and put an address  of this  port into  the mn_ReplyPort
  9031.         field.
  9032.  
  9033.  
  9034.     RastPort
  9035.  
  9036.       Structures:
  9037.         STRUC AreaInfo
  9038.         STRUC TmpRas
  9039.         STRUC RastPort
  9040.  
  9041.  
  9042.       Constants:
  9043.         drawing modes (JAM1, JAM2, COMPLEMENT, INVERSEVID)
  9044.         bits for RastPort flags (FRST_DOT, ONE_DOT, DBUFFER)
  9045.  
  9046.  
  9047.     TagItem
  9048.  
  9049.       Structures:
  9050.         STRUC TagItem
  9051.  
  9052.  
  9053.  
  9054.                                          159
  9055.  
  9056.  
  9057.  
  9058.  
  9059.  
  9060.       Constants:
  9061.         system tags (TAG_DONE, TAG_END, .. , TAG_USER)
  9062.         TAGFILTER_AND, TAGFILTER_NOT
  9063.  
  9064.  
  9065.     View
  9066.  
  9067.       Structures:
  9068.         STRUC ColorMap
  9069.         STRUC ViewPort
  9070.         STRUC View
  9071.         STRUC RasInfo
  9072.  
  9073.       Constants:
  9074.         view modes (PFBA, DUALPF, HIRES, ...)
  9075.  
  9076.  
  9077.     IntuitionWindow
  9078.  
  9079.       Structures:
  9080.         STRUC NewWindow
  9081.         STRUC Window
  9082.  
  9083.       Constants:
  9084.         flag bits set by Intuition (SCREENTYPE, WBENCHSCREEN, ...)
  9085.         window flags (WINDOWSIZING, WINDOWDRAG, ...)
  9086.  
  9087.  
  9088.     IntuitionScreen
  9089.  
  9090.       Structures:
  9091.         STRUC NewScreen
  9092.         STRUC Screen
  9093.  
  9094.  
  9095.  
  9096.   11 The Comal Intuition Tools (CIT).
  9097.  
  9098.  
  9099.     NOTE! CIT requires Workbench 2.04 or higher.
  9100.  
  9101.  
  9102.   The Comal Intuition Tool (short CIT) is a set of modules that are used to
  9103.   build various Intuition items: screens, windows, gadgets etc.
  9104.  
  9105.   Normally the creation of Intuition items involves filling out special struc-
  9106.   tures with  special values. If the item is used to act on response from a
  9107.   user (such as gadgets or menus) you also have to work with message ports,
  9108.   signals and messages. And you must evaluate each message to find out what
  9109.   to do.
  9110.  
  9111.                                          160
  9112.  
  9113.  
  9114.  
  9115.  
  9116.  
  9117.  
  9118.   By using CIT it is much easier. All the necessary structures are filled auto-
  9119.   matically  with  standard  values  that  can be changed by calling object
  9120.   methods. You don't have to know  anything about  ports, signals  and mes-
  9121.   sages and the evaluation of a user action is done by the objects.
  9122.  
  9123.  
  9124.  
  9125.   11.1 General description of CIT.
  9126.  
  9127.   In CIT  all Intuition items are treated as Objects. For example, a button
  9128.   gadget is an object that can be placed  in a  window and  a window  is an
  9129.   object that can be placed in a screen.
  9130.  
  9131.   Certain objects  have similar  characteristics and can be classified into
  9132.   groups called classes. For instance, menus and gadgets are similiar in that
  9133.   they are placed in a window. They are classified as WindowClass objects. In
  9134.   the same way a check box, a button gadget and  a string  input gadget are
  9135.   similar. They are classified as members of the class CITGadget (a subclass
  9136.   of the WindowClass).
  9137.  
  9138.   All the objects are implemented as  structures. You  should think  of the
  9139.   objects as physical items. First you have to create it. This is done by exe-
  9140.   cuting a DIM or LOCAL statement. Then you  will proporly  add some attri-
  9141.   butes like  a position,  a size or even a colour. This is done by calling
  9142.   methods in the structure. Finally you will place it somewhere. This is done
  9143.   by calling a method InsObject in the containing object.
  9144.  
  9145.   As can be seen, all objects are placed in other objects. In this way objects
  9146.   form an object hierachy as shown below (the boxes containing '??' are not
  9147.   defined for the time being):
  9148.  
  9149.  
  9150.  
  9151.                             +---------------+
  9152.                             |               |
  9153.                             | CITWorkbench  |
  9154.                             |               |
  9155.                             +---------------+
  9156.                               ^     ^     ^
  9157.                               |     |     |
  9158.           +-------------------+     |     +------------------+
  9159.           |                         |                        |
  9160.     +------------+           +-------------+          +-------------+
  9161.     |            |           |             |          |             |
  9162.     |   ??       |  ......   |  CITScreen  |  ......  |    ??       |
  9163.     |            |           |             |          |             |
  9164.     +------------+           +-------------+          +-------------+
  9165.                               ^     ^     ^
  9166.                               |     |     |
  9167.  
  9168.                                          161
  9169.  
  9170.  
  9171.  
  9172.  
  9173.  
  9174.           +-------------------+     |     +------------------+
  9175.           |                         |                        |
  9176.     +------------+           +-------------+          +-------------+
  9177.     |            |           |             |          |             |
  9178.     |   ??       |  ......   |  CITWindow  |  ......  |    ??       |
  9179.     |            |           |             |          |             |
  9180.     +------------+           +-------------+          +-------------+
  9181.                               ^  ^  ^  ^  ^
  9182.                               |  |  |  |  |
  9183.                               |  |  |  |  |
  9184.           +-------------------+  |  |  |  +------------------+
  9185.           |                      |  |  |                     |
  9186.           |           +----------+  |  +-------+             |
  9187.           |           |             |          |             |
  9188.     +-----------+     |    +-------------+     |      +-------------+
  9189.     |           |     |    |             |     |      |             |
  9190.     |  CITText  |     |    |  CITGadgets |     |      |   CITMenus  |
  9191.     |           |     |    |             |     |      |             |
  9192.     +-----------+     |    +-------------+     |      +-------------+
  9193.                       |                        |
  9194.                 +-----------+           +-------------+
  9195.                 |           |           |             |
  9196.           ....  |  CITMouse | ........  | CITRequester| ......
  9197.                 |           |           |             |
  9198.                 +-----------+           +-------------+
  9199.  
  9200.  
  9201.  
  9202.   The use of all these different sorts of objects follow the same scheme:
  9203.  
  9204.   To create an object you have to execute a DIM (or LOCAL) statement like:
  9205.  
  9206.       DIM MyObject OF CITObject
  9207.  
  9208.  
  9209.   Most of  the visible  objects have a Size method and a Position method to
  9210.   set its size and its position:
  9211.  
  9212.       MyObject.Size(Width,Height)
  9213.       MyObject.Position(LeftEdge,TopEdge)
  9214.  
  9215.   and some have a Label method to connect a text to the object:
  9216.  
  9217.       MyObject.Label(SomeText$)
  9218.  
  9219.  
  9220.   These methods are always  named Size,  Position and  Label, but sometimes
  9221.   there are additional parameters. In some of the gadgets, for instance, you
  9222.   have to specify if the text is to be placed inside the object itself or to the
  9223.   left, to the right etc.
  9224.  
  9225.                                          162
  9226.  
  9227.  
  9228.  
  9229.  
  9230.  
  9231.  
  9232.   If the  object is  to respond to a user action and you want immediate re-
  9233.   sponse, you have to call the method EventHandler with the name of  a pro-
  9234.   cedure to be called as the result of the users action:
  9235.  
  9236.       MyObject.EventHandler(MyObjectEvent())
  9237.  
  9238.  
  9239.  
  9240.   The number  and types of the parameters in the event procedure are diffe-
  9241.   rent from object type to object type (in the example we have indicated one
  9242.   parameter).
  9243.  
  9244.   Having set all the attributes you have to insert it in another object. This is
  9245.   done by calling the method InsObject in the container object:
  9246.  
  9247.       Container.InsObject(MyObject,Error)
  9248.  
  9249.  
  9250.   When you are finished using the object you should remove it by calling the
  9251.   method RemObject in the container object:
  9252.  
  9253.       Container.RemObject(MyObject)
  9254.  
  9255.  
  9256.   NOTE: Not all objects can be removed individually.
  9257.  
  9258.   By removing the object MyObject all objects contained in this object will
  9259.   be removed, too.
  9260.  
  9261.   Between the insertion and the removal  you will  normally be  waiting for
  9262.   some termination code to take on a non zero value. This is typically done
  9263.   in a loop like:
  9264.  
  9265.       WHILE NOT Terminate DO WAIT
  9266.  
  9267.  
  9268.   While you are waiting all your event procedures will be called automatically.
  9269.  
  9270.   In the following sections you will find a complete description of all the CIT
  9271.   objects.
  9272.  
  9273.  
  9274.  
  9275.   11.2 Simple CIT examples.
  9276.  
  9277.   As a  simple example  of the use of CIT let's make a window with a string
  9278.   input gadget and a button gadget to terminate the input.
  9279.  
  9280.   First we have to load the modules we are using:
  9281.  
  9282.                                          163
  9283.  
  9284.  
  9285.  
  9286.  
  9287.  
  9288.  
  9289.     USE CITScreen
  9290.     USE CITWindow
  9291.     USE CITGadgets
  9292.  
  9293.   and then we will create our window:
  9294.  
  9295.     DIM DemoWindow OF CITWindow
  9296.  
  9297.   give it the right size, place it on the correct position in the containing
  9298.   screen and make it active when it opens:
  9299.  
  9300.     DemoWindow.Size(500,100)
  9301.     DemoWindow.Position(60,50)
  9302.     DemoWindow.Activate
  9303.  
  9304.  
  9305.   We want  to place  the window  in the  ComalScreen which  is a predefined
  9306.   screen found in the module CITScreen:
  9307.  
  9308.     ComalScreen.InsObject(DemoWindow,Error)
  9309.  
  9310.  
  9311.   Any error code is returned in the variable Error. We have to test this va-
  9312.   riable before we proceed:
  9313.  
  9314.     IF Error THEN
  9315.       STOP "Could not create window"
  9316.     ENDIF
  9317.  
  9318.  
  9319.   The string input gadget is created, sized and positioned in the same way:
  9320.  
  9321.     DIM NameInput OF StringGadget
  9322.     NameInput.Size(300,15)
  9323.     NameInput.Position(160,10)
  9324.  
  9325.  
  9326.   We want a text to the left of the gadget:
  9327.  
  9328.     NameInput.Label("Enter your name: ",LEFT)
  9329.  
  9330.  
  9331.   This input  gadget is placed in the window in exactly the same way as the
  9332.   window was placed in the screen:
  9333.  
  9334.     DemoWindow.InsObject(NameInput,Error)
  9335.  
  9336.  
  9337.   And now the button gadget:
  9338.  
  9339.                                          164
  9340.  
  9341.  
  9342.  
  9343.  
  9344.  
  9345.  
  9346.     DIM OkButton OF ButtonGadget
  9347.     OkButton.Size(40,15)
  9348.     OkButton.Position(10,-(6+15))
  9349.     OkButton.Label("Ok",INSIDE)           // Place text inside the gadget
  9350.     DemoWindow.InsObject(OkButton,Error)
  9351.  
  9352.  
  9353.   Note that the y-coordinate of the position is negative. Then the gadget is
  9354.   positioned relative to the buttom border of the window.
  9355.  
  9356.   The variable Error is only changed if an error occurs. Let's test it now:
  9357.  
  9358.     IF Error THEN
  9359.       STOP "Could not create one or more gadgets"
  9360.     ENDIF
  9361.  
  9362.  
  9363.   Now we will sleep until the Ok button is pressed:
  9364.  
  9365.     WHILE NOT OkButton.Pressed DO WAIT
  9366.  
  9367.  
  9368.   The text typed into the input gadget is found in a field by name Value$ in
  9369.   the OkButton structure:
  9370.  
  9371.     PRINT "Your name is: ",NameInput.Value$
  9372.  
  9373.  
  9374.   As the final task we have to close the window (and all  items inserted in
  9375.   the window):
  9376.  
  9377.     ComalScreen.RemObject(DemoWindow)
  9378.  
  9379.  
  9380.   The complete program looks like:
  9381.  
  9382.     USE CITScreen
  9383.     USE CITWindow
  9384.     USE CITGadgets
  9385.  
  9386.     DIM DemoWindow OF CITWindow
  9387.     DemoWindow.Size(500,100)
  9388.     DemoWindow.Position(60,50)
  9389.     DemoWindow.Activate
  9390.     ComalScreen.InsObject(DemoWindow,Error)
  9391.     IF Error THEN
  9392.       STOP "Could not create window"
  9393.     ENDIF
  9394.  
  9395.  
  9396.                                          165
  9397.  
  9398.  
  9399.  
  9400.  
  9401.  
  9402.     DIM NameInput OF StringGadget
  9403.     NameInput.Size(300,15)
  9404.     NameInput.Position(160,10)
  9405.     NameInput.Label("Enter your name: ",LEFT)
  9406.     DemoWindow.InsObject(NameInput,Error)
  9407.  
  9408.     DIM OkButton OF ButtonGadget
  9409.     OkButton.Size(40,15)
  9410.     OkButton.Position(10,-(6+15))
  9411.     OkButton.Label("Ok",INSIDE)
  9412.     DemoWindow.InsObject(OkButton,Error)
  9413.  
  9414.     IF Error THEN
  9415.       STOP "Could not create one or more gadgets"
  9416.     ENDIF
  9417.  
  9418.     WHILE NOT OkButton.Pressed DO WAIT
  9419.  
  9420.     PRINT "Your name is: ",NameInput.Value$
  9421.  
  9422.     ComalScreen.RemObject(DemoWindow)
  9423.  
  9424.  
  9425.   In our  next example  we will  add a  Cancel button  to the window and an
  9426.   event procedure to each of the button gadgets. These procedures are called
  9427.   each time  the respective  buttons are  pressed. The OkEvent procedure is
  9428.   added in this way:
  9429.  
  9430.     OkButton.EventHandler(OkEvent())
  9431.  
  9432.       :
  9433.  
  9434.     PROC OkEvent(Id OF USHORT)
  9435.       Terminate:=1
  9436.     ENDPROC OkEvent
  9437.  
  9438.  
  9439.   The Cancel button (including the event procedure) is made in this way:
  9440.  
  9441.     DIM CancelButton OF ButtonGadget
  9442.     CancelButton.Size(60,15)
  9443.     CancelButton.Position(-(10+60),-(6+15))
  9444.     CancelButton.Label("Cancel",INSIDE)
  9445.     CancelButton.EventHandler(CancelEvent())
  9446.     DemoWindow.InsObject(CancelButton,Error)
  9447.     PROC CancelEvent(Id OF USHORT)
  9448.       Terminate:=2
  9449.     ENDPROC CancelEvent
  9450.  
  9451.  
  9452.  
  9453.                                          166
  9454.  
  9455.  
  9456.  
  9457.  
  9458.  
  9459.   Having done this and having testet for errors we will go to  sleep. While
  9460.   sleeping the system will call the event procedures for you:
  9461.  
  9462.     WHILE NOT Terminate DO WAIT
  9463.  
  9464.  
  9465.   The complete  program looks like (note that the variable Terminate has to
  9466.   be dimensioned before you go to sleep):
  9467.  
  9468.     USE CITScreen
  9469.     USE CITWindow
  9470.     USE CITGadgets
  9471.  
  9472.     DIM Terminate OF SHORT
  9473.  
  9474.     DIM DemoWindow OF CITWindow
  9475.     DemoWindow.Size(500,100)
  9476.     DemoWindow.Position(60,50)
  9477.     DemoWindow.Activate
  9478.     ComalScreen.InsObject(DemoWindow,Error)
  9479.     IF Error THEN
  9480.       STOP "Could not create window"
  9481.     ENDIF
  9482.  
  9483.     DIM NameInput OF StringGadget
  9484.     NameInput.Size(300,15)
  9485.     NameInput.Position(160,10)
  9486.     NameInput.Label("Enter your name: ",LEFT)
  9487.     DemoWindow.InsObject(NameInput,Error)
  9488.  
  9489.     DIM OkButton OF ButtonGadget
  9490.     OkButtonSize(60,15)
  9491.     OkButtonPosition(10,-(6+15))
  9492.     OkButtonLabel("Ok",INSIDE)
  9493.     OkButtonEventHandler(OkEvent())
  9494.     DemoWindow.InsObject(OkButton,Error)
  9495.     PROC OkEvent(id OF USHORT)
  9496.       Terminate:=1
  9497.     ENDPROC OkEvent
  9498.  
  9499.     DIM CancelButton OF ButtonGadget
  9500.     CancelButton.Size(60,15)
  9501.     CancelButton.Position(-(10+60),-(6+15))
  9502.     CancelButton.Label("Cancel",INSIDE)
  9503.     CancelButton.EventHandler(CancelEvent())
  9504.     DemoWindow.InsObject(CancelButton,Error)
  9505.     PROC CancelEvent(id OF USHORT)
  9506.       Terminate:=2
  9507.     ENDPROC CancelEvent
  9508.  
  9509.  
  9510.                                          167
  9511.  
  9512.  
  9513.  
  9514.  
  9515.  
  9516.     IF Error THEN
  9517.       STOP "Could not create one or more gadgets"
  9518.     ENDIF
  9519.  
  9520.     WHILE NOT Terminate DO WAIT
  9521.  
  9522.     CASE Terminate OF
  9523.     WHEN 1
  9524.       PRINT "Hello ",NameInput.Value$,". Welcome to the world of CIT"
  9525.     WHEN 2
  9526.       PRINT "You don't know your name!?"
  9527.     ENDCASE
  9528.  
  9529.     ComalScreen.RemObject(DemoWindow)
  9530.  
  9531.  
  9532.   In the tutorial other examples are shown (chapter II.8-9).
  9533.  
  9534.  
  9535.   11.3 CIT reference.
  9536.  
  9537.   In the following subsections you will find a complete description of all the
  9538.   modules containing CIT objects, the object methods and the attributes that
  9539.   can be set in the objects.
  9540.  
  9541.  
  9542.  
  9543.   11.3.1 CITWorkbench.
  9544.  
  9545.   The CITWorkbench module  containns  the  basic  object  CITWorkbench. You
  9546.   cannot create a CITWorkbench object yourself. It is already created in the
  9547.   module.
  9548.  
  9549.   The following methods in CITWorkbench can be used:
  9550.  
  9551.  
  9552.     PROC InsObject(REF WBObject OF WorkbenchClass,REF Error OF SHORT)
  9553.  
  9554.       An object of the class WorkbenchClass is placed  on the CITWorkbench.
  9555.       For the  time being  CITScreen is  the only  member of the Workbench-
  9556.       Class.
  9557.  
  9558.  
  9559.     PROC RemObject(REF WBObject OF WorkbenchClass)
  9560.  
  9561.       Remove an object from the the CITWorkbench.
  9562.  
  9563.  
  9564.   If variables in the program are cleared all objects inserted in CITWorkbench
  9565.   are automatically removed.
  9566.  
  9567.                                          168
  9568.  
  9569.  
  9570.  
  9571.  
  9572.  
  9573.  
  9574.   11.3.2 CITScreen.
  9575.  
  9576.   The  object  CITScreen  found  in  the  CITScreen module is member of the
  9577.   WorkbenchClass (the only member for the time being).
  9578.  
  9579.   A CITScreen has to be created in a DIM (or LOCAL) statement  and inserted
  9580.   in CITWorkbench.  The screen will be a high resolution screen (640 pixels
  9581.   horizontal).
  9582.  
  9583.   Example: 
  9584.  
  9585.     DIM MyScreen OF CITScreen
  9586.     MyScreen.Label("My Own Screen")
  9587.     MyScreen.Depth(3)
  9588.     CITWorkbench.InsObject(MyScreen,Error)
  9589.  
  9590.  
  9591.   The following methods in CITScreen can be used:
  9592.  
  9593.  
  9594.     PROC InsObject(REF ScrObject OF ScreenClass,REF Error OF SHORT)
  9595.  
  9596.       An object of the class ScreenClass is placed in a CITScreen object.
  9597.  
  9598.       For the time being CITWindow is the only member of the ScreenClass.
  9599.  
  9600.     
  9601.     PROC RemObject(REF ScrObject OF ScreenClass)
  9602.  
  9603.       Remove a ScreenClass object from the CITScreen
  9604.  
  9605.  
  9606.     PROC Label(t$)
  9607.  
  9608.       Place a text in the drag bar of the screen. This method may be called
  9609.       only before the screen has been inserted in CITWorkbench.
  9610.  
  9611.     
  9612.     PROC Depth(d OF SHORT)
  9613.  
  9614.       Set the  depth (the  number of colors) of the screen. This method may
  9615.       be called only before the screen has been inserted in CITWorkbench.
  9616.  
  9617.  
  9618.     PROC Lores
  9619.  
  9620.       Make the screen a low resolution screen (the horizontal resolution is
  9621.       halfed).   This method  may be called only before the screen has been
  9622.       inserted in CITWorkbench. 
  9623.  
  9624.                                          169
  9625.  
  9626.  
  9627.  
  9628.  
  9629.  
  9630.  
  9631.  
  9632.     PROC Interlace
  9633.  
  9634.       Make the screen an interlace screen (the vertical resolution is doubled).
  9635.       This method may be called only before the screen has been inserted in
  9636.       CITWorkbench. 
  9637.  
  9638.  
  9639.     PROC ToBack
  9640.  
  9641.       Send the screen behind all other screens.  This method  may be called
  9642.       only after the screen has been inserted in CITWorkbench.
  9643.  
  9644.  
  9645.     PROC ToFront
  9646.  
  9647.       Bring the screen in front of all other screens. This method may be cal-
  9648.       led only after the screen has been inserted in CITWorkbench.
  9649.  
  9650.  
  9651.     PROC Font(FontName$,FontHeight OF SHORT)
  9652.  
  9653.       Set the default font of this screen. FontName$ is the name of the font
  9654.       (including the '.font' extension) and FontHeight is the desired height of
  9655.       the font.
  9656.  
  9657.       If the font with the name  and the  specified height  cannot be found
  9658.       nothing will happen.
  9659.  
  9660.  
  9661.   Two predefined  ready to use screens are exported from the CITSreen modu-
  9662.   le: ComalScreen (the screen used by the Comal system )  and WBScreen (the
  9663.   Workbench  screen).  They  are  used  in the same way as other CITScreens
  9664.   (except that they cannot be inserted in or removed from CITWorkbench).
  9665.  
  9666.  
  9667.  
  9668.   11.3.3 CITWindow.
  9669.  
  9670.   In the module CITWindow the object CITWindow is found.
  9671.  
  9672.   CITWindow is member of the ScreenClass  (the  only  member  for  the time
  9673.   being). A  CITWindow has  to be created in a DIM (or LOCAL) statement and
  9674.   inserted in a screen.
  9675.  
  9676.  
  9677.   Example: 
  9678.  
  9679.     DIM DemoWindow OF CITWindow
  9680.  
  9681.                                          170
  9682.  
  9683.  
  9684.  
  9685.  
  9686.  
  9687.     DemoWindow.Size(530,150)
  9688.     ComalScreen.InsObject(DemoWindow,Error)
  9689.  
  9690.  
  9691.   The following methods in CITWindow can be used:
  9692.  
  9693.  
  9694.     PROC InsObject(REF WdObject OF WindowClass,REF Error OF SHORT)
  9695.  
  9696.       An object of the class WindowClass is placed in the CITWindow.
  9697.  
  9698.       All  kinds   of  IDCMP   events  except   MOUSEBUTTON  and  MOUSEMOVE
  9699.       events will be resend to the object as soon as they are recieved by the
  9700.       window.
  9701.  
  9702.     
  9703.     PROC RemObject(REF WdObject OF WindowClass)
  9704.  
  9705.       Remove a WindowClass object from the CITWindow.
  9706.  
  9707.  
  9708.     PROC Position(x OF USHORT,y OF USHORT)
  9709.  
  9710.       Set position of the window. This method may be called both before and
  9711.       after the window has been inserted in a screen.
  9712.  
  9713.  
  9714.     PROC Size(w OF USHORT,h OF USHORT)
  9715.  
  9716.       Set the size of the window. This method may be called both before and
  9717.       after the window has been inserted in a screen.
  9718.  
  9719.  
  9720.     PROC Label(t$)
  9721.  
  9722.       Set the window title. This method may be called both before and after
  9723.       the window has been inserted in a screen.
  9724.  
  9725.  
  9726.     PROC Activate
  9727.  
  9728.       Make window  the active.  This method  may be  called both before and
  9729.       after the window has been inserted in a screen.
  9730.  
  9731.  
  9732.     PROC DepthGadget
  9733.  
  9734.       Make a depth gadget  in the  upper right  corner of  the window. This
  9735.       method may  be called  only before  the window has been inserted in a
  9736.       screen.
  9737.  
  9738.                                          171
  9739.  
  9740.  
  9741.  
  9742.  
  9743.  
  9744.  
  9745.  
  9746.     PROC SizingGadget
  9747.  
  9748.       Make a sizing gadget in the  lower right  corner of  the window. This
  9749.       method may  be called  only before  the window has been inserted in a
  9750.       screen.
  9751.  
  9752.  
  9753.     PROC DragBar
  9754.  
  9755.       Add a drag bar  to the  window (so  that the  window can  be moved by
  9756.       the user).  This method may be called only before the window has been
  9757.       inserted in a screen.
  9758.  
  9759.  
  9760.     PROC ToFront
  9761.  
  9762.       Bring the window in front of  all other  windows on  the screen. This
  9763.       method may  be called  only after  the window  has been inserted in a
  9764.       screen.
  9765.  
  9766.  
  9767.     PROC ToBack
  9768.  
  9769.       Bring the window behind all other windows on the screen.  This method
  9770.       may be called only after the window has been inserted in a screen.
  9771.  
  9772.  
  9773.     PROC CloseGadget
  9774.  
  9775.       Make a  close gadget  in the  upper left  corner of  the window. This
  9776.       method may be called only before  the window  has been  inserted in a
  9777.       screen.
  9778.  
  9779.  
  9780.  
  9781.     FUNC ClosePressed
  9782.  
  9783.       This boolean  function returns  TRUE if  the windows close gadget has
  9784.       been pressed. The status of the gadget will be set to FALSE after the
  9785.       call.
  9786.  
  9787.  
  9788.     PROC CloseEventHandler(p OF CloseEventProc)
  9789.  
  9790.       By calling this method with a procedure p, this procedure will be called
  9791.       immediately if the close gadget is pressed.
  9792.  
  9793.       The parameter p is a procedure without parameters.
  9794.  
  9795.                                          172
  9796.  
  9797.  
  9798.  
  9799.  
  9800.  
  9801.  
  9802.       Example:
  9803.  
  9804.           DemoWindow.CloseEventHandler(CloseEvent)
  9805.  
  9806.             :
  9807.  
  9808.           PROC CloseEvent
  9809.  
  9810.             <do necessary actions>
  9811.  
  9812.           ENDPROC CloseEvent
  9813.  
  9814.  
  9815.     PROC SelectEventHandler(EventProc OF ButtonEventProc)
  9816.  
  9817.       By calling this the method the procedure EventProc will be called when
  9818.       the left mouse button (select button) is pressed.
  9819.  
  9820.       EventProc is an event procedure of the form:
  9821.  
  9822.         PROC Button(Down OF BYTE,x OF SHORT,y OF SHORT)
  9823.  
  9824.       At the  call to the event procedure the parameter Down is TRUE if the
  9825.       button was pressed or FALSE if it was released. x  and y  are the the
  9826.       mouse position coordinates.
  9827.  
  9828.       Example:
  9829.  
  9830.         DemoWindow.SelectEventHandler(Button(,,))
  9831.  
  9832.           :
  9833.  
  9834.         PROC Button(Down OF BYTE,x OF SHORT,y OF SHORT)
  9835.           <do anything>
  9836.         ENDPROC Button
  9837.  
  9838.  
  9839.     PROC MenuEventHandler(EventProc OF ButtonEventProc)
  9840.  
  9841.       By calling this the method the procedure EventProc will be called when
  9842.       the right mouse button (menu button) is pressed.
  9843.  
  9844.       For further description see SelectEventHandler.
  9845.  
  9846.       Note that this method must be called before the window is inserted in
  9847.       the screen.  Alse note  that after calling this you cannot have menus
  9848.       attached to the window.
  9849.  
  9850.  
  9851.  
  9852.                                          173
  9853.  
  9854.  
  9855.  
  9856.  
  9857.  
  9858.     PROC PointerEventHandler(EventProc OF PointerEventProc)
  9859.  
  9860.       If the method MouseMove has been  called with  the actual  value TRUE
  9861.       the EventProc will be called when the mouse pointer is moved.
  9862.  
  9863.       EventProc is an event procedure of the form:
  9864.  
  9865.         PROC MousePos(x OF SHORT,y OF SHORT)
  9866.  
  9867.  
  9868.       At the call to the event procedure the parameters x and y are the the
  9869.       mouse position coordinates.
  9870.  
  9871.       Note that you have to respond to the event very fast.
  9872.  
  9873.  
  9874.     PROC MouseMove(b OF SHORT)
  9875.  
  9876.       Start  mouse  move  event  calling.  As  described  above  your event
  9877.       procedure will be called if the parameter b has the value TRUE.
  9878.  
  9879.  
  9880.     PROC Coordinates(REF x OF SHORT,REF y OF SHORT)
  9881.  
  9882.       This method will return the current position coordinates of the mouse
  9883.       pointer.
  9884.  
  9885.       Example:
  9886.  
  9887.         DemoWindow.EventHandler(MouseMove(,))
  9888.         DemoWindow.MouseMove(TRUE)
  9889.           :
  9890.         PROC MouseMove(x OF SHORT,y OF SHORT)
  9891.           PRINT AT 20,5: USING "x = -### ,  y = -###": x,y,
  9892.         ENDPROC MouseMove
  9893.  
  9894.  
  9895.   A predefined ready to use window  ComalWindow is  exported from  the CIT-
  9896.   Window module. This is the standard IO window.
  9897.  
  9898.   Only the  methods InsObject,  RemObject, ToFront  and ToBack  can be used
  9899.   with ComalWindow  and the  window cannot  be removed  from its containing
  9900.   screen. Otherwise  the window  is used  in almost the same way as CITWin-
  9901.   dows. 
  9902.  
  9903.  
  9904.   11.3.4 CITBorder.
  9905.  
  9906.   The module CITBorder contains the window class objects CITBorder.
  9907.  
  9908.  
  9909.                                          174
  9910.  
  9911.  
  9912.  
  9913.  
  9914.  
  9915.   The CITBorder is used to draw borders in the window and is  a rather spe-
  9916.   cial object that you will probably never use. It is inherited by the CITView
  9917.   and CITText. It contains the following methods:
  9918.  
  9919.  
  9920.     PROC Position(LeftEdge OF SHORT,TopEge OF SHORT)
  9921.  
  9922.       Set the position of the upper left corner of the border. Like gadgets
  9923.       the position coordinates may be negative. The the position of the upper
  9924.       left corner will be placed relative to the right and bottom border of
  9925.       the window.
  9926.  
  9927.  
  9928.     PROC Size(Width OF USHORT,Height OF USHORT,Direc OF USHORT)
  9929.  
  9930.       Set the size of the window. The parameter Direc specifies if the border
  9931.       should be raised (use the value UP), recessed (use the value DOWN) or
  9932.       if there should be no visible border (use the value NOBORDER).
  9933.  
  9934.       The default  size of the border is the size of the containing element
  9935.       (CITWindow or CITView).
  9936.  
  9937.  
  9938.   The CITBorder is inherited  by some  other WindowClass  objects (CITView,
  9939.   CITText and CITGraphics).
  9940.  
  9941.  
  9942.   11.3.5 CITView.
  9943.  
  9944.   The CITView object is a WindowClass object that at first sight looks like
  9945.   the CITBorder (which it iherits) but it is a very special WindowClass object
  9946.   in that any WindowClass object (including the CITView itself) can be inser-
  9947.   ted in (and sometimes removed from) a CITView.
  9948.  
  9949.   A WindowClass object inserted in a CITView is placed relative to the bor-
  9950.   der of the view.
  9951.  
  9952.   The CITBorder  contains the Size and Position methods inherited from CIT-
  9953.   Border as well as InsObject and RemObject (see  CITWindow for  a descrip-
  9954.   tion of these methods).
  9955.  
  9956.  
  9957.   11.3.6 CITGadgets.
  9958.  
  9959.   In this module you will find a number of different gadgets to be inserted in
  9960.   a window.
  9961.  
  9962.   All these gadgets are member of  the class  GadgetClass. Members  of this
  9963.   class have these methods (with some minor individual modifications) along
  9964.   with other special methods:
  9965.  
  9966.                                          175
  9967.  
  9968.  
  9969.  
  9970.  
  9971.  
  9972.  
  9973.     PROC Disable
  9974.  
  9975.       Disables the gadget so that the user cannot use it. Most of the gadgets
  9976.       will appear ghoasted.
  9977.  
  9978.  
  9979.     PROC Enable
  9980.  
  9981.       Enables the gadget.
  9982.  
  9983.  
  9984.     PROC Position(LeftEdge OF SHORT,TopEdge OF SHORT)
  9985.  
  9986.       Set the  position (of the upper left corner of the gadget) inside the
  9987.       window (or view). If inserted in a window the parameters LeftEdge and
  9988.       TopEdge are relative to the inner of a window (excluding borders).
  9989.  
  9990.       If the parameters (one ore both) are negative the position of the gad-
  9991.       gets upper left corner will be relative to the right/lower border of the
  9992.       window (view).
  9993.  
  9994.  
  9995.     PROC Size(Width OF USHORT,Height OF USHORT)
  9996.  
  9997.       Set the width and height of the gadget.
  9998.  
  9999.  
  10000.     PROC Label(text$,Flags OF ULONG)
  10001.  
  10002.       Set a  text to be shown with the gadget. The Flags is used to specify
  10003.       the position and the highlightning status of the text:
  10004.  
  10005.       The position values are
  10006.  
  10007.         LEFT        -   place text to the left of the gadget
  10008.         RIGHT       -   place text to the right of the gadget
  10009.         ABOVE       -   place text above the gadget
  10010.         BELOW       -   place text below the gadget
  10011.         INSIDE      -   place text inside the gadget
  10012.  
  10013.       These position values may be BITORed (or added) with
  10014.  
  10015.         HIGHLIGHT   -   show text highlighted (white)
  10016.  
  10017.  
  10018.     PROC Font(Name$,Height OF SHORT)
  10019.  
  10020.       Set the name of the font to be used in the label. If the font cannot be
  10021.       found the default font (topaz80) will be used.
  10022.  
  10023.                                          176
  10024.  
  10025.  
  10026.  
  10027.  
  10028.  
  10029.  
  10030.  
  10031.     PROC Id(ID OF USHORT)
  10032.  
  10033.       Set an identification number. This number is for your use only.
  10034.  
  10035.  
  10036.     PROC EventHandler(p OF GadEventProc)
  10037.  
  10038.       By calling this method with a procedure p, this procedure will be called
  10039.       immediately if the gadget  is activated  (for input  gadgets when you
  10040.       press the <ENTER> key).
  10041.  
  10042.       The parameter  p is  a procedure with one USHORT parameter (the iden-
  10043.       tifiction  number set by the method Id).
  10044.  
  10045.  
  10046.   All the gadgets (except the TextGadget) have a current state. For all gad-
  10047.   gets this state can be read in the field Value (Value$ in the StringGadget).
  10048.  
  10049.   Note that this Value field should never be changed directly. If it is possible
  10050.   to change it, there will be a method available for this purpose.
  10051.  
  10052.  
  10053.  
  10054.   11.3.6.1 TextGadget.
  10055.  
  10056.   The TextGadget  is a  special read  only gadget. A TextGadget has a fixed
  10057.   label (set by the Label method) and a changeable text.
  10058.  
  10059.   The following methods are special for the TextGadget:
  10060.  
  10061.  
  10062.     PROC Text(t$)
  10063.  
  10064.       Set the (changable) text. The method  may be  called both  before and
  10065.       after the gadget has been inserted in a window.
  10066.  
  10067.  
  10068.     PROC Border
  10069.  
  10070.       Call this method to get a recessed border around the text.
  10071.  
  10072.  
  10073.   Example:
  10074.  
  10075.     DIM Text OF TextGadget
  10076.     Text.Position(214,5)
  10077.     Text.Text("CIT demo")
  10078.     DemoWindow.InsObject(Text,Error)
  10079.  
  10080.                                          177
  10081.  
  10082.  
  10083.  
  10084.  
  10085.  
  10086.  
  10087.   Since this gadget is a read only gadget it makes no sence to add an event
  10088.   procedure to this gadget.
  10089.  
  10090.  
  10091.  
  10092.   11.3.6.2 ButtonGadget.
  10093.  
  10094.   The well known button gadget adds the following method to  all the common
  10095.   methods:
  10096.  
  10097.  
  10098.      FUNC Pressed OF SHORT
  10099.  
  10100.       This boolean  function returns  TRUE if  the gadget has been pressed.
  10101.       The status of the gadget will be set to FALSE after the call.
  10102.  
  10103.  
  10104.  
  10105.   11.3.6.3 CheckboxGadget.
  10106.  
  10107.   The CheckboxGadget has the following methods:
  10108.  
  10109.  
  10110.     PROC On
  10111.  
  10112.       Set the state of the gadget to ON (the check mark will be shown). The
  10113.       method may be called both before and after the gadget has been inser-
  10114.       ted in a window.
  10115.  
  10116.  
  10117.     PROC Off
  10118.  
  10119.       Set the state of the gadget to OFF (the check mark will  be removed).
  10120.       The method  may be  called both  before and after the gadget has been
  10121.       inserted in a window.
  10122.  
  10123.  
  10124.  
  10125.   11.3.6.4 StringGadget.
  10126.  
  10127.   The StringGadget is used to enter a string of ASCII characters. This gadget
  10128.   has the following special method:
  10129.  
  10130.  
  10131.     PROC Replace
  10132.  
  10133.       Use  this  method  to  change  the  typing  mode to the replace mode.
  10134.       Otherwise it is insert mode. The method may only be called before the
  10135.       gadget has been inserted in a window.
  10136.  
  10137.                                          178
  10138.  
  10139.  
  10140.  
  10141.  
  10142.  
  10143.  
  10144.  
  10145.     PROC TabCycle
  10146.  
  10147.       Make the gadget a TabCycle gadget. If the user types Tab or Shift-Tab
  10148.       into a TabCycle gadget the next or previous  TabCycle gadget  will be
  10149.       activated. The  method may  only be called before the gadget has been
  10150.       inserted in a window.
  10151.  
  10152.  
  10153.     PROC MaxChar(n OF USHORT)
  10154.  
  10155.       This method sets the maximum number of input  characters in  the gad-
  10156.       get. The  default number  is 64. The method may only be called before
  10157.       the gadget has been inserted in a window.
  10158.  
  10159.  
  10160.     PROC Text(t$)
  10161.  
  10162.       Set the content of the gadgets input field. The method  may be called
  10163.       both before and after the gadget has been inserted in a window.
  10164.  
  10165.  
  10166.     PROC Activate
  10167.  
  10168.       Activate the gadget so that you can type in your text. The method may
  10169.       only be called after the gadget has been inserted in a window.
  10170.  
  10171.  
  10172.   Example:
  10173.  
  10174.     DIM StringGad OF StringGadget
  10175.     StringGad.Label("Type in a text",LEFT)
  10176.     StringGad.Position(150,48)
  10177.     StringGad.Size(170,15)
  10178.     DemoWindow.InsObject(StringGad,Error)
  10179.  
  10180.  
  10181.  
  10182.   11.3.6.5 IntegerGadget.
  10183.  
  10184.   The IntegerGadget is used to enter an integer number. This gadget has the
  10185.   following special method:
  10186.  
  10187.  
  10188.     PROC Replace
  10189.  
  10190.       Use  this  method  to  change  the  typing  mode to the replace mode.
  10191.       Otherwise it is insert mode. The method may only be called before the
  10192.       gadget has been inserted in a window.
  10193.  
  10194.                                          179
  10195.  
  10196.  
  10197.  
  10198.  
  10199.  
  10200.  
  10201.  
  10202.     PROC TabCycle
  10203.  
  10204.       Make the gadget a TabCycle gadget. If the user types Tab or Shift-Tab
  10205.       into a TabCycle gadget the next or previous  TabCycle gadget  will be
  10206.       activated. The  method may  only be called before the gadget has been
  10207.       inserted in a window.
  10208.  
  10209.  
  10210.     PROC MaxChar(n OF USHORT)
  10211.  
  10212.       This method sets the maximum number of input  characters in  the gad-
  10213.       get. The  default number  is 64. The method may only be called before
  10214.       the gadget has been inserted in a window.
  10215.  
  10216.  
  10217.     PROC Number(n OF ULONG)
  10218.  
  10219.       Set the content of the gadgets input field. The method  may be called
  10220.       both before and after the gadget has been inserted in a window.
  10221.  
  10222.  
  10223.     PROC Activate
  10224.  
  10225.       Activate the  gadget so  that you can type in your number. The method
  10226.       may only be called after the gadget has been inserted in a window.
  10227.  
  10228.  
  10229.  
  10230.   11.3.6.6 SliderGadget.
  10231.  
  10232.   A SliderGadget is a gadget used  to show  or control  the amount  of some
  10233.   quantity like a color, a volume or an intensity.
  10234.  
  10235.   This gadget has the following methods:
  10236.  
  10237.  
  10238.     PROC Limits(Min OF SHORT,Max OF SHORT)
  10239.     
  10240.       The method is used to set the level limits, i.e. the minimum and maxi-
  10241.       mum value of the quantity in question. The method may  only be called
  10242.       before the gadget has been inserted in a window.
  10243.  
  10244.  
  10245.     PROC Level(l OF SHORT)
  10246.  
  10247.       The method is use to set the actual level of the quantity. The method
  10248.       may be called both before and after the gadget has been inserted in a
  10249.       window.
  10250.  
  10251.                                          180
  10252.  
  10253.  
  10254.  
  10255.  
  10256.  
  10257.  
  10258.  
  10259.   In the  string used as parameter in the Label method (common for all gad-
  10260.   gets) you may place  the formatting  characters '#'  as in  a PRINT USING
  10261.   statement. Then the current level will be printed.
  10262.  
  10263.  
  10264.   Example:
  10265.  
  10266.       DIM SliderGad OF SliderGadget
  10267.       SliderGad.Position(150,88)
  10268.       SliderGad.Limits(0,100)
  10269.       SliderGad.Label("Fraction:###%",LEFT)
  10270.       DemoWindow.InsObject(SliderGad,Error)
  10271.  
  10272.     As a result of the line 
  10273.  
  10274.         SliderGad.Label("Fraction:###%",LEFT)
  10275.  
  10276.     a text of the form
  10277.  
  10278.         Fraction: 37%
  10279.  
  10280.     will be printed on the left side of the gadget.
  10281.  
  10282.  
  10283.  
  10284.   11.3.6.7 ScrollerGadget.
  10285.  
  10286.   A ScrollerGadget  is a gadget used to show and/or adjust the fraction and
  10287.   the position of a limited view into a larger area. The ScrollerGadget is a
  10288.   well known gadget. It is placed on the right side of the Comal editor win-
  10289.   dow and it is used in all the drawer windows opened by Workbench
  10290.  
  10291.   This gadget has the following methods:
  10292.  
  10293.  
  10294.     PROC Top(t OF SHORT)
  10295.  
  10296.       Sets the first visible position in the area that the scroller represents.
  10297.       The method  may be  called both  before and after the gadget has been
  10298.       inserted in a window.
  10299.  
  10300.  
  10301.     PROC Total(t OF SHORT)
  10302.  
  10303.       Sets the total size of the area that the scroller represents. The method
  10304.       may be called both before and after the gadget has been inserted in a
  10305.       window.
  10306.  
  10307.  
  10308.                                          181
  10309.  
  10310.  
  10311.  
  10312.  
  10313.  
  10314.  
  10315.     PROC Visible(v OF SHORT)
  10316.  
  10317.       Sets the number of visible elements.  The method  may be  called both
  10318.       before and after the gadget has been inserted in a window.
  10319.  
  10320.  
  10321.     PROC Arrows(Size OF SHORT)
  10322.  
  10323.       Place arrows at the end of the scroller. The parameter is the width of
  10324.       each arrow button for a horizontal scroller or the height for a vertical
  10325.       scroller. The  default size  is 10. Use a size value of zero to avoid
  10326.       arrows.
  10327.  
  10328.       The method may only be called before the gadget has  been inserted in
  10329.       a window.
  10330.  
  10331.  
  10332.     PROC Orientation(Or OF SHORT)
  10333.  
  10334.       Set the orientation of the scroller, The parameter values are:
  10335.  
  10336.         HORIZONTAL    -   make a horizontal scroller
  10337.         VERTICAL      -   make a vertical scroller
  10338.  
  10339.       The default orientation is horizontal.
  10340.  
  10341.       The method  may only be called before the gadget has been inserted in
  10342.       a window.
  10343.  
  10344.  
  10345.   The value found in the field Value is the current Top value.
  10346.  
  10347.  
  10348.   Example: Let's say we have a text of 137 lines (numbered 0 .. 136) and we
  10349.     can see 21 lines on the display (currently from line 32 to 52). The fol-
  10350.     lowing lines will create a scroller representing the text:
  10351.  
  10352.       DIM Scroler OF ScrollerGadget
  10353.       Scroller.Position(500,5)
  10354.       Scroller.Size(15,150)
  10355.       Scroller.Total(137)             // A total of 137 lines
  10356.       Scroller.Top(32)                // First visible (counting from zero)
  10357.       Scroller.Visible(21)            // 21 visible lines
  10358.       Scroller.Orientation(VERTICAL)
  10359.       DemoWindow.InsObject(Scroller,Error)
  10360.  
  10361.  
  10362.  
  10363.  
  10364.  
  10365.                                          182
  10366.  
  10367.  
  10368.  
  10369.  
  10370.  
  10371.   11.3.6.8 CycleGadget.
  10372.  
  10373.   A CycleGadget is used to allow the user to choose one among several choi-
  10374.   ces. It appears as a raised rectangular button. A circular arrow glyph ap-
  10375.   pears to the left and the current choice to the right. Clicking once on the
  10376.   gadget the next choice in a list will appear, while shift-clicking will show
  10377.   the previous choice.
  10378.  
  10379.   This gadget has the following methods:
  10380.  
  10381.  
  10382.     PROC Choices(REF Texts$())
  10383.  
  10384.       The texts in the array Texts$() (all texts or up to the first empty text)
  10385.       is the choices that will appear in the gadget. These texts must be valid
  10386.       through the whole lifetime of the gaget.
  10387.  
  10388.       The method may be called both  before and  after the  gadget has been
  10389.       inserted in a window.
  10390.  
  10391.  
  10392.     PROC Active(n OF SHORT)
  10393.  
  10394.       Sets the choice with the ordinal number n (counting from zero) as the
  10395.       active choice in the gadget.  The method may be called both before and
  10396.       after the gadget has been inserted in a window.
  10397.  
  10398.  
  10399.   Example:
  10400.  
  10401.     DIM CycleChoice$(4) OF 20
  10402.     READ CycleChoice$()
  10403.     DATA "Choice number 1"
  10404.     DATA "Choice number 2"
  10405.     DATA "Choice number 3"
  10406.     DATA "Choice number 4"
  10407.  
  10408.     DIM CycleGad OF CycleGadget
  10409.     CycleGad.Position(330,8)
  10410.     CycleGad.Size(190,14)
  10411.     CycleGad.Label("Press here",LEFT)
  10412.     CycleGad.Choices(CycleChoice$())
  10413.     CycleGad.Active(2)                    // 'Choice number 3'
  10414.     DemoWindow.InsObject(CycleGad,Error)
  10415.  
  10416.  
  10417.   11.3.6.9 RadioButtonGadget.
  10418.  
  10419.   Like the  CycleGadget the  RadioButtonGadget allow the user to choose one
  10420.   option from among several.
  10421.  
  10422.                                          183
  10423.  
  10424.  
  10425.  
  10426.  
  10427.  
  10428.  
  10429.   All the choices are shown as a text beside a small raised oval that looks
  10430.   like a small radio button. Exactly one one button is recessed and highligh-
  10431.   ted to indicate the selected choice.
  10432.  
  10433.   This gadget has the following methods:
  10434.  
  10435.  
  10436.     PROC Choices(REF Texts$(),Place OF ULONG)
  10437.  
  10438.       The texts in the array Texts$() (all texts or up to the first empty text)
  10439.       is the choices that will appear. These texts must be valid through the
  10440.       whole lifetime of the gaget.
  10441.  
  10442.       The parameter Place specifies  where the  text is  to be  placed. The
  10443.       values are:
  10444.  
  10445.         LEFT  - place text on the left side of the buttons
  10446.         RIGHT - place text on the right side of the buttons
  10447.  
  10448.       The method  may only be called before the gadget has been inserted in
  10449.       a window.
  10450.  
  10451.  
  10452.     PROC Spacing(s OF SHORT)
  10453.  
  10454.       Sets the amount of spacing (in pixels) between each button. The default
  10455.       value is zero (not very nice). The method may only be called before the
  10456.       gadget has been inserted in a window.
  10457.  
  10458.  
  10459.     PROC Active(n OF SHORT)
  10460.  
  10461.       Sets the choice with the ordinal number n (counting from zero) as the
  10462.       active choice in the gadget. The method may be called both before and
  10463.       after the gadget has been inserted in a window.
  10464.  
  10465.  
  10466.   11.3.6.10 ListViewGadget.
  10467.  
  10468.   A ListViewGadget, like the CycleGadget and  the RadioButtonGadget, allows
  10469.   the user to select one among several choices. It consists of a scroller with
  10470.   arrows, an area where the choices are visible and an optional place where
  10471.   the current selection is shown. The user can browse through the list using
  10472.   the scroller or the arrows and may select  an entry  by clicking  on that
  10473.   item.
  10474.  
  10475.   This gadget has the following methods:
  10476.  
  10477.  
  10478.  
  10479.                                          184
  10480.  
  10481.  
  10482.  
  10483.  
  10484.  
  10485.     PROC ChoiceArray(REF Texts$())
  10486.  
  10487.       The texts in the array Texts$() (all texts or up to the first empty text)
  10488.       is the choices that will appear in the gadget. These texts must be valid
  10489.       through the whole lifetime of the gaget.
  10490.  
  10491.       The method  may be  called both  before and after the gadget has been
  10492.       inserted in a window.
  10493.  
  10494.  
  10495.     PROC ChoiceList(REF List OF List)
  10496.  
  10497.       This is an alternative way of supplying the choices. The  choices are
  10498.       put ito the ln_Name field of an Exec list.
  10499.  
  10500.       The method  may be  called both  before and after the gadget has been
  10501.       inserted in a window.
  10502.  
  10503.  
  10504.     PROC Spacing(s OF USHORT)
  10505.  
  10506.       Sets the amount of spacing (in pixels) between each entry in the list-
  10507.       view. The default value is zero. The method may only be called before
  10508.       the gadget has been inserted in a window.
  10509.  
  10510.  
  10511.     PROC Top(n OF USHORT)
  10512.  
  10513.       The ordinal number (counting from zero) of the top item visible in the
  10514.       listview. The  method may  be called both before and after the gadget
  10515.       has been inserted in a window.
  10516.  
  10517.  
  10518.     PROC ScrollWidth(w OF USHORT)
  10519.  
  10520.       Sets the width of the scroller used in the listview. The method may be
  10521.       called only before the gadget has been inserted in a window.
  10522.  
  10523.  
  10524.     PROC ReadOnly
  10525.  
  10526.       Make the listview a read-only listview. The method may be called only
  10527.       before the gadget has been inserted in a window.
  10528.  
  10529.  
  10530.     PROC ShowSelected(REF StrgGad OF StringGadget)
  10531.  
  10532.       Use this method to attach a StringGadget to the listview. The currently
  10533.       selected item  will be  shown in the gadget (ready to be edited). The
  10534.       parameter StrgGad must have been created  (in a  DIM or  LOCAL state-
  10535.  
  10536.                                          185
  10537.  
  10538.  
  10539.  
  10540.  
  10541.  
  10542.       ment) but not inserted in a window.
  10543.  
  10544.       The method  may be called only before the gadget has been inserted in
  10545.       a window.
  10546.  
  10547.  
  10548.     PROC Selected(s OF USHORT)
  10549.  
  10550.       Ordinal number (counting from zero) of the item to be placed into the
  10551.       display under the listview.
  10552.  
  10553.       The method  may be  called both  before and after the gadget has been
  10554.       inserted in a window. If called before without a prior call of the Show-
  10555.       Selected method, a readonly TextGadget will be created.
  10556.  
  10557.  
  10558.   Example:
  10559.  
  10560.     DIM ListViewTexts$(4) OF 20
  10561.     ListViewTexts$(1):="Choice1"
  10562.     ListViewTexts$(2):="Choice2"
  10563.     ListViewTexts$(3):="Choice3"
  10564.     ListViewTexts$(4):="Choice4"
  10565.  
  10566.     DIM ListView OF ListViewGadget
  10567.     ListView.Position(200,128)
  10568.     ListView.Size(100,40)
  10569.     ListView.ChoiceArray(ListViewTexts$())
  10570.     ListView.Selected(1)                    // A TextGadget is created
  10571.     DemoWindow.InsObject(ListView,Error)
  10572.  
  10573.  
  10574.  
  10575.   11.3.6.11 PaletteGadget.
  10576.  
  10577.   The PaletteGadget lets the user pick a colour from a set of several. It con-
  10578.   sists of a number of coloured squares, one for each colour available.
  10579.  
  10580.   This gadget has the following methods:
  10581.  
  10582.  
  10583.     PROC Color(c OF UBYTE)
  10584.  
  10585.       The selected colour of the palette. Default is zero.
  10586.  
  10587.       The method may be called both  before and  after the  gadget has been
  10588.       inserted in a window.
  10589.  
  10590.  
  10591.  
  10592.  
  10593.                                          186
  10594.  
  10595.  
  10596.  
  10597.  
  10598.  
  10599.     PROC IndicatorWidth(w)
  10600.  
  10601.       Specifies the width of the current-colour indicator. The default width is
  10602.       20 pixels.
  10603.  
  10604.       The method may be called only before the gadget has  been inserted in
  10605.       a window.
  10606.  
  10607.  
  10608.     PROC IndicatorHeight(h)
  10609.  
  10610.       This method asks for a current-colour indicator to be placed above the
  10611.       the colour selection squares. The height is specified as a parameter.
  10612.  
  10613.       The method may be called only before the gadget has  been inserted in
  10614.       a window.
  10615.  
  10616.  
  10617.     PROC Depth(d OF SHORT)
  10618.  
  10619.       Specifies the number of bitplanes that the gadget represents. Default is
  10620.       two. The method may be called only before the gadget  has been inser-
  10621.       ted in a window.
  10622.  
  10623.  
  10624.     PROC ColorOffset(Offset OF SHORT)
  10625.  
  10626.       If there are more bitplanes in the screen than specified by the Depth
  10627.       method this is the number of the first colour to be displayed. Default
  10628.       is zero.
  10629.  
  10630.       The method  may be called only before the gadget has been inserted in
  10631.       a window.
  10632.  
  10633.  
  10634.   Example:
  10635.     DIM Palette OF PaletteGadget
  10636.     Palette.Position(350,128)
  10637.     Palette.Color(2)                      // Color 2 is the selected one
  10638.     DemoWindow.InsObject(Palette,Error)
  10639.  
  10640.  
  10641.  
  10642.   11.3.7 CITText.
  10643.  
  10644.   The module CITText contains the window class object CITText.
  10645.  
  10646.   The CITText is used to write texts in  the window.  It contains  the same
  10647.   methods as  CITBorder (it  inherits CITBorder)  as well  as the following
  10648.   methods:
  10649.  
  10650.                                          187
  10651.  
  10652.  
  10653.  
  10654.  
  10655.  
  10656.  
  10657.  
  10658.     PROC PenColor(c OF SHORT)
  10659.  
  10660.       Set the colour of the drawing pen.
  10661.  
  10662.  
  10663.     PROC BackColor(c OF SHORT)
  10664.  
  10665.       Set the colour of the back ground pen. This value is only used if the
  10666.       method Transparent is called with the parameter value FALSE.
  10667.  
  10668.  
  10669.     PROC Transparent(b OF SHORT)
  10670.  
  10671.       If b has the value TRUE the letters are drawn transparent, i.e. no back
  10672.       ground is drawn.
  10673.  
  10674.  
  10675.     PROC Font(Name$,Height OF SHORT)
  10676.  
  10677.       Set the name of the font to be used. If the font cannot be  found the
  10678.       default font (topaz80) will be used.
  10679.  
  10680.  
  10681.     PROC Print(x OF SHORT,y OF SHORT,t$)
  10682.  
  10683.       Print the text t$ at position x,y.
  10684.  
  10685.  
  10686.   Example:
  10687.  
  10688.     DIM Text OF CITText
  10689.     Text.Position(100,50)
  10690.     Text.Size(250,50,DOWN)
  10691.     DemoWindow.InsObject(Text,Error)
  10692.  
  10693.     Text.PenColor(3)
  10694.     Text.Font("times.font",24)
  10695.     Text.Print(10,10,"Hello world!")
  10696.  
  10697.  
  10698.  
  10699.   11.3.8 CITGraphics.
  10700.  
  10701.   CITGraphics in the module CITGraphics is a window class object containing
  10702.   a (very small) subset of the graphics routines of the Graphics module.
  10703.  
  10704.   It contains the same methods as CITText (it inherits CITText)  as well as
  10705.   the following methods:
  10706.  
  10707.                                          188
  10708.  
  10709.  
  10710.  
  10711.  
  10712.  
  10713.  
  10714.     PROC Clear
  10715.  
  10716.       Clear the graphics area defined by Position and Size.
  10717.  
  10718.  
  10719.     PROC Color(c OF SHORT)
  10720.  
  10721.       Set the color of the drawing pen.
  10722.  
  10723.  
  10724.     PROC MoveTo(x,y)
  10725.  
  10726.       Move (without drawing) the pen to the point with coordinates (x,y).
  10727.  
  10728.  
  10729.     PROC DrawTo(x,y)
  10730.  
  10731.       Draw a straight line from the current point to the point with coordina-
  10732.       tes (x,y).
  10733.  
  10734.  
  10735.     PROC Plot(x,y)
  10736.  
  10737.       Set a dot at the point with coordinates (x,y).
  10738.  
  10739.  
  10740.     PROC DrawText(x,y,t$)
  10741.  
  10742.       Print a text starting at the graphics coordinates (x,y). The Print me-
  10743.       thod of CITText is used to actually print the text.
  10744.  
  10745.  
  10746.     PROC Coordinates(Xmin,Xmax,Ymin,Ymax)
  10747.  
  10748.       Define a  new coordinate  system. Xmin and Xmax will be the new x-co-
  10749.       ordinates of the left and right edge of the drawing area. Ymin will be
  10750.       the new  y-coordinate of  the bottom edge and Ymax wil be the y-coor-
  10751.       dinate of the top edge.
  10752.  
  10753.  
  10754.   In CITGraphics all drawing are restricted to drawing area set by the Size
  10755.   method. This is also the case with DrawText.
  10756.  
  10757.  
  10758.   11.3.9 CITMenus.
  10759.  
  10760.   CITMenu in  the module  CITMenus is  a window  class object  used to make
  10761.   menus in a window. It contains the following methods:
  10762.  
  10763.  
  10764.                                          189
  10765.  
  10766.  
  10767.  
  10768.  
  10769.  
  10770.  
  10771.     PROC Title(Label$,Flags OF USHORT,REF MenuId OF USHORT)
  10772.  
  10773.       Set the title of a new menu. The parameters are:
  10774.  
  10775.         Label$
  10776.  
  10777.           The title (the headline) of a new series of menu items.
  10778.  
  10779.         Flags
  10780.  
  10781.           The only legal non zero value is
  10782.  
  10783.             DISABLED    disable this menu (all items and subitems) from start.
  10784.                         The menu can be enabled by calling the method On.
  10785.  
  10786.         MenuId
  10787.  
  10788.             An identification number is returned in this variable. The value is
  10789.             used in calls to the On and Off methods.
  10790.  
  10791.  
  10792.     PROC Item(Label$,Key$,Flags OF USHORT,Exlude OF LONG,
  10793.                               Prc OF MenuEvent,REF MenuId OF USHORT)
  10794.  
  10795.       Make a new menu item belonging to the menu created  by the  last call
  10796.       of the method Title. The parameters are
  10797.  
  10798.         Label$
  10799.  
  10800.           The name of the menu item.
  10801.  
  10802.         Key$
  10803.  
  10804.           The first character in this string is used as a short cut for the
  10805.           menu item. If the string is the empty string there will be no short
  10806.           cut for this item.
  10807.  
  10808.         Flags
  10809.  
  10810.           This parameter  can be  zero or it can take on one or more of the
  10811.           following values:
  10812.  
  10813.             DISABLED    Disable the item (and all subitems belonging to it)
  10814.                         from start.  The item can be enabled by calling the
  10815.                         method On.
  10816.  
  10817.             CHECKIT     A check mark will be drawn to the left of the title
  10818.                         if the item is currently selected.
  10819.  
  10820.  
  10821.                                          190
  10822.  
  10823.  
  10824.  
  10825.  
  10826.  
  10827.             MENUTOGGLE  By using  this value  the user can toggle the check
  10828.                         mark by selecting the item. Only to be used in con-
  10829.                         nection with the CHECKIT flag value.
  10830.  
  10831.                         Normally you  will use this flag in connection with
  10832.                         the CHECKIT flag or you will set an exclude mask.
  10833.  
  10834.             CHECKED     Make the item selected from start. Only to  be used
  10835.                         in connection with the CHECKIT flag value.
  10836.  
  10837.           The values can be BITORed (or added) together.
  10838.  
  10839.         Exclude
  10840.  
  10841.           Set a  1 in  a binary bitmask for each item in this (sub)menu you
  10842.           want to be deselected when the user selects this item. The right-
  10843.           most digit in the bitmask corresponds to the first item. Only to be
  10844.           used in connection with the CHECKIT flag value.
  10845.  
  10846.         Prc
  10847.  
  10848.           This is an event procedure with  one unsigned  short (USHORT) pa-
  10849.           rameter. This procedure will be called when the item is selected.
  10850.  
  10851.           At the call the actual parameter value will be the menu number re-
  10852.           turned in the REF parameter MenuId. In this way you  can identify
  10853.           the item if several items (or subitems) shares an event procedure.
  10854.  
  10855.         MenuId
  10856.  
  10857.           An identification number is returned in this variable. The value is
  10858.           used in calls to the On and Off methods.
  10859.  
  10860.  
  10861.     PROC SubItem(Label$,Key$,Flags OF USHORT,Exlude OF LONG,
  10862.                               Prc OF MenuEvent,REF MenuId OF USHORT)
  10863.  
  10864.       Create a subitem belonging to the last item.  The parameters  are the
  10865.       same as described above (the Item method).
  10866.  
  10867.  
  10868.     PROC Bar
  10869.  
  10870.       Make a separator bar between the previous and the next (sub)item.
  10871.  
  10872.  
  10873.     PROC On(MenuId OF USHORT)
  10874.  
  10875.       Enable the  menu or (sub)item identified by MenuId (the number retur-
  10876.       ned by calls to the methods Title, Item and SubItem).
  10877.  
  10878.                                          191
  10879.  
  10880.  
  10881.  
  10882.  
  10883.  
  10884.  
  10885.  
  10886.     PROC Off(MenuId OF USHORT)
  10887.  
  10888.       Disable the menu or (sub)item identified by MenuId (the number retur-
  10889.       ned by calls to the methods Title, Item and SubItem).
  10890.  
  10891.  
  10892.   Example:  This example  shows part of a program (most of the event proce-
  10893.     dures are not shown) creates a menu in the standard IO window.  
  10894.  
  10895.  
  10896.       USE CITWindow
  10897.       USE CITMenus
  10898.  
  10899.       DIM Terminate OF SHORT
  10900.  
  10901.       DIM Menu OF CITMenu
  10902.       Menu.Title("Project",0,ProjectId)
  10903.       Menu.Item("Open","O",0,0,PrcOpen(),OpenId)
  10904.       Menu.Item("Save","",0,0,PrcSave(),SaveId)
  10905.       Menu.Bar
  10906.       Menu.Item("Print Mode","",0,0,PrcMode(),ModeId)
  10907.       Menu.SubItem("Draft","",CHECKIT+CHECKED,%10,PrcMode(),DraftId)
  10908.       Menu.SubItem("NLQ","",CHECKIT,%01,PrcMode(),NLQId)
  10909.       Menu.Item("Print","P",0,0,PrcPrint(),PrintId)
  10910.       Menu.Bar
  10911.       Menu.Item("Quit","Q",0,0,PrcQuit(),QuitId)
  10912.       Menu.Title("Edit",0,EditId)
  10913.       Menu.Item("Cut","X",0,0,PrcCut(),CutId)
  10914.       Menu.Item("Copy","C",0,0,PrcCopy(),CopyId)
  10915.       Menu.Item("Paste","V",0,0,PrcPaste(),PasteId)
  10916.       Menu.Bar
  10917.       Menu.Item("Undo","Z",0,0,PrcUndo(),UndoId)
  10918.       ComalWindow.InsObject(Menu,Error)
  10919.  
  10920.       IF Error THEN
  10921.         PRINT "Could not create menu"
  10922.       ELSE
  10923.         WHILE NOT Terminate DO WAIT
  10924.         ComalWindow.RemObject(Menu)
  10925.       ENDIF
  10926.  
  10927.       // *********** Event procedures ************
  10928.  
  10929.       PROC PrcQuit(Num OF USHORT)
  10930.         Terminate:=TRUE
  10931.       ENDPROC PrcQuit
  10932.  
  10933.       PROC PrcOpen(Num OF USHORT)
  10934.  
  10935.                                          192
  10936.  
  10937.  
  10938.  
  10939.  
  10940.  
  10941.         :
  10942.       ENDPROC PrcOpen
  10943.  
  10944.       PROC PrcSave(Num OF USHORT)
  10945.         :
  10946.  
  10947.  
  10948.  
  10949.  
  10950.   11.3.10 CITRequester.
  10951.  
  10952.   CITRequester in the module CITRequesters is a window class object used to
  10953.   make system requesters in a window. It contains only one method:
  10954.  
  10955.  
  10956.       FUNC Request(Text$,YesNo$) OF LONG
  10957.  
  10958.         The parameters are:
  10959.  
  10960.         Text$:  This is the body text of the requester. This text may contain
  10961.                 C-language formatting characters, or the new line character,
  10962.                 CHR$(10).
  10963.  
  10964.         YesNo$: The gadget  text for  one or more gadgets in the requester.
  10965.                 Each gadget text is separated by the chracter '|'.
  10966.  
  10967.         The return value is zero if the rightmost gadget was pressed. Other-
  10968.         wise the return value is the number of the gadget (counting from the
  10969.         left).
  10970.  
  10971.         Example:
  10972.  
  10973.           DIM Rq OF CITRequester
  10974.  
  10975.             :
  10976.  
  10977.           CASE Rq.Request("Text modified"10"Save text?","Yes|No|Cancel") OF
  10978.           WHEN 0
  10979.  
  10980.             :
  10981.  
  10982.           WHEN 1
  10983.  
  10984.             :
  10985.  
  10986.           WHEN 2
  10987.  
  10988.             :
  10989.  
  10990.           ENDCASE
  10991.  
  10992.                                          193
  10993.  
  10994.  
  10995.  
  10996.  
  10997.  
  10998.  
  10999.  
  11000.   11.4 Creating your own CIT classes.
  11001.  
  11002.   In principle it is a simple task to make new CIT types belonging to one of
  11003.   the excisting CITClasses: WorkbenchClass, ScreenClasss, WindowClass etc.
  11004.  
  11005.   But before we can do this it is necessary to know a little more about how
  11006.   CIT works.
  11007.  
  11008.   All the CIT classes (except the base class CITWorkbench) contain two cen-
  11009.   tral methods:
  11010.  
  11011.       FUNC CreateObject(REF Alfa OF CITAlfa, .. ) OF SHORT VIRTUAL
  11012.  
  11013.       PROC DeleteObject VIRTUAL
  11014.  
  11015.  
  11016.   and in addition all the WindowClasses contain an event method:
  11017.  
  11018.       PROC HandleEvent(REF Msg OF IntuiMessage) VIRTUAL
  11019.  
  11020.  
  11021.   The value  of the  first parameter in the CreateObject method is the con-
  11022.   tainer object into which this object is to be placed. This method may have
  11023.   some other parameters as indicated.
  11024.  
  11025.   As can be seen in a lot of examples, an AlfaClass object is inserted in a
  11026.   CITAlfa object by executing a line of the form:
  11027.  
  11028.     Alfa.InsObject(AlfaClassObject,Error)
  11029.  
  11030.  
  11031.   The method InsObject now calls the method CreateObject in AlfaClassObject
  11032.   and it is in fact this method that does the actual insertion. After a succes-
  11033.   full return from CreateObject the container object Alfa inserts the the new
  11034.   object in a book keeping list such that it knows which objects are current-
  11035.   ly inserted.
  11036.  
  11037.   It can also be seen from the examples, that an AlfaClass object is removed
  11038.   from a CITAlfa object by executing a line of the form:
  11039.  
  11040.     Alfa.RemObject(AlfaClassObject)
  11041.  
  11042.  
  11043.   The method  RemObject now  calls the  method DeleteObject in AlfaClassOb-
  11044.   ject and after that removes it from its book keeping list. If AlfaClassObject
  11045.   itself contains inserted object the DeleteObject method in AlfaClassObject
  11046.   has to remove all its inserted objects (i.e. it calls the DeleteObject method
  11047.   in all the inserted object).
  11048.  
  11049.                                          194
  11050.  
  11051.  
  11052.  
  11053.  
  11054.  
  11055.  
  11056.   If an  AlfaClass event occurs, the object Alfa traverses the book keeping
  11057.   list and calls the HandleEvent method in all the inserted  objects one by
  11058.   one.
  11059.  
  11060.   An important  requiremet for  this to work with many different objects is
  11061.   that the methods CreateObject, DeleteObject and  HandleEvent are declared
  11062.   as virtual methods.
  11063.  
  11064.   To make a new AlfaClass type you have to define a structure that inherits
  11065.   the base class AlfaClass or one of its ancestors. In this structure you will
  11066.   probably define new data fields and you are likely to overload one or more
  11067.   of the virtual methods CreateObject, DeleteObject and HandleEvent.
  11068.  
  11069.   Here is a typical example:
  11070.  
  11071.     STRUC ExtAlfa
  11072.       INHERIT AlfaClass
  11073.  
  11074.           :
  11075.       < some data fields >
  11076.           :
  11077.  
  11078.       FUNC CreateObject(REF Alfa OF CITAlfa) OF SHORT VIRTUAL
  11079.  
  11080.         // First create the ancestor object
  11081.         IF AlfaClass.CreateObject(Alfa) THEN
  11082.  
  11083.           < do other ExtAlfa specific creation >
  11084.  
  11085.           RETURN TRUE
  11086.         ELSE
  11087.           RETURN FALSE
  11088.         ENDIF
  11089.  
  11090.       ENDFUNC CreateObject
  11091.  
  11092.       PROC DeleteObject VIRTUAL
  11093.  
  11094.         < do ExtAlfa specific deletion >
  11095.  
  11096.         // Finally delete the ancestor object
  11097.         AlfaClass.DeleteObject
  11098.  
  11099.       ENDPROC DeleteObject
  11100.  
  11101.       < other methods >
  11102.  
  11103.     ENDSTRUC ExtAlfa
  11104.  
  11105.  
  11106.                                          195
  11107.  
  11108.  
  11109.  
  11110.  
  11111.  
  11112.  
  11113.   Note that the base class AlfaClass defined in connection with the definition
  11114.   of the  CITAlfa type  is only a skeleton. It would not make much sence to
  11115.   create an object of this type (although it is possible). It is defined as fol-
  11116.   low:
  11117.  
  11118.  
  11119.     STRUC AlfaClass
  11120.       METHODTABLE
  11121.  
  11122.       DIM CITAlfa OF POINTER TO CITAlfa
  11123.  
  11124.       PROC Terminate DESTRUCTOR
  11125.         IF CITAlfa THEN
  11126.           LOCAL AlfaClass OF POINTER TO AlfaClass
  11127.  
  11128.           AlfaClass:=ADR(CITAlfa)-4
  11129.           CITAlfa@.RemObject(AlfaClass@)
  11130.         ENDIF
  11131.       ENDPROC Terminate
  11132.  
  11133.       FUNC CreateObject(REF Alfa OF CITAlfa, .. ) OF SHORT VIRTUAL
  11134.         CITAlfa:=ADR(Alfa)
  11135.         RETURN TRUE
  11136.       ENDFUNC CreateObject
  11137.  
  11138.       PROC DeleteObject VIRTUAL
  11139.         CITAlfa:=0
  11140.       ENDPROC DeleteObject
  11141.  
  11142.       PROC HandleEvent(REF Msg OF IntuiMessage) VIRTUAL
  11143.       ENDPROC HandleEvent
  11144.  
  11145.     ENDSTRUC AlfaClass
  11146.  
  11147.  
  11148.   The CreateObject method stores a pointer to the container object (you are
  11149.   free to use this in your own extensions) and DeleteObject deletes this poin-
  11150.   ter. The destructor Terminate removes the object if the object is going to
  11151.   loose its data area (at return from a procedure for instance).
  11152.  
  11153.   The HandleEvent method is only present in the WindowClass.
  11154.  
  11155.   You should look into  the modules  CITWorkbench, CITScreen  and CITWindow
  11156.   to see  the actual definitions (there are some minor differences from the
  11157.   general scheme) and to see what the content of the actual container object
  11158.   is.
  11159.  
  11160.  
  11161.  
  11162.  
  11163.                                          196
  11164.  
  11165.  
  11166.  
  11167.  
  11168.  
  11169.   Example:  As a  complete example we will make an extension of the CITWin-
  11170.     dow (a member of the ScreenClass). This extension  should have  a fixed
  11171.     default position and size and an Ok-button in the lower left corner.
  11172.  
  11173.     In addition  there should be a method Wait. This method will wait until
  11174.     the Ok-button has been pressed.
  11175.  
  11176.     The definition could be made in this way:
  11177.  
  11178.  
  11179.       STRUC MyWindow
  11180.         INHERIT CITWindow
  11181.  
  11182.         USE CITGadgets
  11183.         USE IntuitionScreen
  11184.  
  11185.         DIM CloseButton OF ButtonGadget
  11186.  
  11187.         FUNC Init CONSTRUCTOR
  11188.           NewWindow.LeftEdge:=50
  11189.           NewWindow.TopEdge:=30
  11190.           NewWindow.Width:=500
  11191.           NewWindow.Height:=150
  11192.           CloseButton.Size(60,14)
  11193.           CloseButton.Position(5,-(14+3))
  11194.           CloseButton.Label("STOP",INSIDE)
  11195.           RETURN TRUE
  11196.         ENDFUNC Init
  11197.  
  11198.         FUNC CreateObject(REF CITScr OF CITScreen0) OF SHORT VIRTUAL
  11199.           LOCAL Error OF SHORT
  11200.  
  11201.           IF CITWindow.CreateObject(CITScr) THEN
  11202.             InsObject(CloseButton,Error)
  11203.             IF Error THEN
  11204.               CITWindow.DeleteObject
  11205.               RETURN FALSE
  11206.             ELSE
  11207.               RETURN TRUE
  11208.             ENDIF
  11209.           ELSE
  11210.             RETURN FALSE
  11211.           ENDIF
  11212.         ENDFUNC CreateObject
  11213.  
  11214.         PROC Wait
  11215.           WHILE NOT CloseButton.Pressed DO WAIT
  11216.         ENDPROC Wait
  11217.  
  11218.       ENDSTRUC MyWindow
  11219.  
  11220.                                          197
  11221.  
  11222.  
  11223.  
  11224.  
  11225.  
  11226.  
  11227.     Note that there is no DeleteObject  in the  structure. The DeleteObject
  11228.     method in CITWindow will do the work.
  11229.  
  11230.  
  11231.   You should  look through  the different CIT-modules to see other examples
  11232.   on definition of CIT classes.
  11233.  
  11234.  
  11235.  
  11236.  
  11237.  
  11238.  
  11239.  
  11240.  
  11241.  
  11242.  
  11243.  
  11244.  
  11245.  
  11246.  
  11247.  
  11248.  
  11249.  
  11250.  
  11251.  
  11252.  
  11253.  
  11254.  
  11255.  
  11256.  
  11257.  
  11258.  
  11259.  
  11260.  
  11261.  
  11262.  
  11263.  
  11264.  
  11265.  
  11266.  
  11267.  
  11268.  
  11269.  
  11270.  
  11271.  
  11272.  
  11273.  
  11274.  
  11275.  
  11276.  
  11277.                                          198
  11278.  
  11279.  
  11280.  
  11281.  
  11282.  
  11283.   V. MAKING EXECUTABLE PROGRAMS
  11284.  
  11285.   There are two ways to make executable programs (i.e. programs that can be
  11286.   started by clicking on its icon) out of a Comal program text.
  11287.  
  11288.   One way  is to  store the  program as a code file. To execute the program
  11289.   the whole Comal system (the interpreter and all modules used  in the pro-
  11290.   gram) must be present on the system.
  11291.  
  11292.   Another way is to combine the interpreter, the program and all the modules
  11293.   used by the program into one executable file.  This file  can be executed
  11294.   without the presence of the Comal system.
  11295.  
  11296.  
  11297.   1 Comal code file.
  11298.  
  11299.   A Comal  program can  be stored  on disk as a code file by using the menu
  11300.   item Save.. in the Programs menu.
  11301.  
  11302.   By double clicking on the icon created along with the code file, the pro-
  11303.   gram is started (without loading the editor).
  11304.  
  11305.   The program  can be  started from  the Shell (CLI) by executing a command
  11306.   like:
  11307.  
  11308.       Comal.Starter ProgramName
  11309.  
  11310.  
  11311.   Example:
  11312.  
  11313.       Comal.Starter Programs/GraphDemo
  11314.  
  11315.  
  11316.   The program is executed as a separate process and the current directory at
  11317.   start is the directory containing the code file.
  11318.  
  11319.   The code file is much shorter than the combined file described in the next
  11320.   section and it is the best way to  make an  executable file  if the Comal
  11321.   system is present.
  11322.  
  11323.  
  11324.   2 Combined files.
  11325.  
  11326.   The Combiner  combines the interpreter, a program and all modules used by
  11327.   this program into one single file that can be executed independent  of the
  11328.   Comal system.
  11329.  
  11330.   The Combiner  strips off  the comments from the program and all the Comal
  11331.   modules and it strips off the information text from mashine coded modules
  11332.   in the SystemModules directory before it combines it.
  11333.  
  11334.                                          199
  11335.  
  11336.  
  11337.  
  11338.  
  11339.  
  11340.  
  11341.   The combined  file can be executed by double clicking on the icon created
  11342.   by the Combiner or by starting it from the Shell (CLI) in the normal way.
  11343.  
  11344.   The current directory at start of the execution is the directory containing
  11345.   the file.
  11346.  
  11347.  
  11348.   2.1 Starting the Combiner from the editor.
  11349.  
  11350.   The simplest  way to  make a  combined file is to start the Combiner from
  11351.   the editor by using the Combine.. menu item in the  Programs menu. Before
  11352.   the Combiner is started a file requester will pop up, and you may select the
  11353.   name and destination of the combined file.
  11354.  
  11355.   The current workspace size and stack size as well as the current state of
  11356.   Automatic Variables and Execute Window are used as default values for the
  11357.   combined file (may be changed by using the Tool Types in the icon).
  11358.  
  11359.   If the editor uses the Workbench screen, the Tool Type
  11360.  
  11361.       SCREEN=Workbench
  11362.  
  11363.   is put into the icon of the combined file.
  11364.  
  11365.  
  11366.   2.2 Starting the Combiner from Workbench.
  11367.  
  11368.   The Combiner can be started from the Workbench. Activate the  icon of the
  11369.   Combiner by clicking once on its icon, press the shift key and double click
  11370.   on the icon of a program (text or code).
  11371.  
  11372.   The following Tool Types can be put into the icon of the  Combiner or the
  11373.   icon of the program:
  11374.  
  11375.     SCREEN
  11376.  
  11377.       The only legal value is Workbench:
  11378.  
  11379.         SCREEN=Workbench
  11380.  
  11381.       The default value is a private screen.
  11382.  
  11383.  
  11384.     AUTOVAR
  11385.  
  11386.       This tool type is used to select the default AutoVar state of the com-
  11387.       bined file. The default value for the Combiner is On.
  11388.  
  11389.       Example:  AUTOVAR=Off
  11390.  
  11391.                                          200
  11392.  
  11393.  
  11394.  
  11395.  
  11396.  
  11397.  
  11398.     EXECWINDOW
  11399.  
  11400.       This tool type is used to select the default ExecWindow  state of the
  11401.       combined file. The default value for the Combiner is On.
  11402.  
  11403.  
  11404.     WORKSPACE
  11405.  
  11406.       Selects the  size of  the workspace used by the combined program. The
  11407.       default value is 75000 bytes.
  11408.  
  11409.       Example:  WORKSPACE=60000
  11410.  
  11411.  
  11412.     STACK
  11413.  
  11414.       Selects the size of the stack, if the combined program is started from
  11415.       Workbench. The default value is 8Kb.
  11416.  
  11417.       Example:  STACK=16000
  11418.  
  11419.       If the  combined program is started from the Shell, the stack size of
  11420.       the Shell will be used.
  11421.  
  11422.  
  11423.     OUTPUT
  11424.  
  11425.       Specify the path and/or the name of the ouput from the combiner.
  11426.  
  11427.       Example:  OUTPUT=Comal:Programs/
  11428.                 OUTPUT=ram:Hanoi
  11429.  
  11430.       If the name ends with ':' or '/' the tool value is treated as a path and
  11431.       the name of the output will be the same as the input file name.
  11432.  
  11433.  
  11434.   If no output file path is specified the name of the combined file will be the
  11435.   name of the input file with the extension '.cmb'.
  11436.  
  11437.  
  11438.   2.3 Starting the Combiner from the Shell (CLI).
  11439.  
  11440.   The Combiner may be started from the Shell. The command is:
  11441.  
  11442.       Combiner [options] ProgramName
  11443.  
  11444.  
  11445.   The options are the same as the Tool Types used if the Combiner is started
  11446.   from the Workbench.
  11447.  
  11448.                                          201
  11449.  
  11450.  
  11451.  
  11452.  
  11453.  
  11454.  
  11455.   Example:
  11456.  
  11457.       Combiner OUTPUT=ram: WORKSPACE=50000 Demos/Polygon2
  11458.  
  11459.  
  11460.  
  11461.   3 Using ToolTypes in executable files.
  11462.  
  11463.   The field Tool Types inside the icon of an executable file (a code file or a
  11464.   combined file) is where you can set parameters for the program.
  11465.  
  11466.   The TOOLTYPE's and the ToolValue's you can use are described below. 
  11467.  
  11468.  
  11469.     SCREEN
  11470.  
  11471.       By using the SCREEN tool type you select if Comal should open its own
  11472.       screen or use the workbench screen. The only legal value is Workbench.
  11473.  
  11474.         SCREEN=Workbench
  11475.  
  11476.       The default  value is  a private  screen. But this screen will not be
  11477.       opened if EXECWINDOW is set to Off.
  11478.  
  11479.  
  11480.     AUTOVAR
  11481.  
  11482.       This tool type is used to select if the program should create variables
  11483.       automatically or if all variables has to be declared in a DIM or LOCAL
  11484.       statement before use.
  11485.  
  11486.       Example:  AUTOVAR=Off
  11487.  
  11488.  
  11489.     EXECWINDOW
  11490.  
  11491.       This tool type is used to select if the program should open the stan-
  11492.       dard execute window (used by PRINT, INPUT etc.). The default value is
  11493.       On.
  11494.  
  11495.       Example:  EXECWINDOW=Off
  11496.  
  11497.  
  11498.     WORKSPACE
  11499.  
  11500.       Selects the size of the workspace  used by  the program.  The default
  11501.       value is 75000 bytes.
  11502.  
  11503.       Example:  WORKSPACE=60000
  11504.  
  11505.                                          202
  11506.  
  11507.  
  11508.  
  11509.  
  11510.  
  11511.   VI. DESCRIPTION OF THE Comal SYSTEM
  11512.  
  11513.   The Comal system consists of several program files. During normal program
  11514.   devellopment three of these program files are used. These files are:
  11515.  
  11516.     Comal
  11517.  
  11518.       The editor
  11519.  
  11520.     Comal.CodeMan
  11521.  
  11522.       A program used to manipulate the program buffer.  It generates inter-
  11523.       mediate code  from ASCII lines and regenerate ASCII lines from inter-
  11524.       mediate code. It inserts new lines in the buffer and deletes lines from
  11525.       the buffer. And much more.
  11526.  
  11527.     Comal.Interpreter
  11528.  
  11529.       The interpreter that executes your programs.
  11530.  
  11531.  
  11532.   The programs  are executed  as separate  processes. The editor Comal com-
  11533.   municates with Comal.CodeMan and Comal.Interpreter by sending messages.
  11534.  
  11535.  
  11536.   1 The code manipulator Comal.CodeMan.
  11537.  
  11538.   The program Comal.CodeMan is used to manipulate the  program buffer. Once
  11539.   started it will stay as a resident process and all comumnication with the
  11540.   process goes through its message port Comal.CodeMan.
  11541.  
  11542.   A message send to this port must be either a RexxMessage (explained  in a
  11543.   later section) or it must be of the form:
  11544.  
  11545.     STRUC CodeCommandMsg
  11546.       INHERIT Message
  11547.       DIM Command OF POINTER TO CodeCommand
  11548.     ENDSTRUC CodeCommandMsg
  11549.  
  11550.   where Message is a standard Exec message and CodeCommand is
  11551.  
  11552.     STRUC CodeCommand
  11553.       DIM Cmd OF SHORT
  11554.       DIM Status OF SHORT
  11555.       DIM PrgBuf OF POINTER TO PrgBuf
  11556.       DIM Param1 OF ULONG
  11557.       DIM Param2 OF ULONG
  11558.       DIM CmdProc@ OF CmdProc
  11559.     ENDSTRUC CodeCommand
  11560.  
  11561.  
  11562.                                          203
  11563.  
  11564.  
  11565.  
  11566.  
  11567.  
  11568.  
  11569.   Before a  message is  send to  Comal.CodeMan the  Cmd field is set to the
  11570.   command you want to be executed  and  the  fields  Param1  and  Param2 is
  11571.   filled with corresponding command parameters.
  11572.  
  11573.   Before Comal.CodeMan  returns the  message, it  places the command status
  11574.   code in the field Status (zero is ok) and return values in the fields Param1
  11575.   and Param2.
  11576.  
  11577.   The command that can be executed are:
  11578.  
  11579.     CODE_KILL (1)           Kill CodeMan process
  11580.  
  11581.       If there  are no  open program buffers the Comal.CodeMan process will
  11582.       be removed.
  11583.  
  11584.       There are no return values from this command.
  11585.  
  11586.  
  11587.     CODE_OPEN (2)           Open program buffer
  11588.  
  11589.       Create a new program buffer. If  status is  ok the  fields PrgBuf and
  11590.       CmdProc is  set. CmdProc can be used to call CodeMan directly without
  11591.       sending a message (considerably faster).
  11592.  
  11593.       Command parameters:   Param1 = program buffer length
  11594.                             Param2 = initial flags
  11595.  
  11596.       Return values:        None
  11597.  
  11598.  
  11599.     CODE_CLOSE (3)          Close program buffer
  11600.  
  11601.       A  program  buffer  previously   opened  by   executing  the  command
  11602.       CODE_OPEN is closed.
  11603.  
  11604.       Command parameters:   None
  11605.  
  11606.       Return values:        None
  11607.  
  11608.  
  11609.     CODE_CLEAR (4)          Clear program buffer
  11610.  
  11611.       Remove the current content of the program buffer.
  11612.  
  11613.       Command parameters:   None
  11614.  
  11615.       Return values:        None
  11616.  
  11617.  
  11618.  
  11619.                                          204
  11620.  
  11621.  
  11622.  
  11623.  
  11624.  
  11625.     CODE_LOAD (5)           Read file into program buffer
  11626.  
  11627.       Read program stored on disk in code form into the program buffer. The
  11628.       previous content of the program buffer is lost.
  11629.  
  11630.       Command parameters:   Param1 = Pointer to null terminated file name
  11631.  
  11632.       Return values:        Param1 = Line number
  11633.                             Param2 = Total number of lines in buffer
  11634.  
  11635.       Note: Since Comal.CodeMan runs as a separate  process (unless CmdProc
  11636.             is used) the complete path for the file must be specified.
  11637.  
  11638.  
  11639.     CODE_SAVE (6)           Write program buffer to file
  11640.  
  11641.       The content of the program buffer is stored on disk in code form. The
  11642.       program buffer is unchanged.
  11643.  
  11644.       Command parameters:   Param1 = Pointer to null terminated file name
  11645.  
  11646.       Return values:        None
  11647.  
  11648.       Note: Since Comal.CodeMan runs as a separate  process (unless CmdProc
  11649.             is used) the complete path for the file must be specified.
  11650.  
  11651.  
  11652.     CODE_GEN (7)            Generate code for ASCII line
  11653.  
  11654.       Intermediate code is generated for an ASCII program line. If an error
  11655.       occurs the return parameter Param1 points to the place where the error
  11656.       was detected.
  11657.  
  11658.       Command parameters:   Param1 = Pointer to null terminated program line
  11659.                             Param2 = Address of buffer for the code
  11660.  
  11661.       Return values:        Param1 = Pointer into program line
  11662.                             Param2 = Address of buffer for the code
  11663.  
  11664.       Note: The buffer must be large enough to hold the code generated (500
  11665.             bytes is recommented).
  11666.  
  11667.  
  11668.     CODE_GENDIRECT (8)
  11669.  
  11670.       Intermediate code is generated for an ASCII program line. An error is
  11671.       reported if the code generated cannot be executed directly (if the pro-
  11672.       gram line is part of a program structure). If an error occurs the return
  11673.       parameter Param1 points to the place where the error was detected.
  11674.  
  11675.  
  11676.                                          205
  11677.  
  11678.  
  11679.  
  11680.  
  11681.  
  11682.       Command parameters:   Param1 = Pointer to null terminated program line
  11683.                             Param2 = Address of buffer for the code
  11684.  
  11685.       Return values:        Param1 = Pointer into program line
  11686.                             Param2 = Address of buffer for the code
  11687.  
  11688.       Note: The buffer must be large enough to hold the code generated (500
  11689.             bytes is recommented).
  11690.  
  11691.  
  11692.     CODE_REGEN (9)          Regenerate ASCII line
  11693.  
  11694.       Regenerate the current line (pointed at by the buffer pointer) into the
  11695.       corresponding ASCII line. This command can be viewed of as the rever-
  11696.       se of CODE_GEN.
  11697.  
  11698.       Command parameters:   Param1 = ASCII buffer pointer
  11699.  
  11700.       Return values:        Param1 = Length of ASCII line generated
  11701.                             Param2 = Line number of current line
  11702.  
  11703.       Note: The generated ASCII line is null terminated and the length retur-
  11704.             ned includes the terminating zero
  11705.  
  11706.  
  11707.     CODE_INSERT (10)        Insert code line in buffer
  11708.  
  11709.       Insert intermediate code line in program buffer at the current position.
  11710.  
  11711.       Command parameters:   Param1 = Address of code
  11712.  
  11713.       Return values:        Param1 = Line number of current line
  11714.                             Param2 = Total number of lines in buffer
  11715.  
  11716.  
  11717.     CODE_DELETE (11)        Delete current line in buffer
  11718.  
  11719.       The current line in buffer is deleted
  11720.  
  11721.       Command parameters:   None
  11722.  
  11723.       Return values:        Param1 = Line number of current line
  11724.                             Param2 = Total number of lines in buffer
  11725.  
  11726.  
  11727.     CODE_REPLACE (12)       Replace line in buffer
  11728.  
  11729.       Replace the  current line with the code given as parameter. This is a
  11730.       combination of CODE_DELETE and CODE_INSERT.
  11731.  
  11732.  
  11733.                                          206
  11734.  
  11735.  
  11736.  
  11737.  
  11738.  
  11739.       Command parameters:   Param1 = Address of code
  11740.  
  11741.       Return values:        Param1 = Line number of current line
  11742.                             Param2 = Total number of lines in buffer
  11743.  
  11744.  
  11745.     CODE_UP (13)            Move pointer n lines up
  11746.  
  11747.       Move the buffer pointer up n lines (or to top of buffer).
  11748.  
  11749.       Command parameters:   Param1 = Number of lines to move up
  11750.  
  11751.       Return values:        Param1 = Line number of current line
  11752.                             Param2 = Total number of lines in buffer
  11753.  
  11754.  
  11755.     CODE_DOWN (14)          Move pointer n lines down
  11756.  
  11757.       Move the buffer pointer down n lines (or to buttom of buffer).
  11758.  
  11759.       Command parameters:   Param1 = Number of lines to move down 
  11760.  
  11761.       Return values:        Param1 = Line number of current line
  11762.                             Param2 = Total number of lines in buffer
  11763.  
  11764.  
  11765.     CODE_BOB (15)           Move pointer to bottom of buffer
  11766.  
  11767.       Move the buffer pointer to bottom of buffer.
  11768.  
  11769.       Command parameters:   None  
  11770.  
  11771.       Return values:        Param1 = Line number of current line
  11772.                             Param2 = Old line number
  11773.  
  11774.  
  11775.     CODE_TOB (16)           Move pointer to top of buffer
  11776.  
  11777.       Move the buffer pointer to top of buffer.
  11778.  
  11779.       Command parameters:   None  
  11780.  
  11781.       Return values:        Param1 = 1
  11782.                             Param2 = Old line number
  11783.  
  11784.     CODE_SETADR (17)        Set pointer to specified address
  11785.  
  11786.       The code pointer is set to the line containing the specified address
  11787.  
  11788.       Command parameter:    Param1 = address
  11789.  
  11790.                                          207
  11791.  
  11792.  
  11793.  
  11794.  
  11795.  
  11796.  
  11797.       Return values:        Param1 = Line number of current line
  11798.                             Param2 = Address offset in current line
  11799.  
  11800.  
  11801.     CODE_SETFLAGS (18)      Set flags
  11802.  
  11803.       Set the CodeMan flags
  11804.  
  11805.       Command parameters:   Param1 = New flag values of flags to chage
  11806.                             Param2 = Mask of flag bits to change
  11807.  
  11808.       Return values:        Param1 = new flag values
  11809.                             Param2 = old flag values
  11810.  
  11811.  
  11812.   Flags:
  11813.     $0001:  List standard identifiers in capital
  11814.     $0002:  List in PC format
  11815.  
  11816.  
  11817.   Status codes returned by CODE_OPEN:
  11818.  
  11819.     NOMEM (1)           Cannot allocate memory
  11820.     NUMINITERR (2)      IEEE initialization error
  11821.  
  11822.  
  11823.   Status code returned by other commands:                                  
  11824.  
  11825.     NOTDIRECT (1)       Not direct command
  11826.     NOBUFSPACE (2)      Not enough room in program buffer 
  11827.     ENDOFBUF (3)        Pointer at end of buffer
  11828.     ADDRNOTFOUND (4)    Address not found in programbuffer
  11829.     NOFILE (5)          File not found
  11830.     READERROR (6)       Error during reading
  11831.     WRITEERROR (7)      Error during writing
  11832.     ILLFORMAT (8)       Not legal Comal program file
  11833.     CODEMANINUSE (9)    Cannot kill CodeMan
  11834.  
  11835.   All the  structures and symbolic names are defined in the module CodeMan-
  11836.   Include.
  11837.  
  11838.   The following procedure CodeToAscii is an example of the use  of the com-
  11839.   mands. The procedure changes a code program file to an ASCII text file.
  11840.  
  11841.  
  11842.     PROC CodeToAscii(Name$,NewName$) CLOSED
  11843.       USE System
  11844.       USE InterpreterInclude
  11845.       USE ExecLists
  11846.  
  11847.                                          208
  11848.  
  11849.  
  11850.  
  11851.  
  11852.  
  11853.       USE PortObjects
  11854.       USE ExecLibrary
  11855.  
  11856.       DIM CodeManPort OF POINTER TO MsgPort
  11857.       DIM CodeManMsg OF CodeCommandMsg
  11858.       DIM ReplyPort OF MsgPort
  11859.       DIM Command OF CodeCommand
  11860.       DIM Buffer(500) OF UBYTE
  11861.  
  11862.       CodeManMsg.mn_ReplyPort:=ADR(ReplyPort)
  11863.  
  11864.       // Find CodeMan port
  11865.       CodeManPort:=FindPort("Comal.CodeMan")
  11866.       IF CodeManPort=0 THEN
  11867.         CleanUp
  11868.         STOP
  11869.       ENDIF
  11870.  
  11871.       // .. and open CodeMan
  11872.       Command.Cmd:=CODE_OPEN
  11873.       Command.Param1:=$8000
  11874.       Command.Param2:=0
  11875.       SendCommand(Command)
  11876.       IF Command.Status THEN
  11877.         CleanUp
  11878.         STOP
  11879.       ENDIF
  11880.  
  11881.       Command.Cmd:=CODE_LOAD
  11882.       Command.Param1:=ADR(Name$)
  11883.       Command.Param2:=0
  11884.       SendCommand(Command)
  11885.       IF Command.Status THEN
  11886.         CleanUp
  11887.         STOP
  11888.       ENDIF
  11889.  
  11890.       OPEN FILE 1,NewName$,WRITE
  11891.       REPEAT
  11892.         Command.Cmd:=CODE_REGEN
  11893.         Command.Param1:=ADR(Buffer())
  11894.         Command.Param2:=0
  11895.         SendCommand(Command)
  11896.         IF Command.Status THEN
  11897.           CleanUp
  11898.           STOP
  11899.         ENDIF
  11900.         PRINT FILE 1: CharArrayToString$(ADR(Buffer()))
  11901.         Command.Cmd:=CODE_DOWN
  11902.         Command.Param1:=1
  11903.  
  11904.                                          209
  11905.  
  11906.  
  11907.  
  11908.  
  11909.  
  11910.         Command.Param2:=0
  11911.         SendCommand(Command)
  11912.       UNTIL Command.Status
  11913.  
  11914.       CleanUp
  11915.  
  11916.       PROC SendCommand(REF Command OF CodeCommand)
  11917.         CodeManMsg.Command:=ADR(Command)
  11918.         CodeManPort@.Put(CodeManMsg)
  11919.         CodeManMsg.Wait
  11920.       ENDPROC SendCommand
  11921.  
  11922.       PROC CleanUp
  11923.         IF Command.CmdProc THEN
  11924.           Command.Cmd:=CODE_CLOSE
  11925.           Command.CmdProc@(ADR(Command))
  11926.           Command.CmdProc:=0
  11927.         ENDIF
  11928.         CLOSE
  11929.       ENDPROC CleanUp
  11930.  
  11931.     ENDPROC CodeToAscii
  11932.  
  11933.  
  11934.   2 The interpreter Comal.Interpreter.
  11935.  
  11936.   The program  Comal.Interpreter is used to execute a program. Once started
  11937.   it will stay as a resident process and all communication with the process
  11938.   goes through message ports.
  11939.  
  11940.   A message  send to  the port must be either a RexxMessage (explained in a
  11941.   later section) or it must be of the form:
  11942.  
  11943.     STRUC InterpreterCommandMsg
  11944.       INHERIT Message
  11945.       DIM Command OF POINTER TO InterpreterCommand
  11946.     ENDSTRUC InterpreterCommandMsg
  11947.  
  11948.   where Message is a standard  Exec  message  and  InterpreterCommand  is a
  11949.   structure of the form:
  11950.  
  11951.  
  11952.     STRUC InterpreterCommand
  11953.       DIM Cmd OF SHORT           // Put your command in here
  11954.       DIM Status OF SHORT        // Look for command status here
  11955.       DIM Int_Port@ OF MsgPort   // Use this port in communication
  11956.       DIM Task@ OF Task          // Interpreter task pointer
  11957.       DIM BreakSigMask OF ULONG  // Signal used to stop running program
  11958.       DIM Param1 OF ULONG        // 1. parameter
  11959.       DIM Param2 OF ULONG        // 2. parameter
  11960.  
  11961.                                          210
  11962.  
  11963.  
  11964.  
  11965.  
  11966.  
  11967.       DIM Param3 OF ULONG        // 3. parameter
  11968.       DIM Flags OF ULONG
  11969.     ENDSTRUC InterpreterCommand
  11970.  
  11971.  
  11972.   Before a message is send to Comal.Interpreter the Cmd field is set to the
  11973.   command you want to be executed and the fields Param1 and Param2  is fil-
  11974.   led with corresponding command parameters. Before the message is returned,
  11975.   the command status code in the field Status (zero is ok) and return values
  11976.   in the fields Param1, Param2 and Param3 are set.
  11977.  
  11978.   The command that can be executed are:
  11979.  
  11980.  
  11981.     INT_KILL (1)            Kill interpreter
  11982.  
  11983.       If there are no active interpreters the master process Comal.Interpreter
  11984.       will be removed. A non zero status means that the master process can-
  11985.       not be  closed (others are using it). There are no command parameters
  11986.       or return values.
  11987.  
  11988.  
  11989.     INT_OPEN (2)            Open interpreter
  11990.  
  11991.       A new interpreter is opened. The new interpreter is in fact a new pro-
  11992.       cess and  all the  next commands are send to the port returned in the
  11993.       field Int_Port.
  11994.  
  11995.       Command parameters:   Param1 = address of open structure
  11996.                             Param2 = stack size of new process
  11997.                             Param3 = RUN flags (only if LOAD and RUN)
  11998.  
  11999.       The open structure has the form:
  12000.  
  12001.         STRUC IntOpenStruc
  12002.           DIM Flags OF ULONG
  12003.           DIM WorkspaceLength OF ULONG
  12004.           DIM PrgId OF POINTER TO UBYTE
  12005.           DIM IO_Port OF POINTER TO MsgPort
  12006.           DIM Screen OF POINTER TO Screen
  12007.           DIM InterpreterId OF POINTER TO UBYTE
  12008.         ENDSTRUC IntOpenStruc
  12009.  
  12010.       and the open flags are:
  12011.  
  12012.         INTOPEN_AUTOVAR  ($00000001)    Automatic creation of variables
  12013.         INTOPEN_COMMPORT ($00000002)    Create communication port
  12014.         INTOPEN_LOADPRG  ($20000000)    Open and load program.
  12015.         INTOPEN_OPENSCR  ($40000000)    Open separate screen
  12016.         INTOPEN_LOADRUN  ($A0000000)    Load and run as separate process
  12017.  
  12018.                                          211
  12019.  
  12020.  
  12021.  
  12022.  
  12023.  
  12024.  
  12025.       If flag bit 29  is set  (LOADPRG and  LOADRUN) the  field PrgId  is a
  12026.       pointer to a null terminated file name. Otherwise it is an address of a
  12027.       program buffer (returned by CODE_OPEN command to Comal.CodeMan).
  12028.  
  12029.       return values:        Param1 = address of communication port  (if the
  12030.                             INTOPEN_COMMPORT is set)
  12031.  
  12032.  
  12033.     INT_CLOSE (3)           Close program buffer
  12034.  
  12035.       Close  the  interpreter  and  remove the process created by INT_OPEN.
  12036.       The master process Comal.Interpreter is not closed.
  12037.  
  12038.       Command parameters:   None
  12039.  
  12040.       Return values:        None
  12041.  
  12042.  
  12043.     INT_SCAN (4)            Scan program
  12044.  
  12045.       Make a prepass scan of the program. The address returned  can be send
  12046.       to CodeMan (CODE_SETADR) to get the exact error position.
  12047.  
  12048.       Command parameters:   None
  12049.  
  12050.       Return value:         Param1 = active program buffer
  12051.                             Param2 = pointer into program line (if error)
  12052.  
  12053.  
  12054.     INT_RUN (5)             Execute program
  12055.  
  12056.       Execute program  in main  program buffer. The address returned can be
  12057.       send to  CodeMan (CODE_SETADR)  to get  the exact  error position. If
  12058.       the  run  flag  RUNFLAG_STDIO  ($00000001)  is set, an execute window
  12059.       will be the standard  IO device.  Otherwise the  IO_Port in  the open
  12060.       structure is used.
  12061.       
  12062.       Command parameters:   Param1 = flags
  12063.  
  12064.       Return values:        Param1 = active program buffer
  12065.                             Param2 = pointer into program line (if error)
  12066.                             Param3 = address of return text
  12067.  
  12068.  
  12069.     INT_COMMAND (6)         Execute line as command
  12070.  
  12071.       Execute a single code line as command.
  12072.  
  12073.       Command parameters:   Param1 = pointer to line
  12074.  
  12075.                                          212
  12076.  
  12077.  
  12078.  
  12079.  
  12080.  
  12081.  
  12082.       Return values:        Param1 = active program buffer
  12083.                             Param2 = pointer into program line (if error)
  12084.                             Param3 = address of return text
  12085.  
  12086.  
  12087.     INT_CONTINUE (7)        Continue
  12088.  
  12089.       Continue breaked program execution
  12090.  
  12091.       Command parameters:   None
  12092.  
  12093.       Return values:        None
  12094.  
  12095.  
  12096.     INT_RETPRGBUF (8)       Return program buffer
  12097.  
  12098.       The  commands  INT_SCAN,  INT_RUN,  INT_COMMAND  transfers  the  pro-
  12099.       gram buffer to the interpreter and you are not allowed  to change the
  12100.       buffer. To get the program buffer back execute this command.
  12101.  
  12102.       Command parameters:   None
  12103.  
  12104.       Return values:        None
  12105.  
  12106.  
  12107.     INT_DISCARD (9)         Remove all modules
  12108.  
  12109.       Remove all modules loaded.
  12110.  
  12111.       Command parameters:   None
  12112.  
  12113.       Return values:        None
  12114.  
  12115.  
  12116.     INT_LISTMODULES (10)    Return list of all modules
  12117.  
  12118.       A list of module structures for all modules are returned.
  12119.  
  12120.       Command parameters:   None
  12121.  
  12122.       Return values:        Param1 = address of first structure in list
  12123.  
  12124.  
  12125.     INT_STARTTRACE (11)     Initiate tracing mode
  12126.  
  12127.       Scan program and start tracing. No lines are executed.
  12128.  
  12129.       Command parameters:   None
  12130.  
  12131.  
  12132.                                          213
  12133.  
  12134.  
  12135.  
  12136.  
  12137.  
  12138.       Return values:        Param1 = active program buffer
  12139.                             Param2 = pointer into line (if error)
  12140.                             Param3 = return text
  12141.  
  12142.  
  12143.     INT_STOPTRACE (12)      Stop tracing mode
  12144.  
  12145.       Command parameters:   None
  12146.  
  12147.       Return values:        None
  12148.  
  12149.  
  12150.     INT_SINGLESTEP (13)     Execute one step
  12151.  
  12152.       Execute one step of program. The program must be in tracing mode.
  12153.  
  12154.       Command parameters:   None
  12155.  
  12156.       Return values:        Param1 = program buffer
  12157.                             Param2 = pointer to line (if error)
  12158.                             Param3 = return text
  12159.  
  12160.  
  12161.     INT_LINESTEP (14)       Execute one line
  12162.  
  12163.       Execute one line of program. The program must be in tracing mode.
  12164.  
  12165.       Command parameters:   None
  12166.  
  12167.       Return values:        Param1 = program buffer
  12168.                             Param2 = pointer to line (if error)
  12169.                             Param3 = return text
  12170.  
  12171.  
  12172.     INT_SETBREAK (15)       Set break point
  12173.  
  12174.       Set break point at specified line in program or module
  12175.  
  12176.       Command parameters:   Param1 = address of program buffer
  12177.                             Param2 = line number of break point line
  12178.  
  12179.       Return values:        None
  12180.  
  12181.  
  12182.     INT_CLEARBREAK (16)     Clear break point
  12183.  
  12184.       Clear break point at specified line
  12185.  
  12186.       Command parameters:   Param1 = address of program buffer
  12187.                             Param2 = line number of break point line
  12188.  
  12189.                                          214
  12190.  
  12191.  
  12192.  
  12193.  
  12194.  
  12195.  
  12196.       Return values:        None
  12197.  
  12198.  
  12199.     INT_CLEARALL (17)       Clear all break points
  12200.  
  12201.       Clear all break points in main program and modules.
  12202.  
  12203.       Command parameters:   None
  12204.  
  12205.       Return values:        None
  12206.  
  12207.  
  12208.  
  12209.   Status codes returned by INT_OPEN:
  12210.  
  12211.     NOMEM (1)           Cannot allocate memory
  12212.     NUMINITERR (2)      IEEE initialization error
  12213.  
  12214.  
  12215.   Status codes  returned by all other commands are the same as is send by a
  12216.   running program.
  12217.  
  12218.   The structures and all the symbolic names are defined in the module Inter-
  12219.   preterInclude.
  12220.  
  12221.   The following procedure StartProgram is an example of the use of the com-
  12222.   mands. The procedure starts a program stored as a code program file.
  12223.  
  12224.  
  12225.     PROC StartProgram(PrgName$) CLOSED
  12226.       USE System
  12227.       USE InterpreterInclude
  12228.       USE ExecLists
  12229.       USE PortObjects
  12230.       USE ExecLibrary
  12231.  
  12232.       DIM IntCmd OF InterpreterCommand
  12233.       DIM IntCmdMsg OF InterpreterCommandMsg
  12234.       DIM ReplyPort@ OF MsgPort, ReplySigMask OF ULONG
  12235.       DIM MasterPort@ OF MsgPort
  12236.       DIM OpenStruc OF IntOpenStruc
  12237.       DIM RetSigMask OF ULONG
  12238.       DIM pos OF SHORT
  12239.  
  12240.       // Find Interpreter master port
  12241.       MasterPort:=FindPort(MasterPortName$)
  12242.       IF MasterPort=0 THEN
  12243.         STOP "Cannot find interpreter master"
  12244.       ENDIF
  12245.  
  12246.                                          215
  12247.  
  12248.  
  12249.  
  12250.  
  12251.  
  12252.  
  12253.       // Remove path from program name
  12254.       pos:=LEN(PrgName$)+1
  12255.       REPEAT
  12256.         pos:-1
  12257.       UNTIL pos=0 OR PrgName$(pos..pos)=":" OR PrgName$(pos..pos)="/"
  12258.       Name$:=PrgName$(pos+1..)
  12259.  
  12260.       OpenStruc.Flags:=INTOPEN_LOADRUN BITOR INTOPEN_AUTOVAR
  12261.       OpenStruc.WorkspaceLength:=$8000
  12262.       OpenStruc.PrgId:=ADR(PrgName$)
  12263.       OpenStruc.Screen:=0                 // Use Workbench screen
  12264.       OpenStruc.IO_Port:=0                // No IO port
  12265.       OpenStruc.InterpreterId:=ADR(Name$) // Id of new process
  12266.  
  12267.       IntCmdMsg.mn_ReplyPort:=ADR(ReplyPort)
  12268.       IntCmdMsg.Command:=ADR(IntCmd)
  12269.       IntCmd.Cmd:=INT_OPEN
  12270.       IntCmd.Param1:=ADR(OpenStruc)
  12271.       IntCmd.Param2:=$4000                // Stack size
  12272.       IntCmd.Param3:=RUNFLAG_STDIO
  12273.       MasterPort@.Put(IntCmdMsg)
  12274.       IntCmdMsg.Wait
  12275.  
  12276.       IF IntCmd.Status<>0 THEN
  12277.         STOP "Cannot load program"
  12278.       ENDIF
  12279.  
  12280.       // The program is started - return
  12281.  
  12282.     ENDPROC StartProgram
  12283.  
  12284.  
  12285.  
  12286.   3 The starter program Comal.Starter.
  12287.  
  12288.   The  default  tool  for  a  Comal  code  program  file  is   the  program
  12289.   Comal.Starter. This program loads the interpreter Comal.Interpreter (if not
  12290.   already loaded) and opens an interpreter process that reads the  file and
  12291.   executes  it   as  a   stand  alone  process  by  using  the  open  flags
  12292.   INTOPEN_LOADRUN (almost like the procedure StartProgram in section 2).
  12293.  
  12294.   Having done this the Comal.Starter terminates.
  12295.  
  12296.  
  12297.  
  12298.  
  12299.  
  12300.  
  12301.  
  12302.  
  12303.                                          216
  12304.  
  12305.  
  12306.  
  12307.  
  12308.  
  12309.   VII. THE Comal AREXX INTERFACE
  12310.  
  12311.   Each of the three main parts  of the  Comal system  (Comal, Comal.CodeMan
  12312.   and Comal.Interpreter)  has an  AREXX interface.  This chapter covers the
  12313.   commands supported and how to access them.
  12314.  
  12315.  
  12316.   1 The editor AREXX interface.
  12317.  
  12318.   For each project opened a separate process is started with  its own AREXX
  12319.   port. The name of the port is Comal.Project.<project number>, for instance
  12320.   Comal.Project.001 and Comal.Project.002.
  12321.  
  12322.   The AREXX commands accepted  by the  editor are  (NOTE: for  all commands
  12323.   the return code is RC_WARN (5) if the command is currently disabled):
  12324.  
  12325.  
  12326.     NEW                 Create a new project
  12327.  
  12328.       Command format: NEW
  12329.  
  12330.       Return values:  The name of the AREXX port of the project
  12331.  
  12332.       Return codes:   RC_OK (0) if success
  12333.                       RC_ERROR (10) if the command failed
  12334.  
  12335.       Example:        NEW
  12336.  
  12337.  
  12338.     CLEAR             Clear program buffer
  12339.  
  12340.       Command format: CLEAR [FORCE]
  12341.  
  12342.       Return values:  None
  12343.  
  12344.       Return codes:   RC_OK (0) if success
  12345.                       RC_WARN (5) if user pressed the NO gadget
  12346.  
  12347.       If the program in the program buffer has been changed the user will be
  12348.       prompted to accept unless the FORCE argument is specified.
  12349.  
  12350.       Example:        CLEAR FORCE
  12351.  
  12352.  
  12353.     OPEN              Open and load a new project file
  12354.  
  12355.       Command format: OPEN [FILENAME=<name>][MODE=ASCII|CODE][FORCE]
  12356.  
  12357.       Return values:  None
  12358.  
  12359.  
  12360.                                          217
  12361.  
  12362.  
  12363.  
  12364.  
  12365.  
  12366.       Return codes:   RC_OK (0) if success
  12367.                       RC_WARN (5) if NO or CANCEL gadget pressed
  12368.                       RC_ERROR (10) if illegal or no file
  12369.  
  12370.       If the file name is not specified the user is prompted for a file name
  12371.       via the file requester. The MODE argument specifies the file type (an
  12372.       ASCII text file or a Comal code file). The default mode is ASCII. If the
  12373.       program  in  the  program  buffer  has  been changed the user will be
  12374.       prompted to accept unless the FORCE argument is specified.
  12375.  
  12376.       Example:        OPEN FILENAME=Demos/Integral1 FORCE
  12377.  
  12378.  
  12379.     SAVE              Save project
  12380.  
  12381.       Command format: SAVE [MODE=ASCII|CODE]
  12382.  
  12383.       Return values:  None
  12384.  
  12385.       Return codes:   RC_OK (0) if success
  12386.                       RC_WARN (5) if CANCEL gadget pressed
  12387.                       RC_ERROR (10) else
  12388.  
  12389.       The MODE argument specifies the file  type (an  ASCII text  file or a
  12390.       Comal code file). The default mode is ASCII. If the current project is
  12391.       unnamed the user is prompted for a file name via the file requester.
  12392.  
  12393.       Example:        SAVE CODE
  12394.  
  12395.  
  12396.  
  12397.     SAVEAS            Save project under specified name
  12398.  
  12399.       Command format: OPEN [FILENAME=<name>] [MODE=ASCII|CODE]
  12400.  
  12401.       Return values:  None
  12402.  
  12403.       Return codes:   RC_OK (0) if success
  12404.                       RC_WARN (5) if NO or CANCEL gadget pressed
  12405.                       RC_ERROR (10) if illegal or no file
  12406.  
  12407.       If the file name is not specified the user is prompted for a file name
  12408.       via the file requester. The MODE argument specifies the file type (an
  12409.       ASCII text file or a Comal code file).
  12410.  
  12411.       Example:        SAVEAS FILENAME=Programs/Hanoi CODE
  12412.  
  12413.  
  12414.  
  12415.  
  12416.  
  12417.                                          218
  12418.  
  12419.  
  12420.  
  12421.  
  12422.  
  12423.     PRINT             Output the program to printer
  12424.  
  12425.       Command format: PRINT
  12426.  
  12427.       Return values:  None
  12428.  
  12429.       Return codes:   RC_OK (0)
  12430.  
  12431.       Example:        PRINT
  12432.  
  12433.  
  12434.     QUIT              Terminate the project
  12435.  
  12436.       Command format: QUIT [FORCE]
  12437.  
  12438.       Return values:  None
  12439.  
  12440.       Return codes:   RC_OK (0) if success
  12441.                       RC_WARN (5) if user pressed the NO gadget
  12442.  
  12443.       If the program in the program buffer has been changed the user will be
  12444.       prompted to accept unless the FORCE argument is specified.
  12445.  
  12446.       Example:        QUIT
  12447.  
  12448.  
  12449.     BLOCK             Set block mode on/off
  12450.  
  12451.       Command format: BLOCK
  12452.  
  12453.       Return values:  ON  or  OFF  dependent  on the block mode state after
  12454.                       the command is executed.
  12455.  
  12456.       Return codes:   RC_OK (0)
  12457.  
  12458.       Example:        BLOCK
  12459.  
  12460.  
  12461.     BLOCKSIZE         Return the size of the current block
  12462.  
  12463.       Command format: BLOCKSIZE
  12464.  
  12465.       Return values:  The returned number is  in fact  not the  size of the
  12466.                       block. The  number of lines in the block is -RetVal+1
  12467.                       if RetVal<0 and RetVal+1 else. The number can be used
  12468.                       directly as  an argument  in the LINE command to move
  12469.                       to the other end of the block.
  12470.  
  12471.       Return codes:   RC_OK (0)
  12472.  
  12473.  
  12474.                                          219
  12475.  
  12476.  
  12477.  
  12478.  
  12479.  
  12480.       Example:        BLOCKSIZE
  12481.  
  12482.  
  12483.     CUT               Move marked block to the clip board
  12484.  
  12485.       Command format: CUT
  12486.  
  12487.       Return values:  None.
  12488.  
  12489.       Return codes:   RC_OK (0) if success
  12490.                       RC_ERROR (10) if out of memory
  12491.  
  12492.       Example:        CUT
  12493.  
  12494.  
  12495.     COPY              Move a copy of the marked block to the clip board
  12496.  
  12497.       Command format: COPY
  12498.  
  12499.       Return values:  None.
  12500.  
  12501.       Return codes:   RC_OK (0) if success
  12502.                       RC_ERROR (10) if out of memory
  12503.  
  12504.       Example:        COPY
  12505.  
  12506.  
  12507.     PASTE             Insert content of clipboard into the program
  12508.  
  12509.       Command format: PASTE
  12510.  
  12511.       Return values:  None.
  12512.  
  12513.       Return codes:   RC_OK (0) if success
  12514.                       RC_ERROR (10) if out of memory
  12515.  
  12516.       Example:        PASTE
  12517.  
  12518.  
  12519.     ERASE             Delete marked block
  12520.  
  12521.       Command format: ERASE
  12522.  
  12523.       Return values:  None.
  12524.  
  12525.       Return codes:   RC_OK (0)
  12526.  
  12527.       Example:        ERASE
  12528.  
  12529.  
  12530.  
  12531.                                          220
  12532.  
  12533.  
  12534.  
  12535.  
  12536.  
  12537.     CURSOR            Move cursor
  12538.  
  12539.       Command format: CURSOR UP|DOWN|LEFT|RIGHT
  12540.  
  12541.       Return values:  None
  12542.  
  12543.       Return codes:   RC_OK (0) if success
  12544.                       RC_WARN (5) if border of text
  12545.  
  12546.       Example:        CURSOR DOWN
  12547.  
  12548.  
  12549.     POSITION          Move cursor to specified position
  12550.  
  12551.       Command format: POSITION <place>  where place is:
  12552.                         SOF start of file
  12553.                         EOF end of file
  12554.                         SOL start of line
  12555.                         EOL end of line
  12556.                         SOV start of view (top of window)
  12557.                         EOV end of view (bottom of window)
  12558.  
  12559.       Return values:  None
  12560.  
  12561.       Return codes:   RC_OK (0)
  12562.  
  12563.       Example.        POSITION EOF
  12564.  
  12565.  
  12566.     LINE              Move cursor up/down specified number of lines
  12567.  
  12568.       Command format: LINE <number>
  12569.  
  12570.       Return values:  None.
  12571.  
  12572.       Return codes:   RC_OK (0) if success
  12573.                       RC_WARN (5) if border of text
  12574.  
  12575.       Example:        LINE -5     /* Move 5 lines up  */
  12576.  
  12577.  
  12578.     COLUMN            Move cursor left/right specified number of characters
  12579.  
  12580.       Command format: COLUMN <number>
  12581.  
  12582.       Return values:  None.
  12583.  
  12584.       Return codes:   RC_OK (0) if success
  12585.                       RC_WARN (5) if border of text
  12586.  
  12587.  
  12588.                                          221
  12589.  
  12590.  
  12591.  
  12592.  
  12593.  
  12594.       Example:        COLUMN 5    /* Move 5 characters right  */
  12595.  
  12596.  
  12597.  
  12598.     TEXT              Write the text argument at current cursor position
  12599.  
  12600.       Command format: TEXT text
  12601.  
  12602.       Return values:  None.
  12603.  
  12604.       Return codes:   RC_OK (0)
  12605.  
  12606.       Example:        TEXT ' this text will be written'
  12607.  
  12608.  
  12609.     NEWLINE           Output a CR character
  12610.  
  12611.       Command format: NEWLINE
  12612.  
  12613.       Return values:  None.
  12614.  
  12615.       Return codes:   RC_OK (0)
  12616.  
  12617.       The command has the same effect as pressing the enter key.
  12618.  
  12619.       Example:        NEWLINE
  12620.  
  12621.  
  12622.     INSLINE           Insert en empty line at the cursor position
  12623.  
  12624.       Command format: INSLINE
  12625.  
  12626.       Return values:  None.
  12627.  
  12628.       Return codes:   RC_OK (0)
  12629.  
  12630.       Example:        INSLINE
  12631.  
  12632.  
  12633.     DELCHAR           Delete character under cursor
  12634.  
  12635.       Command format: DELCHAR
  12636.  
  12637.       Return values:  None.
  12638.  
  12639.       Return codes:   RC_OK (0)
  12640.  
  12641.       Example:        DELCHAR
  12642.  
  12643.  
  12644.  
  12645.                                          222
  12646.  
  12647.  
  12648.  
  12649.  
  12650.  
  12651.     DELLINE           Delete cursor line
  12652.  
  12653.       Command format: DELLINE
  12654.  
  12655.       Return values:  None.
  12656.  
  12657.       Return codes:   RC_OK (0)
  12658.  
  12659.       Example:        DELLINE
  12660.  
  12661.  
  12662.     GETTEXT           Get the content of cursor line
  12663.  
  12664.       Command format: GETTEXT
  12665.  
  12666.       Return values:  The cursor line.
  12667.  
  12668.       Return codes:   RC_OK (0)
  12669.  
  12670.       Example:        GETTEXT
  12671.  
  12672.  
  12673.     WRITESTATUS       Write text in status line
  12674.  
  12675.       Command format: WRITESTATUS text
  12676.  
  12677.       Return values:  None.
  12678.  
  12679.       Return codes:   RC_OK (0)
  12680.  
  12681.       Example:        WRITESTATUS 'this text will be written'
  12682.  
  12683.  
  12684.     GETFILE           Get file from file requester
  12685.  
  12686.       Command format: GETFILE [FILENAME=<Name>][HAIL=<HailText>]
  12687.  
  12688.       Return values:  Selected file name (including full path).
  12689.  
  12690.       Return codes:   RC_OK (0) if success
  12691.                       RC_WARN (5) if CANCEL gadget presse
  12692.  
  12693.       The command will open a file requester. If a file name is specified this
  12694.       name will be written as the current file. The hail test will be written
  12695.       in the top of the file requester window.
  12696.  
  12697.       Example:        GETFILE FILENAME=System.mod HAIL=Select a module
  12698.  
  12699.  
  12700.  
  12701.  
  12702.                                          223
  12703.  
  12704.  
  12705.  
  12706.  
  12707.  
  12708.     INSERT            Set insert mode
  12709.  
  12710.       Command format: INSERT [ON|OF]
  12711.  
  12712.       Return values:  ON or OFF dependent  on the  insert mode  state after
  12713.                       the command is executed.
  12714.  
  12715.       Return codes:   RC_OK (0)
  12716.  
  12717.       Flip insert mode or set insert mode to on or off.
  12718.  
  12719.       Example:        INSERT ON
  12720.  
  12721.  
  12722.  
  12723.     ENTERINSERT       Set enter mode
  12724.  
  12725.       Command format: ENTERINSERT [ON|OF]
  12726.  
  12727.       Return values:  ON  or  OFF  dependent  on the enter mode state after
  12728.                       the command is executed.
  12729.  
  12730.       Return codes:   RC_OK (0)
  12731.  
  12732.       Flip enter mode or set enter mode to on or off.
  12733.  
  12734.       Example:        ENTERINSERT ON
  12735.  
  12736.  
  12737.  
  12738.   2 The CodeMan AREXX interface.
  12739.  
  12740.   The  CodeMan  AREXX  port  is  named  Comal.CodeMan.  The  AREXX commands
  12741.   accepted by the are:
  12742.  
  12743.  
  12744.     KILL              Remove the CodeMan process
  12745.  
  12746.       Command format: KILL
  12747.  
  12748.       Return values:  None
  12749.  
  12750.       Return codes:   RC_OK (0) if success
  12751.                       RC_WARN (5) if the command failed
  12752.  
  12753.       Example:        KILL
  12754.  
  12755.  
  12756.  
  12757.  
  12758.  
  12759.                                          224
  12760.  
  12761.  
  12762.  
  12763.  
  12764.  
  12765.     OPEN              Create new program buffer
  12766.  
  12767.       Command format: OPEN [MEMORY=size]
  12768.  
  12769.       Return values:  An address which is used to identify the buffer.
  12770.  
  12771.       Return codes:   RC_OK (0) if success
  12772.                       RC_ERROR (10) if the command failed
  12773.  
  12774.       A new  program buffer  is created. If MEMORY is not specified the de-
  12775.       fault value $8000 will be used.
  12776.  
  12777.       Example:        OPEN MEMORY=25000
  12778.  
  12779.  
  12780.     CLOSE             Close program buffer opened by the OPEN command.
  12781.  
  12782.       Command format: CLOSE ID=Id
  12783.  
  12784.       Return values:  None
  12785.  
  12786.       Return codes:   RC_OK (0) if success
  12787.                       RC_ERROR (10) if the program buffer was not found
  12788.  
  12789.       A program buffer opened by the  OPEN  command  is  closed.  The argu-
  12790.       ment Id is the address returned by the OPEN command.
  12791.  
  12792.       Example:        CLOSE ID=BUFFER
  12793.  
  12794.  
  12795.     CLEAR             Clear program buffer
  12796.  
  12797.       Command format: CLEAR ID=Id
  12798.  
  12799.       Return values:  None
  12800.  
  12801.       Return codes:   RC_OK (0) if success
  12802.                       RC_ERROR (10) if the program buffer was not found
  12803.  
  12804.       The argument Id is the address returned by the OPEN command.
  12805.  
  12806.       Example:        CLEAR ID=BUFFER
  12807.  
  12808.  
  12809.     LOAD              Load program file into program buffer
  12810.  
  12811.       Command format: LOAD ID=Id FILENAME=Name
  12812.  
  12813.       Return values:  None
  12814.  
  12815.  
  12816.                                          225
  12817.  
  12818.  
  12819.  
  12820.  
  12821.  
  12822.       Return codes:   RC_OK (0) if success
  12823.                       RC_ERROR (10) if the buffer or file was not found
  12824.  
  12825.       A program  stored as  a code  file if  loaded. The argument Id is the
  12826.       address returned by the OPEN command.
  12827.  
  12828.       Example:        LOAD ID=BUFFER FILENAME=MyFile
  12829.  
  12830.  
  12831.     SAVE              Save program buffer as a code program file.
  12832.  
  12833.       Command format: SAVE ID=Id FILENAME=Name
  12834.  
  12835.       Return values:  None
  12836.  
  12837.       Return codes:   RC_OK (0) if success
  12838.                       RC_ERROR (10) if the no buffer or write error
  12839.  
  12840.       The content of the program buffer is stored as a code file. The argu-
  12841.       ment Id is the address returned by the OPEN command.
  12842.  
  12843.       Example:        SAVE ID=BUFFER FILENAME=MyFile
  12844.  
  12845.  
  12846.     MAKECODE          Generate intermediate code
  12847.  
  12848.       Command format: MAKECODE ID=Id ProgramLine
  12849.  
  12850.       Return values:  Address of the generated code.
  12851.  
  12852.       Return codes:   RC_OK (0) if success
  12853.                       RC_ERROR (10) else
  12854.  
  12855.       Intermediate code for the ASCII program line specified as argument is
  12856.       generated. The address of the generated code is returned.
  12857.  
  12858.       Example:        MAKECODE ID=BUFFER 'IF Alfa=7 THEN'
  12859.  
  12860.  
  12861.     MAKEDIREC         Generate intermediate code for direct command
  12862.  
  12863.       Command format: MAKEDIREC ID=Id ProgramLine
  12864.  
  12865.       Return values:  Address of the generated code.
  12866.  
  12867.       Return codes:   RC_OK (0) if success
  12868.                       RC_ERROR (10) else
  12869.  
  12870.       Intermediate code for the command specified as argument is generated.
  12871.       The address of the generated code is returned.
  12872.  
  12873.                                          226
  12874.  
  12875.  
  12876.  
  12877.  
  12878.  
  12879.  
  12880.       Example:        MAKEDIREC ID=BUFFER 'PRINT sin(1)'
  12881.  
  12882.  
  12883.     MAKEASCII         Change intermediate code to ASCII
  12884.  
  12885.       Command format: MAKECODE ID=Id
  12886.  
  12887.       Return values:  Address of the generated ASCII line.
  12888.  
  12889.       Return codes:   RC_OK (0) if success
  12890.                       RC_ERROR (10) else
  12891.  
  12892.       An ASCII text line for the current buffer line is generated. The address
  12893.       of the generated line is returned.
  12894.  
  12895.       Example:        MAKEASCII ID=BUFFER
  12896.  
  12897.  
  12898.     INSERT            Insert code in the program buffer
  12899.  
  12900.       Command format: INSERT ID=Id
  12901.  
  12902.       Return values:  None.
  12903.  
  12904.       Return codes:   RC_OK (0) if success
  12905.                       RC_ERROR (10) else
  12906.  
  12907.       The code generated by the  last  MAKECODE  or  MAKEDIREC  is inserted
  12908.       at the current position of the buffer pointer.
  12909.  
  12910.       Example:        INSERT ID=BUFFER
  12911.  
  12912.  
  12913.     DELETE            Delete the current buffer line
  12914.  
  12915.       Command format: DELETE ID=Id
  12916.  
  12917.       Return values:  None
  12918.  
  12919.       Return codes:   RC_OK (0) if success
  12920.                       RC_ERROR (10) else
  12921.  
  12922.       Example:        DELETE ID=BUFFER
  12923.  
  12924.  
  12925.     REPLACE           Replace code in the program buffer
  12926.  
  12927.       Command format: REPLACE ID=Id
  12928.  
  12929.  
  12930.                                          227
  12931.  
  12932.  
  12933.  
  12934.  
  12935.  
  12936.       Return values:  None.
  12937.  
  12938.       Return codes:   RC_OK (0) if success
  12939.                       RC_ERROR (10) else
  12940.  
  12941.       The current line in the program buffer is replaced by the code genera-
  12942.       ted by the last MAKECODE or MAKEDIREC.
  12943.  
  12944.       Example:        REPLACE ID=BUFFER
  12945.  
  12946.  
  12947.     POSITION          Move buffer pointer to specified position
  12948.  
  12949.       Command format: POSITION ID=Id <place>  where place is:
  12950.                         SOF start of file
  12951.                         EOF end of file
  12952.  
  12953.       Return values:  None
  12954.  
  12955.       Return codes:   RC_OK (0) if success
  12956.                       RC_ERROR (10) else
  12957.  
  12958.       Example.        POSITION ID=BUFFER SOF
  12959.  
  12960.  
  12961.     LINE              Move buffer pointer up/down specified number of lines
  12962.  
  12963.       Command format: LINE ID=Id <number>
  12964.  
  12965.       Return values:  None.
  12966.  
  12967.       Return codes:   RC_OK (0) if success
  12968.                       RC_WARN (5) if border of text
  12969.                       RC_ERROR (10) else
  12970.  
  12971.       Example:        LINE ID=BUFFER -5 /* Move 5 lines down  */
  12972.  
  12973.  
  12974.  
  12975.  
  12976.   3 The interpreter AREXX interface.
  12977.  
  12978.   For each interpreter opened a separate  process is  started with  its own
  12979.   AREXX port.  The name  of the port is Comal.Interpreter.<id>. For the in-
  12980.   terpreters opened by the editor the  <Id> if  001, 002  etc. For instance
  12981.   Comal.Interpreter.001.
  12982.  
  12983.   Only two AREXX commands are accepted by the interpreter:
  12984.  
  12985.  
  12986.  
  12987.                                          228
  12988.  
  12989.  
  12990.  
  12991.  
  12992.  
  12993.     KILL              Remove the Interpreter master
  12994.  
  12995.       Command format: KILL
  12996.  
  12997.       Return values:  None
  12998.  
  12999.       Return codes:   RC_OK (0) if success
  13000.                       RC_WARN (5) if the command failed
  13001.  
  13002.       Example:        KILL
  13003.  
  13004.  
  13005.     EXECUTE           Load and execute program file.
  13006.  
  13007.       Command format:
  13008.           EXECUTE FILENAME=Name [WORKSPACE=Size] [STACK=Size]
  13009.  
  13010.       Return values:  None
  13011.  
  13012.       Return codes:   RC_OK (0) if success
  13013.                       RC_WARN (10) else
  13014.  
  13015.       A program  stored on  disk in  code form  is loaded  and executed. If
  13016.       WORKSPACE is not specified the default size $8000  is used.  If STACK
  13017.       is not specified the default stack size $4000 is used.
  13018.  
  13019.       Example:        EXECUTE FILENAME=Comal:Programs/GraphDemo
  13020.  
  13021.  
  13022.  
  13023.   4 An AREXX script example.
  13024.  
  13025.   The following script will cut off a marked block and save it on disk as a
  13026.   code file. This is done by opening a separate program buffer and move the
  13027.   block into this buffer line by line.
  13028.  
  13029.  
  13030.     /* Save block as code file  */
  13031.  
  13032.     OPTIONS RESULTS
  13033.     'BLOCKSIZE'
  13034.     IF RC > 0 
  13035.       THEN DO
  13036.         OPTIONS
  13037.         WRITESTATUS 'No block marked'
  13038.       END
  13039.       ELSE DO
  13040.         BlockSize = RESULT
  13041.         IF ARG() = 0
  13042.         THEN DO
  13043.  
  13044.                                          229
  13045.  
  13046.  
  13047.  
  13048.  
  13049.  
  13050.           'GETFILE'
  13051.           File = RESULT
  13052.         END
  13053.         ELSE DO
  13054.           File = ARG(1)
  13055.         END
  13056.         IF RC = 0
  13057.         THEN DO
  13058.           'BLOCK'
  13059.           IF BlockSize < 0
  13060.           THEN DO
  13061.             OPTIONS
  13062.             'LINE' BlockSize
  13063.             BlockLen = -BlockSize+1;
  13064.             BlockSize =0
  13065.           END
  13066.           ELSE DO
  13067.             BlockLen = BlockSize+1;
  13068.             BlockSize = -BlockSize
  13069.           END
  13070.           address 'Comal.CodeMan'
  13071.           OPTIONS RESULTS
  13072.           'OPEN'
  13073.           ID = RESULT
  13074.           DO BlockLen
  13075.             address
  13076.             OPTIONS RESULTS
  13077.             'GETTEXT'
  13078.             Line = RESULT
  13079.             'CURSOR DOWN'
  13080.             address
  13081.             OPTIONS
  13082.             MAKECODE 'ID ' ID Line
  13083.             INSERT 'ID ' ID
  13084.             'LINE ID ' ID 1
  13085.           END
  13086.           'SAVE ID ' ID FILENAME File
  13087.           'CLOSE' 'ID ' ID
  13088.           address
  13089.           'LINE' BlockSize
  13090.         END
  13091.       END
  13092.  
  13093.  
  13094.  
  13095.  
  13096.  
  13097.  
  13098.  
  13099.  
  13100.  
  13101.                                          230
  13102.  
  13103.  
  13104.  
  13105.  
  13106.  
  13107.   VIII. COMAL IO DEVICES
  13108.  
  13109.  
  13110.   1 What is a Comal device?
  13111.  
  13112.   A Comal IO device is a sort of a file with a predefined name. The name of
  13113.   a Comal device always ends with a colon (:). At the start of the Comal sy-
  13114.   stem three Comal devices are defined:
  13115.  
  13116.     "ds:"   the standard IO window
  13117.     "kb:"   the keyboard attached the the IO window
  13118.     "lp:"   the printer
  13119.  
  13120.  
  13121.   These device  names can  be used  in a  OPEN FILE  satements and a SELECT
  13122.   statements.
  13123.  
  13124.   Example:
  13125.  
  13126.     OPEN FILE 1,"ds:",WRITE
  13127.     SELECT OUTPUT "lp:"
  13128.  
  13129.  
  13130.   The devices are primariy intented for  use in  SELECT statements.  At the
  13131.   start of a program execution implicite
  13132.  
  13133.     SELECT OUTPUT "ds:"
  13134.  
  13135.   and
  13136.  
  13137.     SELECT INPUT "kb:"
  13138.  
  13139.   are executed.
  13140.  
  13141.  
  13142.   2 Making new devices.
  13143.  
  13144.   It is possible to add new devices or to replace one of the predefined devi-
  13145.   ces. A new device is added by calling  the internal  Comal procedure Add-
  13146.   ComalDevice (found in the module SystemCode).
  13147.  
  13148.   All devices are linked together in a list and AddComalDevice links the new
  13149.   device into the start of this list. Thus adding a device having  the same
  13150.   name as an excisting device will in fact replace that device.
  13151.  
  13152.   A device is removed from the list by calling RemComalDevice.
  13153.  
  13154.   The procedure AddComalDevice is called with an initialized device structure
  13155.   that completely describes the device:
  13156.  
  13157.  
  13158.                                          231
  13159.  
  13160.  
  13161.  
  13162.  
  13163.  
  13164.     STRUC IoDevice
  13165.       DIM NextDevice OF POINTER TO IoDevice
  13166.       DIM Name OF ULONG
  13167.       DIM Type OF USHORT
  13168.       DIM Reserved OF SHORT
  13169.       DIM Open OF ULONG
  13170.       DIM Close OF ULONG
  13171.       DIM Read OF ULONG
  13172.       DIM Write OF ULONG
  13173.       DIM ReadLn OF ULONG
  13174.       DIM WriteLn OF ULONG
  13175.       DIM Scan OF ULONG
  13176.       DIM GetStrmPtr OF ULONG
  13177.       DIM SetStrmPtr OF ULONG
  13178.       DIM StreamErr OF ULONG
  13179.     ENDSTRUC IoDevice
  13180.  
  13181.  
  13182.   Field desription:
  13183.  
  13184.     NextDevice
  13185.  
  13186.       A pointer to the next device in the list of devices. Set by the Comal
  13187.       system.
  13188.  
  13189.  
  13190.     Name
  13191.  
  13192.       A pointer to the name of the device. Must end with a colon (:).
  13193.  
  13194.  
  13195.     Type
  13196.  
  13197.       The possible device types are:
  13198.  
  13199.         SEQ_DEVICE (0)  sequential device (for instance a printer)
  13200.         CRT_DEVICE (1)  used by windows
  13201.         KBD_DEVICE (2)  keyboard
  13202.         RBF_DEVICE (3)  random access device
  13203.  
  13204.  
  13205.     Open          open device
  13206.  
  13207.       An address of an open procedure of the form:
  13208.  
  13209.         FUNC Open(Name OF ULONG,Mode OF USHORT,REF Eof OF SHORT)
  13210.  
  13211.       where
  13212.  
  13213.         Name is  a null  terminated string  of characters. The start of the
  13214.  
  13215.                                          232
  13216.  
  13217.  
  13218.  
  13219.  
  13220.  
  13221.           string is  the device  name. The  characters after  the colon are
  13222.           transfered  from  the  name  in  the OPEN or SELECT statement and
  13223.           can be used to specify special parameters for the device (for in-
  13224.           stance: SELECT OUTPUT "sp: baud=1200").
  13225.  
  13226.  
  13227.         Mode is one or more of the following BITORed together:
  13228.  
  13229.           ACCESS_READ (1)   read only device (such as a keyboard)
  13230.           ACCESS_WRITE (2)  write only device (such as a printer)
  13231.           ACCESS_NEW (4)    delete excisting (if window for instance)
  13232.  
  13233.       At return the function sets the parameter Eof (end of file) to TRUE or
  13234.       FALSE and returns an ULONG which  is  used  to  indentify  the device
  13235.       (zero means error).
  13236.  
  13237.  
  13238.     Close         close the device
  13239.  
  13240.       An address of a procedure of the form:
  13241.  
  13242.         PROC Close(Id OF ULONG)
  13243.  
  13244.  
  13245.       The procedure  is called  when a  CLOSE statement is executed or when
  13246.       another device is selected in a SELECT statement. Id is the identifier
  13247.       returned by the open procedure.
  13248.  
  13249.       The procedure should not necessarily close the device. If for instance
  13250.       the device is a CRT_DEVICE like "ds:" it  is not  smart to  close the
  13251.       window each time another device is selected by the SELECT statement.
  13252.  
  13253.  
  13254.     Read          read a block of bytes
  13255.  
  13256.       An address of a function of the form:
  13257.  
  13258.         FUNC Read(Id,Data,REF MaxBytes,REF BreakMask) OF SHORT
  13259.  
  13260.       where
  13261.  
  13262.         Id OF ULONG is the device identifier returned by OPEN.
  13263.         Data OF ULONG is the address of a read buffer.
  13264.         MaxByte OF LONG is the number of bytes to read.
  13265.         BreakMask  OF  ULONG  is  a  mask  of signals that should break the
  13266.           reading. Not all devices supports this facility.
  13267.  
  13268.       Before return the routine must set the actual number of bytes read in
  13269.       MaxBytes and then return -1 (if error), 0 if OK or 1 if end of stream
  13270.       was reached.
  13271.  
  13272.                                          233
  13273.  
  13274.  
  13275.  
  13276.  
  13277.  
  13278.  
  13279.  
  13280.     Write         write a block of bytes
  13281.  
  13282.       An address of a function of the form
  13283.  
  13284.         FUNC Write(Id,Data,Length) OF SHORT
  13285.  
  13286.       where
  13287.  
  13288.         Id OF ULONG is the device identifier returned by OPEN.
  13289.         Data OF ULONG is the address of the data to write.
  13290.         Length OF LONG is the number of bytes to write.
  13291.  
  13292.       Before return the routine must set the actual number of bytes written
  13293.       in Length and then return TRUE (1) if OK or FALSE (0) if error.
  13294.  
  13295.       If this field is set for a KBD_DEVICE, guide texts in INPUT statements
  13296.       are sent to this function.
  13297.  
  13298.  
  13299.     ReadLn        read one line
  13300.  
  13301.       An address of a function of the form
  13302.  
  13303.         FUNC ReadLn(Id,Data,REF MaxLength) OF SHORT
  13304.  
  13305.       where
  13306.  
  13307.         Id OF ULONG is the device identifier returned by OPEN.
  13308.         Data OF ULONG is the address of a read buffer.
  13309.         MaxByte OF LONG is the maximal number of bytes to read.
  13310.  
  13311.       The routine reads characters until a line end character is read or Max-
  13312.       Bytes characters are read. The routine is responsible for editing during
  13313.       the input (if CRT_DEVICE).
  13314.  
  13315.       Before return the routine must set the actual number of bytes read in
  13316.       MaxBytes (The line end character not included) and then return -1 (if
  13317.       error), 0 if OK or 1 if end of stream was reached.
  13318.  
  13319.  
  13320.     WriteLn         write one line
  13321.  
  13322.       An address of a function of the form
  13323.  
  13324.         FUNC WriteLn(Id,Line,Length) OF SHORT
  13325.  
  13326.       where
  13327.  
  13328.  
  13329.                                          234
  13330.  
  13331.  
  13332.  
  13333.  
  13334.  
  13335.         Id OF ULONG is the device identifier returned by OPEN.
  13336.         Line OF ULONG is the address of the line to write.
  13337.         Length OF LONG is the length of the line to write.
  13338.  
  13339.       The routine must terminate by writing a line termination character to
  13340.       the device.  Before return the routines must set the actual number of
  13341.       bytes written in Length and then return TRUE (1) if  OK or  FALSE (0)
  13342.       if error.
  13343.  
  13344.  
  13345.     Scan          scan the device
  13346.  
  13347.       An address of a function of the form
  13348.  
  13349.         FUNC Scan(Id,Data,REF Length) OF SHORT
  13350.  
  13351.       where
  13352.  
  13353.         Id OF ULONG is the device identifier returned by OPEN.
  13354.         Data OF ULONG is the address of a read buffer.
  13355.         Length OF LONG is the length of the read buffer.
  13356.  
  13357.       The function should test if there are "characters" ready in the device.
  13358.       If this is the case ot should return the first "character". Otherwise it
  13359.       should return  without reading  any characters.  A "character" may be
  13360.       more than one byte.  A keyboard  for instance  returns more  than one
  13361.       byte if a function key is pressed.
  13362.  
  13363.       Before return the routine must set the actual number of bytes read in
  13364.       Length and then return -1 (if error), 0 if OK or 1  if end  of stream
  13365.       was reached.
  13366.  
  13367.  
  13368.     Get           get position of the stream pointer
  13369.  
  13370.       Get is the address of a function. The format of this function depends
  13371.       on the device type.
  13372.  
  13373.         CRT_DEVICE:   FUNC Get(Id,REF Row, REF Col) OF SHORT
  13374.  
  13375.           where
  13376.  
  13377.             Id OF ULONG is the device identifier.
  13378.             Row OF SHORT is used to return row number of the cursor
  13379.             Col OF SHORT is used to return column number of the cursor
  13380.  
  13381.         RBF_DEVICE:   FUNC Get(Id,REF Offset) OF SHORT
  13382.  
  13383.           where
  13384.  
  13385.  
  13386.                                          235
  13387.  
  13388.  
  13389.  
  13390.  
  13391.  
  13392.             Id OF ULONG is the device identifier.
  13393.             Offset OF LONG is used to  return  the  current  offset  of the
  13394.               stream pointer.
  13395.  
  13396.       Other devices should set these fields to zero. For both functions the
  13397.       return value is TRUE if operation succeded and otherwise FALSE.
  13398.  
  13399.  
  13400.     Set           set position of the stream pointer
  13401.  
  13402.       Set is the address of a function. The format of this function depends
  13403.       on the device type.
  13404.  
  13405.         CRT_DEVICE:
  13406.  
  13407.             FUNC Set(Id,Row,Col) OF SHORT
  13408.  
  13409.           where
  13410.  
  13411.             Id OF ULONG is the device identifier.
  13412.             Row OF SHORT is the new row number of the cursor
  13413.             Col OF SHORT is the new column number of the cursor
  13414.  
  13415.  
  13416.         RBF_DEVICE:
  13417.  
  13418.             FUNC Get(Id,REF Offset) OF SHORT
  13419.  
  13420.           where
  13421.  
  13422.             Id OF ULONG is the device identifier.
  13423.             Offset OF LONG is the new offset of the stream pointer.
  13424.  
  13425.       Other devices should set these fields to zero. For both functions the
  13426.       return value is TRUE if operation succeded and otherwise FALSE.
  13427.  
  13428.  
  13429.     StreamErr
  13430.  
  13431.       For the time being not used. Set to zero.
  13432.  
  13433.  
  13434.   The fields Name, Type, Open, Close, Get (CRT  and RBF)  and Set  (CRT and
  13435.   RBF) must  be set. Other fields may be set to zero if the device does not
  13436.   support the function.
  13437.  
  13438.  
  13439.   The following module adds a serial device "sp:" to the list of Comal devices:
  13440.  
  13441.  
  13442.  
  13443.                                          236
  13444.  
  13445.  
  13446.  
  13447.  
  13448.  
  13449.   // Serial device "sp:"
  13450.  
  13451.   MODULE SerialDevice
  13452.  
  13453.     USE System
  13454.     USE SystemCode
  13455.     USE PortObjects
  13456.     USE IoObjects
  13457.     USE ExecLibrary
  13458.  
  13459.     STRUC IOTArray
  13460.       DIM TermArray0 OF ULONG
  13461.       DIM TermArray1 OF ULONG
  13462.     ENDSTRUC IOTArray
  13463.  
  13464.     STRUC IOExtSer  // Standard IO request to serial.device
  13465.       INHERIT IOStdReq             // Standard IO-request
  13466.       DIM io_CtrlChar OF ULONG     // xON, xOFF, INQ, ACK
  13467.       DIM io_RBufLen OF ULONG      // length of read buffer
  13468.       DIM io_ExtFlags OF ULONG     // Not used
  13469.       DIM io_Baud OF ULONG         // Baud rate
  13470.       DIM io_BrkTime OF ULONG      // duration of break signal in micros
  13471.       DIM io_TermArray OF IOTArray // Termination characters
  13472.       DIM io_ReadLen OF UBYTE      // Bits per read character
  13473.       DIM io_WriteLen OF UBYTE     // Bits per write character
  13474.       DIM io_StopBits OF UBYTE     // Number of stop bits
  13475.       DIM io_SerFlags OF UBYTE     // Flags set by serial device
  13476.       DIM io_Status OF USHORT
  13477.     ENDSTRUC IOExtSer
  13478.  
  13479.     STRUC IoDevice
  13480.       DIM NextDevice OF POINTER TO IoDevice
  13481.       DIM Name OF ULONG       // Pointer to device name 'sp:'
  13482.       DIM Type OF USHORT      // Type of device
  13483.       DIM Reserved OF SHORT
  13484.       DIM Open OF ULONG
  13485.       DIM Close OF ULONG
  13486.       DIM Read OF ULONG
  13487.       DIM Write OF ULONG
  13488.       DIM ReadLn OF ULONG
  13489.       DIM WriteLn OF ULONG
  13490.       DIM Scan OF ULONG
  13491.       DIM GetStrmPtr OF ULONG
  13492.       DIM SetStrmPtr OF ULONG
  13493.       DIM StreamErr OF ULONG
  13494.     ENDSTRUC IoDevice
  13495.  
  13496.     DIM CMD_READ OF SHORT
  13497.     DIM CMD_WRITE OF SHORT
  13498.     DIM CMD_NONSTD OF SHORT
  13499.  
  13500.                                          237
  13501.  
  13502.  
  13503.  
  13504.  
  13505.  
  13506.  
  13507.     CMD_READ:=2
  13508.     CMD_WRITE:=3
  13509.     CMD_NONSTD:=9
  13510.  
  13511.     DIM SerReq OF POINTER TO IOExtSer
  13512.     DIM ReplyPort OF POINTER TO MsgPort
  13513.     DIM DevOpen OF BOOL
  13514.     DIM SerDevice OF IoDevice
  13515.     DIM SerDevName$ OF 3
  13516.  
  13517.     SerDevName$:="sp:"
  13518.     SerDevice.Name:=ADR(SerDevName$)
  13519.     SerDevice.Type:=0         // Sequential device
  13520.     SerDevice.Open:=ADR(SerOpen(,,))
  13521.     SerDevice.Close:=ADR(SerClose())
  13522.     SerDevice.Read:=ADR(SerRead(,,,))
  13523.     SerDevice.Write:=ADR(SerWrite(,,))
  13524.     SerDevice.ReadLn:=ADR(SerReadLn(,,))
  13525.     SerDevice.WriteLn:=ADR(SerWriteLn(,,))
  13526.     AddComalDevice(ADR(SerDevice))
  13527.  
  13528.     FUNC SerOpen(Name OF ULONG,Mode OF USHORT,REF Eof OF SHORT)
  13529.                                                           OF ULONG
  13530.       ALLOCATE(SerReq,MEMF_PUBLIC)
  13531.       ALLOCATE(ReplyPort,MEMF_PUBLIC)
  13532.       SerReq@.mn_ReplyPort:=ReplyPort
  13533.  
  13534.       // Open serial.device'
  13535.       IF OpenDevice("serial.device",0,SerReq,0) THEN
  13536.         DEALLOCATE(SerReq)
  13537.         RETURN 0
  13538.       ENDIF
  13539.       DevOpen:=TRUE
  13540.  
  13541.       // Set TermArray
  13542.       SerReq@.io_Command:=CMD_NONSTD+2
  13543.       SerReq@.io_TermArray.TermArray0:=$1C0A0A0A
  13544.       SerReq@.io_TermArray.TermArray1:=$0A0A0A0A
  13545.       SerReq@.Do  // Set TermArray
  13546.  
  13547.       Eof:=FALSE
  13548.       RETURN $FFFFFFFF
  13549.     ENDFUNC SerOpen
  13550.  
  13551.     PROC SerClose(Id OF ULONG)
  13552.       IF DevOpen THEN
  13553.         SerReq@.Abort
  13554.         dummy:=SerReq@.mn_ReplyPort@.Get
  13555.         CloseDevice(SerReq)
  13556.  
  13557.                                          238
  13558.  
  13559.  
  13560.  
  13561.  
  13562.  
  13563.         DEALLOCATE(SerReq)
  13564.         DEALLOCATE(ReplyPort)
  13565.         DevOpen:=FALSE
  13566.       ENDIF
  13567.     ENDPROC SerClose
  13568.  
  13569.     FUNC SerRead(Id OF ULONG,Buffer OF ULONG,REF MaxLen OF, 
  13570.                  LONG,BreakMask OF ULONG) OF SHORT
  13571.       SerReq@.io_SerFlags:=SerReq@.io_SerFlags BITAND %10111111
  13572.       SerReq@.io_Command:=CMD_READ
  13573.       SerReq@.io_Length:=MaxLen
  13574.       SerReq@.io_Data:=Buffer
  13575.       SerReq@.Send               // Read data
  13576.       SerReq@.Wait
  13577.       MaxLen:=SerReq@.io_Actual  // Return number of bytes read
  13578.     ENDFUNC SerRead
  13579.  
  13580.     FUNC SerWrite(Id OF ULONG,Data OF ULONG,REF Length OF LONG)
  13581.                                                            OF BOOL
  13582.       SerReq@.io_Command:=CMD_WRITE
  13583.       SerReq@.io_Length:=Length
  13584.       SerReq@.io_Data:=Data
  13585.       SerReq@.Send               // Write data
  13586.       SerReq@.Wait
  13587.       IF SerReq@.io_Error THEN
  13588.         RETURN FALSE
  13589.       ELSE
  13590.         RETURN TRUE
  13591.       ENDIF
  13592.     ENDFUNC SerWrite
  13593.  
  13594.     FUNC SerReadLn(Id OF ULONG,Buffer OF ULONG,REF MaxLen OF LONG)
  13595.                                                              OF SHORT
  13596.       LOCAL Ptr OF POINTER TO UBYTE
  13597.  
  13598.       SerReq@.io_SerFlags:=SerReq@.io_SerFlags BITOR %01000000
  13599.       SerReq@.io_Command:=CMD_READ
  13600.       SerReq@.io_Length:=MaxLen
  13601.       SerReq@.io_Data:=Buffer
  13602.       SerReq@.Send                // Read data
  13603.       SerReq@.Wait
  13604.       IF SerReq@.io_Error THEN
  13605.         RETURN -1
  13606.       ENDIF
  13607.       Ptr:=ADR(Buffer)+SerReq@.io_Actual-1
  13608.       CASE Ptr@ OF
  13609.       WHEN $1C
  13610.         MaxLen:=SerReq@.io_Actual-1
  13611.         RETURN 1        // End of file
  13612.       WHEN $0A
  13613.  
  13614.                                          239
  13615.  
  13616.  
  13617.  
  13618.  
  13619.  
  13620.         MaxLen:=SerReq@.io_Actual-1
  13621.         RETURN 0
  13622.       OTHERWISE
  13623.         MaxLen:=SerReq@.io_Actual
  13624.         RETURN 0
  13625.       ENDCASE
  13626.     ENDFUNC SerReadLn
  13627.  
  13628.     FUNC SerWriteLn(Id OF ULONG,Data OF ULONG,REF Length OF LONG)
  13629.                                                            OF BOOL
  13630.       LOCAL ch OF UBYTE
  13631.  
  13632.       SerReq@.io_Command:=CMD_WRITE
  13633.       SerReq@.io_Length:=Length
  13634.       SerReq@.io_Data:=Data
  13635.       SerReq@.Send               // Write data
  13636.       SerReq@.Wait
  13637.       IF SerReq@.io_Error THEN
  13638.         RETURN FALSE
  13639.       ENDIF
  13640.       ch:=$0A
  13641.       SerReq@.io_Command:=CMD_WRITE
  13642.       SerReq@.io_Length:=1
  13643.       SerReq@.io_Data:=ADR(ch)
  13644.       SerReq@.Do     // Write LF
  13645.       IF SerReq@.io_Error THEN
  13646.         RETURN FALSE
  13647.       ELSE
  13648.         RETURN TRUE
  13649.       ENDIF
  13650.     ENDFUNC SerWriteLn
  13651.  
  13652.     PROC SerSignal(s OF LONG) SIGNAL
  13653.       CASE s OF
  13654.       WHEN SIG_CLOSE,SIG_DISCARD
  13655.         RemComalDevice(ADR(SerDevice))
  13656.       OTHERWISE
  13657.         // No action
  13658.       ENDCASE
  13659.     ENDPROC SerSignal
  13660.  
  13661.   ENDMODULE SerialDevice
  13662.  
  13663.  
  13664.   3 Making your own IO window.
  13665.  
  13666.   It is possible to replace the standard IO window opened by the interpreter
  13667.   by your  own window.  To see how this can be done it is necessary to know
  13668.   what is happening before a program is started.
  13669.  
  13670.  
  13671.                                          240
  13672.  
  13673.  
  13674.  
  13675.  
  13676.  
  13677.   When the interpreter receives an execute command the IO is  redirected to
  13678.   the IO  port (see section V.2) and the standard console device closes the
  13679.   execute window (if it is open). The console device closes the window when
  13680.   the signal SIG_CLEAR is send.
  13681.  
  13682.   Then the  program is scanned and during this scanning process all modules
  13683.   are loaded and are initialized by executing the initialization part of the
  13684.   module. A module can use this initialization to add a new "ds:" device and a
  13685.   new "kb:" device.
  13686.  
  13687.   After the scanning an implicite  SELECT  OUTPUT  "ds:"  and  an implicite
  13688.   SELECT INPUT  "kb:" is executed. If a module has added a new "ds:" device
  13689.   and a new "kb:" device these devices are put into the start of the device
  13690.   list and it will be these devices that are used by the SELECT statements.
  13691.  
  13692.   As a  consequence your  IO window will be opened and the standard IO win-
  13693.   dow will not be used.
  13694.  
  13695.   In the directory ModuleDev you will find an example of such a module pro-
  13696.   grammed in C (IoWindow.c and IoWindow.interface).
  13697.  
  13698.  
  13699.  
  13700.  
  13701.  
  13702.  
  13703.  
  13704.  
  13705.  
  13706.  
  13707.  
  13708.  
  13709.  
  13710.  
  13711.  
  13712.  
  13713.  
  13714.  
  13715.  
  13716.  
  13717.  
  13718.  
  13719.  
  13720.  
  13721.  
  13722.  
  13723.  
  13724.  
  13725.  
  13726.  
  13727.  
  13728.                                          241
  13729.  
  13730.  
  13731.  
  13732.  
  13733.  
  13734.   IX. MASHINE CODED MODULES
  13735.  
  13736.   Comal has been designed to be a modular language. It is possible to devide
  13737.   a project into several modules. These modules can be written in as different
  13738.   languages as assembler, C as well as the Comal language itself.
  13739.  
  13740.   Seen from the users of the modules there are no difference in the modules
  13741.   wether they are written in assembler, C or Comal. The routines in the mo-
  13742.   dules are called in exactly the same way. Very often a module is first writ-
  13743.   ten in Comal and then (if necessary) it is rewritten in C or even assembler.
  13744.  
  13745.   In chapter III.9 development of modules in Comal  was described.  In this
  13746.   chapter machine coded modules (written in C or assembler) will be descri-
  13747.   bed.
  13748.  
  13749.  
  13750.   1 The format of a mashine coded module.
  13751.  
  13752.   A mashine coded module consists of three parts:
  13753.  
  13754.     - the interface part
  13755.     - the initialization and signal routines
  13756.     - the routine part (procedures and functions in the module)
  13757.  
  13758.  
  13759.   In the following sections 1.1-1.3 the three parts are described. C program-
  13760.   mers do not need to read these sections.
  13761.  
  13762.  
  13763.   1.1 The interface part.
  13764.  
  13765.   In the interface part of a module all necessary informations about the ex-
  13766.   ported routines are stored (the name and the address of  the routine, the
  13767.   type of the routine and its parameters etc.).
  13768.  
  13769.   The interface  part is  a table of elements of the form (described in not
  13770.   100% correct C):
  13771.  
  13772.     struct NameTable NameTable[NumNames];
  13773.  
  13774.   where the NameTable structure is defined as
  13775.  
  13776.     struct NameTable
  13777.     {
  13778.       void *RoutineAddress;   /* The address of the routine           */
  13779.       struct ProcType *Type;  /* The address of the type descriptor   */
  13780.       char *RoutineName;      /* A pointer to the name of the routine */
  13781.     }
  13782.  
  13783.  
  13784.  
  13785.                                          242
  13786.  
  13787.  
  13788.  
  13789.  
  13790.  
  13791.   The information of the type of the routine is stored in a structure Proc-
  13792.   Type. Routines with the same type can use the same structure.
  13793.  
  13794.   The structure ProcType has the form:
  13795.  
  13796.     struct Param
  13797.     {
  13798.       UBYTE Flags;          /* Set to 0x80 if REF parameter       */
  13799.       BYTE  SecondaryType;  /* Set to zero                        */
  13800.       WORD  PrimaryType;    /* Parameter type (se include files)  */
  13801.     };
  13802.  
  13803.     struct ProcType
  13804.     {
  13805.       WORD TypeId;          /* PROC_ID or FUNC_ID                 */
  13806.       WORD ReturnType;      /* Return type (FUNC) or zero (PROC)  */
  13807.       WORD *TypeDescriptor; /* Set to zero                        */
  13808.       UWORD Flags;
  13809.       UBYTE StackUse1;      /* Stack use of type descriptors      */
  13810.       UBYTE StackUse0;      /* Primary parameter stack use        */
  13811.       UWORD NumPar;         /* Number of formal parameters        */
  13812.       struct Param Param[NumPar];
  13813.     };
  13814.  
  13815.   Set Flags to 0x0001 if it is a string function returning a C string (null ter-
  13816.   minated ASCII string).
  13817.  
  13818.   The stack use are the number of bytes used to transfer the  parameters on
  13819.   the stack.  The secondary stack is used to transfer the address of a type
  13820.   descriptor for structured types  (ARRAY, FUNC  and PROC)  and REF parame-
  13821.   ters. 
  13822.  
  13823.  
  13824.   1.2 The initialization and signal routines.
  13825.  
  13826.   The initialization routine is the very first mashine instructions in the mo-
  13827.   dule. It is a function with the C format:
  13828.  
  13829.     short Init(struct ComalStruc *ComalStruc,struct Module *Module)
  13830.  
  13831.  
  13832.   This means that the addresses of the ComalStruc and the  module structure
  13833.   for the  module in question are pushed onto the stack (as two long words)
  13834.   before a call is made to the first instruction of the module.
  13835.  
  13836.   The initialization routine should as a minimum fill  the module structure
  13837.   with the  address of  the name  table and the number of names in the name
  13838.   table and then return the status code (in D0.W). Zero is the OK code.
  13839.  
  13840.  
  13841.  
  13842.                                          243
  13843.  
  13844.  
  13845.  
  13846.  
  13847.  
  13848.   Very often an initialization routine also stores the address of the Comal-
  13849.   Struc for later use.
  13850.  
  13851.   A signal routine is a procedure with the C format:
  13852.  
  13853.     void signal(short SignalNum)
  13854.  
  13855.  
  13856.   To tell the comal system that there is a signal routine, the address of the
  13857.   routine must be placed in the module structure by the initialization routine.
  13858.   Otherwise there are no difference between a signal routine in a Comal mo-
  13859.   dule and a mashine coded module. The same signal numbers are send.
  13860.  
  13861.   All routines, including the initialization routine and the signal routine, may
  13862.   use registers D0-D1/A0/A1. The content of all other registers must be re-
  13863.   stored before a return.
  13864.  
  13865.  
  13866.   1.3 The routine part.
  13867.  
  13868.   Procedures and functions that are to be exported  from the  module (those
  13869.   referenced in the name table) must have the form used by most C compilers
  13870.   (for instance SAS/C ver. 5.xx).
  13871.  
  13872.   When a procedure or a function is called from Comal, the actual parameters
  13873.   are pushed onto the stack.
  13874.  
  13875.   Float value parameters are pushed as two long words. Value parameters for
  13876.   the integer types are pushed as one long word (byte and short integers are
  13877.   sign extended before they are pushed).
  13878.  
  13879.   Text values are transfered as an address to the text value that is null ter-
  13880.   minated.
  13881.  
  13882.   Parameters of the type  STRUC,  ARRAY,  PROC  and  FUNC  as  well  as REF
  13883.   parameters of any kind are pushed as addresses.
  13884.  
  13885.   Values returned by functions are passed back in register D0 (D0 and D1 if
  13886.   float).
  13887.  
  13888.   All routines may use registers D0-D1/A0/A1. The content of all  other re-
  13889.   gisters must be restored before a return.
  13890.  
  13891.  
  13892.   2 An assembler programmed module.
  13893.  
  13894.   Let us  as an  example show  how a  module is programmed in assembler. We
  13895.   are going to make a module containing the following procedures  and func-
  13896.   tions:
  13897.  
  13898.  
  13899.                                          244
  13900.  
  13901.  
  13902.  
  13903.  
  13904.  
  13905.     FUNC Even(i OF LONG) OF SHORT
  13906.     FUNC Hex$(i OF ULONG)
  13907.     PROC Capital(REF t$)
  13908.  
  13909.  
  13910.   The interface part contains a name table of three elements
  13911.  
  13912.  
  13913.   NameTable:     DC.L    CapitalName      * Name of procedure
  13914.                  DC.L    CapitalType      * Type descriptor
  13915.                  DC.L    Capital          * Routine address
  13916.  
  13917.                  DC.L    HexName
  13918.                  DC.L    HexType
  13919.                  DC.L    Hex
  13920.  
  13921.                  DC.L    EvenName
  13922.                  DC.L    EvenType
  13923.                  DC.L    Even
  13924.  
  13925.   CapitalName:   DC.B    'Capital',0
  13926.   HexName:       DC.B    'Hex$',0
  13927.   EvenName:      DC.B    'Even',0
  13928.  
  13929.  
  13930.   and type descriptors for each function/procedure:
  13931.  
  13932.  
  13933.   CapitalType:   DC.W    ProcTypeId       * Procedure
  13934.                  DC.W    0                * No return value
  13935.                  DC.L    0                * Always set to zero
  13936.                  DC.W    $0000            * No flags
  13937.                  DC.B    4                * Sec. stack (REF)
  13938.                  DC.B    4                * Address = 4 bytes
  13939.                  DC.W    1                * One parameter
  13940.                  DC.B    $80              * REF parameter
  13941.                  DC.B    0                * Always zero
  13942.                  DC.W    StringTypeId     * Parameter type
  13943.  
  13944.   HexType:       DC.W    FuncTypeId       * Function
  13945.                  DC.W    StringTypeId     * Return value
  13946.                  DC.L    0
  13947.                  DC.W    $0001            * C string is returned
  13948.                  DC.B    0                * No sec. stack use
  13949.                  DC.B    4                * Int paramter = 4 bytes
  13950.                  DC.W    1                * One parameter
  13951.                  DC.B    $00              * Value parameter
  13952.                  DC.B    0
  13953.                  DC.W    UlongTypeId      * Parameter type
  13954.  
  13955.  
  13956.                                          245
  13957.  
  13958.  
  13959.  
  13960.  
  13961.  
  13962.   EvenType:      DC.W    FuncTypeId       * Function
  13963.                  DC.W    ShortTypeId      * Return type
  13964.                  DC.L    0
  13965.                  DC.W    $0000            * No flags
  13966.                  DC.B    0                * No sec. stack use
  13967.                  DC.B    4                * Int parameter = 4 bytes
  13968.                  DC.W    1                * One parameter
  13969.                  DC.B    $00              * Value parameter
  13970.                  DC.B    0
  13971.                  DC.W    LongTypeId       * Parameter type
  13972.  
  13973.  
  13974.   The initialization routine is very simple:
  13975.  
  13976.   Init:    MOVE.L  4(A7),ComalStruc         * Store ComalStruc addr
  13977.            MOVE.L  8(A7),A0
  13978.            MOVE.L  #NameTable,MS_Names(A0)  * Name table address
  13979.            MOVE.W  #3,MS_NumName(A0)        * Number of names
  13980.            MOVEQ   #0,D0                    * Initialization OK
  13981.            RTS
  13982.  
  13983.  
  13984.   The complete source for the module looks like:
  13985.  
  13986.  
  13987.   ; Module Demo
  13988.  
  13989.            include 'Comal.i'
  13990.  
  13991.            SECTION DemoCode,CODE
  13992.            CNOP    0,2
  13993.  
  13994.   Start:   MOVE.L  4(A7),ComalStruc         * Store ComalStruc addr
  13995.            MOVE.L  8(A7),A0
  13996.            MOVE.L  #NameTable,MS_Names(A0)  * Name table address
  13997.            MOVE.W  #3,MS_NumName(A0)        * Number of names
  13998.            MOVEQ   #0,D0                    * Initialization OK
  13999.            RTS
  14000.  
  14001.   Capital: MOVE.L  4(A7),A1                 * Get string address
  14002.   CapLoop: MOVE.B  (A1)+,D0                 * Get next character
  14003.            BEQ.S   CapEnd                   * Return if zero
  14004.            CMP.B   #'a',D0                  * Small letter?
  14005.            BCS     CapLoop                  * No -> loop
  14006.            CMP.B   #'z',D0
  14007.            BHI     CapLoop
  14008.            BCLR    #5,-1(A1)                * Change to capital
  14009.            BRA     CapLoop
  14010.   CapEnd:  RTS
  14011.  
  14012.  
  14013.                                          246
  14014.  
  14015.  
  14016.  
  14017.  
  14018.  
  14019.   Hex:     MOVE.L  ComalStruc,A0            * Get address of ComalStruc
  14020.            MOVE.L  CS_CurrWorkBottom(A0),A1 * .. and work space start
  14021.            MOVE.L  A1,D0                    * Set as return value
  14022.            LEA     10(A1),A1                * Reserve 10 bytes
  14023.            MOVE.L  A1,CS_CurrWorkBottom(A0) * Set new bottom
  14024.            MOVE.L  D0,A1                    * Get start of string
  14025.            MOVE.B  #'$',(A1)+               * Start with hex specifier
  14026.            MOVE.B  #'0',(A1)+
  14027.            MOVE.L  4(A7),D1                 * Number to D1
  14028.            BEQ.S   HexEnd                   * Return if zero
  14029.            MOVEM.L D2/D3,-(A7)              * Store registers
  14030.            SUBQ.L  #1,A1                    * Point after $
  14031.            MOVEQ   #8,D3
  14032.            LEA     Digits(PC),A0         
  14033.   HxLoop1: ROL.L   #4,D1                    * Find first non zero digit
  14034.            SUBQ.W  #1,D3
  14035.            MOVE.W  D1,D2
  14036.            AND.W   #$000F,D2
  14037.            BEQ     HxLoop1
  14038.   HxLoop2: MOVE.B  0(A0,D2.W),(A1)+         * Nex hex digit to buffer
  14039.            ROL.L   #4,D1
  14040.            MOVE.W  D1,D2
  14041.            AND.W   #$000F,D2
  14042.            DBRA    D3,HxLoop2
  14043.            MOVEM.L (A7)+,D2/D3
  14044.   HexEnd:  CLR.B   (A1)                     * Terminate string
  14045.            RTS                              * .. and return
  14046.  
  14047.   Digits:  DC.B    '0123456789ABCDEF'
  14048.  
  14049.   Even:    MOVE.L  4(A7),D0
  14050.            ADDQ.L  #1,D0
  14051.            AND.L   #1,D0
  14052.            RTS
  14053.  
  14054.  
  14055.            SECTION DemoData,DATA
  14056.            CNOP    0,2
  14057.  
  14058.   CapitalType:   DC.W    ProcTypeId       * Procedure
  14059.                  DC.W    0                * No return value
  14060.                  DC.L    0                * Always set to zero
  14061.                  DC.W    $0000            * No flags
  14062.                  DC.B    4                * Sec. stack (REF)
  14063.                  DC.B    4                * Address = 4 bytes
  14064.                  DC.W    1                * One parameter
  14065.                  DC.B    $80              * REF parameter
  14066.                  DC.B    0                * Always zero
  14067.                  DC.W    StringTypeId     * Parameter type
  14068.  
  14069.  
  14070.                                          247
  14071.  
  14072.  
  14073.  
  14074.  
  14075.  
  14076.   HexType:       DC.W    FuncTypeId       * Function
  14077.                  DC.W    StringTypeId     * Return value
  14078.                  DC.L    0
  14079.                  DC.W    $0001            * C string is returned
  14080.                  DC.B    0                * No sec. stack use
  14081.                  DC.B    4                * Int paramter = 4 bytes
  14082.                  DC.W    1                * One parameter
  14083.                  DC.B    $00              * Value parameter
  14084.                  DC.B    0
  14085.                  DC.W    UlongTypeId      * Parameter type
  14086.  
  14087.   EvenType:      DC.W    FuncTypeId       * Function
  14088.                  DC.W    ShortTypeId      * Return type
  14089.                  DC.L    0
  14090.                  DC.W    $0000            * No flags
  14091.                  DC.B    0                * No sec. stack use
  14092.                  DC.B    4                * Int parameter = 4 bytes
  14093.                  DC.W    1                * One parameter
  14094.                  DC.B    $00              * Value parameter
  14095.                  DC.B    0
  14096.                  DC.W    LongTypeId       * Parameter type
  14097.  
  14098.  
  14099.   NameTable:     DC.L    CapitalName
  14100.                  DC.L    CapitalType
  14101.                  DC.L    Capital
  14102.  
  14103.                  DC.L    HexName
  14104.                  DC.L    HexType
  14105.                  DC.L    Hex
  14106.  
  14107.                  DC.L    EvenName
  14108.                  DC.L    EvenType
  14109.                  DC.L    Even
  14110.  
  14111.   CapitalName:   DC.B    'Capital',0
  14112.   HexName:       DC.B    'Hex$',0
  14113.   EvenName:      DC.B    'Even',0
  14114.  
  14115.                  SECTION DemoBlock,BSS
  14116.                  CNOP    0,2
  14117.  
  14118.   ComalStruc:    DS.L    1
  14119.  
  14120.                  END
  14121.  
  14122.  
  14123.   This source  has to  be compiled and linked. Public domain assemblers and
  14124.   linkers will do the work.
  14125.  
  14126.  
  14127.                                          248
  14128.  
  14129.  
  14130.  
  14131.  
  14132.  
  14133.  
  14134.   3 Programming modules in C.
  14135.  
  14136.   It is a very simple task to write modules in C (provided you know  how to
  14137.   program in C).
  14138.  
  14139.   The interface part is written as (almost) normal Comal FUNC or PROC lines
  14140.   in a separate text file and then compiled  by the  compiler CompInterface
  14141.   (found in the ModuleDev directory on the Comal.Extras disk).
  14142.  
  14143.   The initialization routine (optional), the signal routine (optional) and all
  14144.   other routines are written as normal C procedures or functions.
  14145.  
  14146.   As an example let's make a  module containing  these three  functions and
  14147.   procedures:
  14148.  
  14149.     FUNC Even(i OF LONG) OF SHORT
  14150.     FUNC Hex$(i OF ULONG)
  14151.     PROC Capital(REF t$)
  14152.  
  14153.  
  14154.   3.1 The interface part.
  14155.  
  14156.   First let's make the interface part. The source text for the interface com-
  14157.   piler CompInterface is written in an editor. The source looks like:
  14158.  
  14159.     // Interface for Module Demo
  14160.  
  14161.       FUNC Even(i OF LONG) OF SHORT
  14162.       FUNC Hex$(i OF ULONG)
  14163.       PROC Capital(REF s$)
  14164.  
  14165.  
  14166.   Note that comments and empty lines may be used as in Comal.
  14167.  
  14168.   This source file is stored on disk as Demo.interface and then it is compiled
  14169.   by executing  the following  shell (CLI) command (provided Demo.interface
  14170.   and CompInterface are placed in the current directory)
  14171.  
  14172.       CompInterface Demo.interface
  14173.  
  14174.  
  14175.   The output from CompInterface is an assembler source  text with  the name
  14176.   Demo.interface.a. This is compiled with a normal assembler (for instance the
  14177.   SAS/C assembler) by executing the command (the include  file Comal.i must
  14178.   be in the current directory):
  14179.  
  14180.       lc:asm Demo.interface.a
  14181.  
  14182.  
  14183.  
  14184.                                          249
  14185.  
  14186.  
  14187.  
  14188.  
  14189.  
  14190.   The output from the assembler is an object file Demo.interface.o ready to
  14191.   be linked.
  14192.  
  14193.  
  14194.   3.2 The procedures and functions.
  14195.  
  14196.   The routines in a  C programmed  module are  made as  normal C procedures
  14197.   and functions.  The names  and the  types are those used in the interface
  14198.   source. You only have to know that strings (marked with a dollar sign ($)
  14199.   in the  interface source) must be changed to 'char *' and that the dollar
  14200.   sign are omitted from the name (see the function Hex$ in the example).
  14201.  
  14202.   The C source for the module we are making as an example looks like this:
  14203.  
  14204.   /* Module Demo */
  14205.  
  14206.   #include <exec/types.h>
  14207.   #include <string.h>
  14208.   #include <ctype.h>
  14209.   #include "Comal.h"
  14210.   #include "Comal_protos.h"
  14211.  
  14212.   short Even(LONG i)
  14213.   {
  14214.     return( (i+1) & 0x01 );
  14215.   }
  14216.  
  14217.   char *Hex(ULONG i)
  14218.   {
  14219.     char *String;
  14220.     
  14221.     /* Place return string in workspace    */
  14222.     String = ComalStruc->CurrWorkBottom;
  14223.     if ( ComalStruc->CurrWorkBottom+14 >= ComalStruc->CurrWorkTop )
  14224.       ErrorText("Out of memory");
  14225.     ComalStruc->CurrWorkBottom += 14;
  14226.     String[0] = '$';
  14227.     (void)stcl_h(String+1,i);
  14228.     return( String );
  14229.   }
  14230.  
  14231.   void Capital(char *Str)
  14232.   {
  14233.     while ( *Str )
  14234.     {
  14235.       if ( islower(*Str) )
  14236.         *Str = *Str - ('a'-'A');
  14237.       Str++;
  14238.     }
  14239.   }
  14240.  
  14241.                                          250
  14242.  
  14243.  
  14244.  
  14245.  
  14246.  
  14247.  
  14248.  
  14249.   This program is stored on disk  under the  name Demo.c  and then compiled
  14250.   by executing the command (SAS/C compiler)
  14251.  
  14252.     lc:LC -b0 -fi -oDemo.o Demo
  14253.  
  14254.  
  14255.   The output from the compiler is an object file ready to be linked.
  14256.  
  14257.  
  14258.   3.3 Linking the object files.
  14259.  
  14260.   The object files made by the assembler and the C compiler has to be linked
  14261.   together. This is done by the following command (again the SAS/C linker is
  14262.   used):
  14263.  
  14264.     lc:blink Demo.interface.o Demo.o TO Comal:Modules/Demo
  14265.                     LIBRARY Comal.lib lib:lcnb.lib lib:Amiga.lib
  14266.  
  14267.   (type in as one line).
  14268.  
  14269.   The output  from the linker is a module Demo placed in the directory Com-
  14270.   al:Mudules and the module can be used by placing the line
  14271.  
  14272.     USE Demo
  14273.  
  14274.   in a Comal program.
  14275.  
  14276.  
  14277.   3.4 An initialization routine.
  14278.  
  14279.   The interface compiler CompInterface makes the basic initialization code for
  14280.   you. If you need to do more initialization you have to place the following
  14281.   function in your code (NOTE! The name must be ModuleInit):
  14282.  
  14283.     short ModuleInit(void)
  14284.     {
  14285.  
  14286.         :
  14287.  
  14288.     }
  14289.  
  14290.  
  14291.   The function returns zero if the initialization succeded. Otherwise an error
  14292.   code greater than 5 is returned.
  14293.  
  14294.  
  14295.   Example: Here is a simple initialization routine:
  14296.  
  14297.  
  14298.                                          251
  14299.  
  14300.  
  14301.  
  14302.  
  14303.  
  14304.     short ModuleInit(void)
  14305.     {
  14306.       if ( !(DOSBase = OpenLibrary("dos.library",0)) )
  14307.         return(100);
  14308.       else
  14309.         return(0);
  14310.     }
  14311.  
  14312.  
  14313.   3.5 A signal routine.
  14314.  
  14315.   If you  need to  receive signals from the Comal system a signal procedure
  14316.   has to placed in your code (NOTE! The name must be signal):
  14317.  
  14318.     void signal(short s)
  14319.     {
  14320.       :
  14321.     }
  14322.  
  14323.   Example: A signal routine is very often used to close libbraries.
  14324.  
  14325.     void signal(short s)
  14326.     {
  14327.       switch(s)
  14328.       {
  14329.         case SIG_CLOSE:
  14330.         case SIG_DISCARD: 
  14331.           if( DOSBase )
  14332.           {
  14333.             CloseLibrary(DOSBase);
  14334.             DOSBase = NULL;
  14335.           }
  14336.         case SIG_CLEAR:
  14337.         case SIG_RUN:
  14338.         case SIG_STOP:
  14339.         case SIG_END:
  14340.           break;
  14341.       }
  14342.     }
  14343.  
  14344.  
  14345.   3.4 Using the script file MakeMod.
  14346.  
  14347.   All the command used to make a module is placed in a script file MakeMod
  14348.   (found in the ModuleDev directory on the Comal.Extras disk). Provided that
  14349.   both source files (Demo.interface and Demo.c) are placed in the same direc-
  14350.   tory as MakeMod and Comal.h, Comal_protos.h,  Comal.i, and  Comal.lib the
  14351.   module can be made simply by executing the command:
  14352.  
  14353.     MakeMod Demo
  14354.  
  14355.                                          252
  14356.  
  14357.  
  14358.  
  14359.  
  14360.  
  14361.  
  14362.  
  14363.   3.5 The interface compiler CompInterface.
  14364.  
  14365.   The interface compiler CompInterface takes as input a text file containing
  14366.   normal Comal procedure and function heads. The command template is:
  14367.  
  14368.     CompInterface [options] filename
  14369.  
  14370.  
  14371.   Options are specified as a hyphen followed by a single letter. Current op-
  14372.   tions are:
  14373.  
  14374.     -o  This option  is followed  by a  directory path. The output from the
  14375.         compiler is placed in that directory. Default output path is the cur-
  14376.         rent directory.
  14377.  
  14378.     -i  If this option is used, the interface source is added as the modules
  14379.         informationtext (the text you get when  selecting the  Show Modules
  14380.         menu item in the Program menu).
  14381.  
  14382.     -p  If this option is used, all functions (except string functions) can be
  14383.         used as procedures, too.
  14384.  
  14385.  
  14386.   The output from CompInterface is an assembler source text that  has to be
  14387.   compiled by a normal assembler.
  14388.  
  14389.  
  14390.   4 Calling internal Comal routines from modules.
  14391.  
  14392.   A number  of routines  in the  Comal system  may be called from a module.
  14393.   These routines are:
  14394.  
  14395.  
  14396.     void ErrorNumber(short ErrorCode);
  14397.             -6                D2
  14398.  
  14399.       Stop execution with error message. No return from the routine.
  14400.  
  14401.  
  14402.     void ErrorText(char *ErrorText);
  14403.             -12            D0
  14404.  
  14405.       Stop execution with error text. No return from the routine.
  14406.  
  14407.  
  14408.  
  14409.  
  14410.  
  14411.  
  14412.                                          253
  14413.  
  14414.  
  14415.  
  14416.  
  14417.  
  14418.     void ExecBreak(void);
  14419.             -18
  14420.  
  14421.       Call this routine if the break flag is set in the Comal structure (see
  14422.       the include files). No return from the routine unless the execution are
  14423.       continued or the break is disabled (SET ESC statement).
  14424.  
  14425.  
  14426.     struct Window *LockComalWindow(void);
  14427.             -24
  14428.  
  14429.       Get a shared lock for the standard IO  window. The  routine will open
  14430.       the standard IO window (if not already opened) and return a pointer to
  14431.       the window structure.
  14432.  
  14433.  
  14434.     void UnlockComalWindow(void);
  14435.             -30
  14436.  
  14437.       Release the lock for the standard IO window.
  14438.  
  14439.  
  14440.     void AddComalDevice(struct IoDevice *Device);
  14441.             -36                       A0
  14442.  
  14443.       Add an IO device. The parameter is a pointer to an initialized IO devi-
  14444.       ce structure. This structure will be put into the start of the list of
  14445.       standard IO devices (like "ds:").
  14446.  
  14447.     void RemComalDevice(struct IoDevice *Device);
  14448.             -42                       A0
  14449.  
  14450.       Remove an IO device from the list of IO devices.  The parameter  is a
  14451.       pointer to the IO device to be removed.
  14452.  
  14453.  
  14454.     unsigned long ComalWait(unsigned long SignalMask);
  14455.             -48                             D0
  14456.  
  14457.       Wait for the signals in the signalmask and all the Comal signals. The
  14458.       routine ORs all the Comal signals  to SignalMask  and then  calls the
  14459.       Exec routine Wait.
  14460.  
  14461.  
  14462.     void AddExcept(struct ExceptStruc *Except);
  14463.             -54                         A0
  14464.  
  14465.       Add an exception routine to the list of exception routines in the Comal
  14466.       system. The parameter is an initialized structure of the form:
  14467.  
  14468.  
  14469.                                          254
  14470.  
  14471.  
  14472.  
  14473.  
  14474.  
  14475.         struct ExceptStruc
  14476.         {
  14477.           struct ExceptStruc *Next;
  14478.           ULONG SignalMask;
  14479.           void  (*ExceptRoutine)(ULONG,struct ExceptStruc *);
  14480.           APTR  IdField;
  14481.         };
  14482.  
  14483.       The field SignalMask is a mask containing the  exception signals. Ex-
  14484.       ceptRoutine is the address of your exception routine. This routine is
  14485.       called with a mask containing the signals that caused the exception and
  14486.       a pointer to the exception structure. The field IdField is for your own
  14487.       purpose.
  14488.  
  14489.  
  14490.     void RemExcept(struct ExceptStruc *Except);
  14491.             -60                         A0
  14492.  
  14493.       Remove an exception routine from the list of exception routines in the
  14494.       Comal system. The parameter is a pointer to the exception structure to
  14495.       be removed from the exception list.
  14496.  
  14497.  
  14498.     void AddSignal(unsigned long SignalMask);
  14499.             -66                     D0
  14500.  
  14501.       Add a signal to the Comal signals.
  14502.  
  14503.  
  14504.     void RemSignal(unsigned long SignalMask);
  14505.             -72                     D0
  14506.  
  14507.       Remove a signal from the Comal signals.
  14508.  
  14509.  
  14510.     short GetAccept(char *Str, char *Accept, char *Cancel);
  14511.             -78           A0          A1            A2
  14512.  
  14513.       Set up a requester. The parameter Str is the text written in  the re-
  14514.       quester. This string may contain the C formatting character '\r'. The
  14515.       parameters Accept and Cancel are the text filled in the  positive and
  14516.       negative gadgets respectively.
  14517.  
  14518.       The routine returns TRUE if the positive gadget was pressed. Otherwise
  14519.       it returns FALSE.
  14520.  
  14521.  
  14522.   The routines are organized as an Amiga library with jump vectors at nega-
  14523.   tive offsets (the numbers shown under the names) from the Comal structure.
  14524.   From an  assembler program  it must  be called  with the  address of this
  14525.  
  14526.                                          255
  14527.  
  14528.  
  14529.  
  14530.  
  14531.  
  14532.   structure in register A6. Here is a typical calling sequence:
  14533.  
  14534.           MOVE.L  ComalStruc,A6
  14535.           JSR     -LVORemSignal(A6)
  14536.  
  14537.   All the routines uses the registers D0-D1/A0-A1. All other registers are un-
  14538.   changed.
  14539.  
  14540.  
  14541.   5 Calling comal programmed routines from a module.
  14542.  
  14543.   A Comal programmed procedure or function is called as a C procedure, i.e.
  14544.   the parameters are transfered on the stack and a return value is returned
  14545.   in register D0 (D0 and D1 if float).
  14546.  
  14547.   Example: We will make  a module  containing an  integral function  of the
  14548.     form:
  14549.  
  14550.       FUNC integral(f OF FltFnc, a, b)
  14551.  
  14552.       TYPE FltFnc=FUNC(FLOAT) OF FLOAT
  14553.  
  14554.  
  14555.     The interface looks like:
  14556.  
  14557.  
  14558.     // Interface for integral module
  14559.  
  14560.       FUNC integral(f OF FUNC OF FLOAT,a OF FLOAT,b OF FLOAT) OF FLOAT
  14561.  
  14562.  
  14563.     and the code like this:
  14564.  
  14565.  
  14566.     /* Integral module    version 92.07.29  */
  14567.  
  14568.     #include <math.h>
  14569.     #include "Comal.h"
  14570.     #include "Comal_protos.h"
  14571.  
  14572.     double integral(double (*f)(),double a, double b, struct ProcType *Inf)
  14573.     {
  14574.       double xi, s, dx;
  14575.       int n;
  14576.     
  14577.       if ( (Inf->NumPar != 1) ||
  14578.             (*((ULONG *)(Inf->Param)) != (0x0000FFFF & FLOAT_ID)) )
  14579.         ErrorText("Illegal function parameter");
  14580.  
  14581.       n = 16;
  14582.  
  14583.                                          256
  14584.  
  14585.  
  14586.  
  14587.  
  14588.  
  14589.       dx = (b-a)/n;
  14590.       xi = a;
  14591.       s = (f(a)-f(b))*dx/6.0;
  14592.       while ( (n--) > 0 )
  14593.       {
  14594.         xi = xi+dx;
  14595.         s = s+(f(xi)+2*f(xi-dx/2))*dx/3;
  14596.       }
  14597.       return(s);
  14598.     }
  14599.  
  14600.  
  14601.   One thing  has to be noted. At the call to a Comal programmed routine the
  14602.   register A4 must point to the data used by the Comal system.  At the call
  14603.   of your  own routine  the register A4 has the correct value and if you do
  14604.   not touch this register, there is no problem.
  14605.  
  14606.   But what about C compiled code? How can you be sure that  the register A4
  14607.   is not used by the code made by your compiler?
  14608.  
  14609.   As a  general answer  to that question we have to say, that you cannot be
  14610.   sure! Fortunately it seems as if SAS/C (version 5.10) do not use the regis-
  14611.   ter if it is compiled in "non base relative" mode (use the nb-libraries) and
  14612.   if you do not use the math library (the one containing the functions sin,
  14613.   cos, tan, ...). Replacement for most of the functions are placed in Comal.lib.
  14614.  
  14615.  
  14616.   6 Making a library interface.
  14617.  
  14618.   From time  to time new libraries for the Amiga appears (a lot of them are
  14619.   public domain). It is a very simple task to make an interface  for such a
  14620.   library.
  14621.  
  14622.   As an  example we  will make an interface for the ReqTools.Library (found
  14623.   on Fish disk #575).
  14624.  
  14625.   First we have to make an interface source file. This is best  done if you
  14626.   have a C proto include file for the functions in the library. Such a file is
  14627.   supplied with the ReqTools.Library. A small part of this file looks like:
  14628.  
  14629.     APTR rtAllocRequestA(ULONG, struct TagItem *);
  14630.     void rtFreeRequest(APTR);
  14631.     void rtFreeReqBuffer(APTR);
  14632.     LONG rtChangeReqAttrA(APTR, struct TagItem *);
  14633.             :
  14634.  
  14635.  
  14636.   The proto file is changed to an interface file in this way:
  14637.  
  14638.  
  14639.  
  14640.                                          257
  14641.  
  14642.  
  14643.  
  14644.  
  14645.  
  14646.   // Interface for reqtools.library
  14647.  
  14648.     FUNC rtAllocRequestA type OF ULONG, TagItem OF ULONG) OF ULONG
  14649.     PROC rtFreeRequest(req OF ULONG)
  14650.     PROC rtFreeReqBuffer(req OF ULONG)
  14651.     FUNC rtChangeReqAttrA(req OF ULONG, TagItem OF ULONG) OF LONG
  14652.             :
  14653.  
  14654.  
  14655.   Note that pointers are changed to ULONG.
  14656.  
  14657.   Now we are going to make the code.  This contains  only an initialization
  14658.   and a signal routine:
  14659.  
  14660.  
  14661.   /*********************************************************************/
  14662.   /*                                                                   */
  14663.   /*    ReqTools library - version 92.05.11                            */
  14664.   /*                                                                   */
  14665.   /*********************************************************************/
  14666.  
  14667.   #include <exec/types.h>
  14668.   #include <proto/exec.h>
  14669.   #include <pragmas/exec.h>
  14670.   #include "Comal.h"
  14671.   #include "Comal_protos.h"
  14672.  
  14673.   struct Library *ReqToolsBase = NULL;
  14674.  
  14675.   short ModuleInit(void)
  14676.   {
  14677.     if ( !(ReqToolsBase = OpenLibrary("reqtools.library",37)) )
  14678.       return(0);
  14679.     else
  14680.       return(150);
  14681.   }
  14682.  
  14683.   void signal(short s)             /* Signal routine */
  14684.   {
  14685.     switch(s)
  14686.     {
  14687.       case SIG_CLOSE:
  14688.       case SIG_DISCARD: 
  14689.         if( ReqToolsBase )
  14690.           CloseLibrary(ReqToolsBase);
  14691.     }
  14692.   }
  14693.  
  14694.  
  14695.  
  14696.  
  14697.                                          258
  14698.  
  14699.  
  14700.  
  14701.  
  14702.  
  14703.   The files are compiled as usual. To link it you have to specify the ReqTools
  14704.   linker library:
  14705.  
  14706.     blink ReqToolsLibrary.Interface.o ReqToolsLibrary.o
  14707.       TO Comal:Modules/ReqToolsLibrary
  14708.       LIBRARY Comal.lib reqtoolsnb.lib Lib:lcnb.lib Lib:Amiga.lib
  14709.  
  14710.   (NOTE! one line only).
  14711.  
  14712.  
  14713.  
  14714.  
  14715.  
  14716.  
  14717.  
  14718.  
  14719.  
  14720.  
  14721.  
  14722.  
  14723.  
  14724.  
  14725.  
  14726.  
  14727.  
  14728.  
  14729.  
  14730.  
  14731.  
  14732.  
  14733.  
  14734.  
  14735.  
  14736.  
  14737.  
  14738.  
  14739.  
  14740.  
  14741.  
  14742.  
  14743.  
  14744.  
  14745.  
  14746.  
  14747.  
  14748.  
  14749.  
  14750.  
  14751.  
  14752.  
  14753.  
  14754.                                          259
  14755.  
  14756.  
  14757.  
  14758.  
  14759.  
  14760.   X. APPENDIX
  14761.  
  14762.  
  14763.   A. Customizing the Comal text.
  14764.  
  14765.   All texts used in the Comal system are stored in two files Comal.texts and
  14766.   Comal.interpreter.texts found  in the Prefs/Texts drawer. These files are
  14767.   simple ASCII files and it is a simple matter to edit these files.
  14768.  
  14769.   The format of the files is shown in  the following  fraction of  the file
  14770.   Comal.texts:
  14771.  
  14772.   /* Other window title texts */
  14773.   #052  "Comal - project"
  14774.   #053  "Command - project"
  14775.   #054  "Error - project"
  14776.   #055  "Comal module library"
  14777.   #056  "Comal module information text"
  14778.   #057  "Comal watch window"
  14779.  
  14780.   /* About window texts */
  14781.   #058  "About Comal ..."
  14782.   #059  "Comal version 3.01"
  14783.   #060  "Total memory available:"
  14784.   #061  " bytes of memory for program text"
  14785.   #062  " bytes of workspace memory for running program"
  14786.   #063  "Comal was designed and developed by:"
  14787.   #064  "Svend Daugaard Pedersen"
  14788.  
  14789.  
  14790.   /* Menu texts  */
  14791.   #065  "Project"                         /* Menu name    */
  14792.   #066  "New"                             /* Item name    */
  14793.   #067  "N"                               /* Short cut    */
  14794.   #068  "Open..."                         /* Item name    */
  14795.   #069  "O"                               /* Short cut    */
  14796.   #070  "Save"                            /* etc.         */
  14797.   #071  "S"
  14798.   #072  "Save As..."
  14799.   #073  "A"
  14800.   #074  "Print"
  14801.   #075  "P"
  14802.   #076  "Open Command Window"
  14803.   #077  "K"
  14804.   #078  "About..."
  14805.   #079  ""
  14806.   #080  "Clear Program Buffer"
  14807.   #081  ""
  14808.   #082  "Quit Project"
  14809.   #083  "Q"
  14810.  
  14811.                                          260
  14812.  
  14813.  
  14814.  
  14815.  
  14816.  
  14817.  
  14818.   Each text is placed in one line and this line starts with the number of the
  14819.   text. The text itself is placed in double quotes and consists of ASCII cha-
  14820.   racters or the C style codes '\n' (new line), '\"' (double quote) or '\\' (for
  14821.   the character '\').
  14822.  
  14823.   All texts must be defined and  the numbers  must be  placed in increasing
  14824.   order. The first line has number zero. Empty lines and the use of C style
  14825.   comments are allowed.
  14826.  
  14827.   Note that each menu item and subitem text consist of two texts  - one for
  14828.   the text itself and one for the menu short cut. If the short cut text is the
  14829.   empty text (the text ""), no short cut will be available.
  14830.  
  14831.   Having made a new set of text files they must be stored  in the directory
  14832.   Prefs/Texts using file names of the forms:
  14833.  
  14834.     Comal.<text_id>
  14835.  
  14836.   and
  14837.  
  14838.     Comal.Interpreter.<text_id>
  14839.  
  14840.  
  14841.   Normally the <text_id> is the name of a language but it could be anything
  14842.   (but the same for both files!).
  14843.  
  14844.  
  14845.   B. The format of the AREXX macro file.
  14846.  
  14847.   At start Comal searches for a file Comal.macro containing macro definitions.
  14848.   The format of a macro file is shown in the following example:
  14849.  
  14850.   #0 SaveBlock
  14851.   #1 SaveModule
  14852.   #2 SaveModule3
  14853.   #3 StartProgram
  14854.   #4 'StartProgram Comal:Programs/Integral'
  14855.  
  14856.  
  14857.   Each macro line starts with a number sign (#), one digit (0,1,2,..,9), a blank
  14858.   (a space) and the macro string itself. If a line does not start with # it is
  14859.   treated as a comment.
  14860.  
  14861.   The line starting with #0 is attached the function key F1, the line starting
  14862.   with #1 is attached the function key F2 etc.
  14863.  
  14864.  
  14865.  
  14866.  
  14867.  
  14868.                                          261
  14869.  
  14870.  
  14871.  
  14872.  
  14873.  
  14874.   C. Customizing Comal.lib.
  14875.  
  14876.   The link library file Comal.lib found in the directory ModuleDev contains
  14877.   interfaceroutines for the Comal routines as well as initialization and termi-
  14878.   nation code for a C programmed module.
  14879.  
  14880.   The initialization and termination code is compiler dependent and the code
  14881.   found in  Comal.lib is  for use with the SAS/C compiler. In the directory
  14882.   ModuleDev you will also find a file Comal0.lib which is a library file with-
  14883.   out the initialization and termination code. This one can be used to make a
  14884.   library file for other C compilers.
  14885.  
  14886.   As part of the initialization a routine by name C_Init is called and when
  14887.   the module is removed a routine C_Term is called. These routines should do
  14888.   the initialialization and termination necessary for your C compiled code. To
  14889.   make it you should look at the source for the c.o startup code.
  14890.  
  14891.   Here is the code used for SAS/C:
  14892.  
  14893.  
  14894.   ; Module startup for SAS C v.5.xx  -  version 92.07.29
  14895.   ;
  14896.  
  14897.                  include  Comal.i
  14898.  
  14899.                  XDEF     __base
  14900.                  XDEF     _XCEXIT
  14901.                  XDEF     __xcovf
  14902.                  XDEF     _SysBase
  14903.                  XDEF     C_Init
  14904.                  XDEF     C_Term
  14905.  
  14906.                  XREF     _LinkerDB
  14907.                  XREF     ___fpinit
  14908.                  XREF     ___fpterm
  14909.                  XREF     _ComalStruc
  14910.  
  14911.   AbsExecBase    EQU       $4
  14912.  
  14913.                  SECTION  InterfaceCode,CODE
  14914.                  CNOP     0,2
  14915.  
  14916.   ; Initialization routine
  14917.   ;
  14918.   C_Init:        MOVE.L  _ComalStruc,A0       ; Get Comal structure
  14919.                  MOVE.L  CS_MinStack(A0),D0   ; Get stack bottom
  14920.                  ADD.L   #$200,D0             ; Calculate "safe" bound
  14921.                  MOVE.L  D0,__base            ; .. and store
  14922.                  MOVE.L  AbsExecBase,_SysBase ; Set Exec base
  14923.  
  14924.  
  14925.                                          262
  14926.  
  14927.  
  14928.  
  14929.  
  14930.  
  14931.                  MOVE.L  A4,-(A7)             ; Initialize floating point
  14932.                  LEA     _LinkerDB,A4
  14933.                  JSR     ___fpinit
  14934.                  MOVE.L  (A7)+,A4
  14935.  
  14936.                  CLR.W   D0                   ; Set status
  14937.                  RTS                          ; .. and return
  14938.  
  14939.   ; Termination routine
  14940.   ;
  14941.   C_Term:        MOVE.L  A4,-(A7)
  14942.                  LEA     _LinkerDB,A4
  14943.                  JSR      ___fpterm           ; Terminate floating point
  14944.                  MOVE.L  (A7)+,A4
  14945.                  RTS
  14946.                  
  14947.  
  14948.   ; Report stack overflow (only used if stack check is turned on)
  14949.   ;
  14950.   __xcovf:       MOVEQ     #5,D2
  14951.   _XCEXIT:       MOVE.L    _ComalStruc,A0    ; Get Comal library base
  14952.                  JSR       -6(A0)            ; .. and return
  14953.  
  14954.                  SECTION   InterfaceBlock,BSS
  14955.                  CNOP      0,2
  14956.  
  14957.   _SysBase:      DS.L      1                 ; Exec library base
  14958.   __base:        DS.L      1                 ; "Safe" low bound of stack
  14959.  
  14960.                  END
  14961.  
  14962.  
  14963.  
  14964.  
  14965.  
  14966.  
  14967.  
  14968.  
  14969.  
  14970.  
  14971.  
  14972.  
  14973.  
  14974.  
  14975.  
  14976.  
  14977.  
  14978.  
  14979.  
  14980.  
  14981.  
  14982.                                          263
  14983.  
  14984.