
        ##     ##   #   #        ######
         ##   ##   ##  ##        ##   ##                    ##
          ## ##   ### ###        ##   ##
           ###     ##  ## #####  #####     #####    #####  ####   ####
          ## ##    ##  ##        ##   ##       ##  ##       ##   ##  ##
         ##   ##   ##  ##        ##   ##   ######   ####    ##   ##
        ##     ##  ##  ##        ##   ##  ##   ##      ##   ##   ##  ##
        ##     ##  ##  ##        ######    ######  #####   ####   ####
 
        ###############################################################
 
 
 		    		  VERSION 1.27

 		       (C) 1997-2020 by Markus Hoffmann
 		    	 (kollo@users.sourceforge.net)
 		    (see http://x11-basic.sourceforge.net/)

			      ALL RIGHTS RESERVED
 	THIS PROGRAM IS PROVIDED "AS IS" WITHOUT A WARRANTY OF ANY KIND


             See the file `COPYING' for licensing information


       ==>							    <==

	  X11-Basic is a dialect of the BASIC programming language 
	  with graphics capability that integrates features like 
	  shell scripting, cgi-Programming and full graphical 
	  visualization into the easy to learn basic language on 
	  modern computers.

          The syntax is most similar to the old GFA-Basic  ATARI  ST
          implementation. Old GfA-programs should run with only few
          changes.
       ==>							    <==


About this document

      This document describes the features of X11-Basic. You will find
      information about the X11-Basic interpreter (the program xbasic
      under Unix or xbasic.exe under Windows) and the compiler  (the
      program xbc under UNIX or xbc.exe under Windows) as well as  the
      language itself. For a more compact description you may want to
      read the x11basic(1) man-page or the man-page of the X11-Basic
      compiler xbc(1).

      The latest information and updates and new versions of 
      X11-Basic can be found at http://x11-basic.sourceforge.net/ .




X11-BASICVERSION  1.27



            User      Manual



                       (C) 1997-2020 by Markus Hooemann


                             (kollo@users.sourceforge.net)


                      (see http://x11-basic.sourceforge.net/)

                                              Latest revision: November 18, 2020




     ______________________________________________________________________________________________________________________________*
 *___



      X11-Basic is a dialect of the BASIC programming language with graphics capa-

bility that integrates features like shell scripting, cgi-programming and full graphical

visualization into the easy to learn BASIC language on modern computers.  The

syntax is most similar to the old GFA-Basic on ATARI-ST implementation. Old GFA-

programs should run with only few changes.



      About this document



This document describes the features of X11-Basic. You will ond information about

the X11-Basic interpreter (the program xbasic under Unix or xbasic.exe under

Windows) and the compiler (the program xbc under UNIX or xbc.exe under Win-

dows) as well as the language itself. For a more compact description you may want

to read the x11basic(1) man-page or the man-page of the X11-Basic compiler

xbc(1).

      The latest information and updates and new versions of X11-Basic can be found

at

http://x11-basic.sourceforge.net/.



                                                             2




1    About X11-Basic                                                                                          1



X11-BasicContents2Usage                                                                                                           5

     2.1     Installing X11-Basic    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .      5

     2.2     Using the X11-Basic Interpreter   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    10

             2.2.1      Using the X11-Basic Interpreter under UNIX, Linux   .  .  .  .  .    10

             2.2.2      Using the WINDOWS Version of X11-Basic   .  .  .  .  .  .  .  .  .    11

             2.2.3      The Android Version of X11-Basic   .  .  .  .  .  .  .  .  .  .  .  .  .  .    13

             2.2.4      Command line parameters   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    18

     2.3     Editing X11-Basic programs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    19

     2.4     The Byte-code Compiler and the Virtual Machine   .  .  .  .  .  .  .  .  .  .    21

     2.5     Using the X11-Basic to C translator   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    24

     2.6     The X11-Basic compiler manager xbc  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    25

     2.7     The ANSI-Basic to X11-Basic converter   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    27

     2.8     Using GFA-BASIC programs  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    27



3    Programming in X11-Basic                                                                        28

     3.1     The dialect of X11-BASIC   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    28

     3.2     Getting started   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    29

     3.3     Your orst X11-Basic program  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    29

     3.4     Program structure    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    31

     3.5     General Syntax  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    31

     3.6     The very BASIC commands: PRINT, INPUT, IF and GOTO   .  .  .  .  .    33

     3.7     Variables   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    34

             3.7.1      The scope of a Variable .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    36

             3.7.2      Data types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    36

             3.7.3      Variable naming .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    37

             3.7.4      Numbers   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    38

             3.7.5      Strings    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    39

             3.7.6      Arrays  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    40

             3.7.7      Arbitrary precision numbers    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    40

     3.8     Arithmetics and Calculations  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    43

             3.8.1      Expressions and Conditions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    43

             3.8.2      Operators  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    43



                                                              i




CONTENTS____________________________________________________________________________________________________CONTENTS_______________*
 *___



              3.8.3      String processing  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    47

              3.8.4      Arrays  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    48

      3.9     Procedures and Functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    50

              3.9.1      Procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    50

              3.9.2      Functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    51

              3.9.3      Parameters and local variables  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    53

      3.10    Simple Input/Output    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    54

              3.10.1     Printing data to the console .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    55

              3.10.2     Screen control    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    56

              3.10.3     Formatting output with PRINT USING   .  .  .  .  .  .  .  .  .  .  .  .    57

              3.10.4     Gathering User Input   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    62

      3.11    Flow Control   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    63

              3.11.1     Conditional and endless loops   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    65

      3.12    Diagnostics  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    67

      3.13    Address Spaces   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    68

      3.14    Graphics: Drawing and Painting   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    68

      3.15    Reading from and Writing to Files   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    68

      3.16    Internet and bluetooth connections, special oles and sockets   .  .  .  .    69

              3.16.1     Local inter process communication: Pipes  .  .  .  .  .  .  .  .  .  .    69

              3.16.2     World-Wide communication: Sockets .  .  .  .  .  .  .  .  .  .  .  .  .    70

      3.17    Bluetooth connections   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    74

      3.18    Accessing USB devices    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    77

      3.19    Data within the program   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    78

      3.20    Dynamic-link libraries .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    79

              3.20.1     Using shared libraries and C functions  .  .  .  .  .  .  .  .  .  .  .  .    79

      3.21    Memory management   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    81

              3.21.1     Allocating memory   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    82

              3.21.2     Shared memory .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    82

      3.22    Other features    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    83



4     Graphical User Interface                                                                            84

      4.1     ALERT and FILESELECT   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    84

      4.2     Resources   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    85

              4.2.1      Objects   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    87

              4.2.2      The gui ole format .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    96

      4.3     Menus    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    98



                                                              ii




CONTENTS____________________________________________________________________________________________________CONTENTS________



5    Quick reference                                                                                       100

     5.1     Reserved variable names    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  100

     5.2     Conditions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  101

     5.3     Numbers and Constants   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  101

     5.4     Operators  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  101

     5.5     Abbreviations  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  102

     5.6     Interpreter Commands  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  102

     5.7     Flow Control Commands  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  103

     5.8     Console Input/Output Commands   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  104

     5.9     File Input/Output Commands  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  104

     5.10    Variable Manipulation Commands   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  105

     5.11    Memory Manipulation Commands   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  106

     5.12    Math commands   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  106

     5.13    Other Commands    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  107

     5.14    Graphic commands .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  108

             5.14.1     Drawing and painting  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  108

             5.14.2     Screen/Window commands .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  109

             5.14.3     GUI/User input commands   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  110

     5.15    File Input/Output functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  110

     5.16    Variable/String Manipulation functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  111

     5.17    Data compression and coding functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  112

     5.18    Memory Manipulation functions    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  113

     5.19    Logic functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  114

     5.20    Math functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  114

             5.20.1     Angles    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  116

             5.20.2     Trigonometric functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  116

             5.20.3     Random numbers .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  116

     5.21    System functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  117

     5.22    Graphic functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  117

     5.23    Other functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  118

     5.24    Subroutines and Functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  118

     5.25    Error Messages    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  119



6    Command Reference                                                                               126

     6.1     Syntax templates  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  126

     6.2     A   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  127

     6.3     B   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  156



                                                             iii




CONTENTS____________________________________________________________________________________________________CONTENTS_______________*
 *___



      6.4     C   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  175

      6.5     D   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  219

      6.6     E   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  247

      6.7     F   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  283

      6.8     G   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  316

      6.9     H   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  342

      6.10    I  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  351

      6.11    J    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  371

      6.12    K   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  374

      6.13    L   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  377

      6.14    M   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  405

      6.15    N   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  435

      6.16    O   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  445

      6.17    P   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  463

      6.18    Q   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  503

      6.19    R   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  505

      6.20    S   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  546

      6.21    T   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  612

      6.22    U   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  630

      6.23    V   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  643

      6.24    W  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  654

      6.25    X   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  665



7     Frequently asked Questions                                                                   671



8     Compatibility                                                                                            674

      8.1     General remarks   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  674

      8.2     GFA-Basic compatibility    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  677

      8.3     Ideas for future releases of X11-Basic  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  685



A     GNU License                                                                                            689



Index                                                                                                             695



                                                             iv




X11-Basic  is  a  dialect  of  the  BASIC  programming  language  with  graphics  and

sound which integrates features like traditional BASIC language syntax, structured

X11-Basic1prAboutogX11-Basicramming,  shell scripting,  cgi programming,  powerful math,  and full graphical
visualization into the easy to learn BASIC language on modern computers.


     The  syntax  of  X11-Basic  is  most  similar  to  GFA-Basic  in  its  original  ancient

implementation  for  the  ATARI  ST.  Old  GFA-programs  should  run  with  only  a  few

changes. Also DOS/QBASIC programmers will feel comfortable.


     X11-Basic is appropriate for virtually all programming tasks.  For science and

engineering X11-Basic has already proven its capability of handling complex sim-

ulation and control problems.  For system programs, X11-Basic has high level lan-

guage  replacements  for  low  level  programming  features  that  are  much  easier  to

read,  understand,  and  maintain.   For  all  applications,  X11-Basic  is  designed  to

support rapid development of compact, eOEcient, reliable, readable, portable, well

structured programs.


     X11-Basic supports complex numbers and complex math, as well as arbitrary

precision numbers and calculations where needed, as well as very fast 32bit inte-

ger and 64bit AEoating point operations, very powerful string handling functions for

character strings of any length and any content.


     X11-Basic supports the principle 'small is beautiful'. Its aim is to use the fewest

system resources and execute with the highest speed. X11-Basic meets in this, by

providing very powerful built-in commands and functions, and a very fast compiler

producing  even  faster  applications.   X11-Basic  lets  you  write  an  application  with

very little eoeort, giving you full control over your application. In case the X11-Basic

commands  and  functions  aren't  suOEcient,  you  can  easily  use  the  native  shell  to

execute  other  programs  and  commands,  or  you  will  be  able  to  use  any  shared

library on the system, which can be dynamically linked.


     Because it is an interpretive language each new step in your program can be

tested  quickly  providing  you  with  instant  feedback.   And  when  you  onished  your

program  you  can  use  the  X11-Basic  compiler  to  create  a  very  fast  stand-alone

executable.



                                                             1




     __________________________________________________________________________CHAPTER_1.__ABOUT_X11-BASIC_________________________*
 *___



Portability



The  X11-Basic  language  was  designed  to  be  platform  independant  as  much  as

possible. You can expect X11-Basic programs run on many operating systems giv-

ing nearly the same look and feel everywhere. X11-Basic programs are portable.

     X11-Basic is designed to run on many platforms with extremely low resources.

It has originally been developped for UNIX workstations and Linux-systems with the

X-Window system (commonly known as X11,  based on its current major version

being 11).

     But  soon  versions  for  other  operating  systems  (MS  WINDOWS,  MAC  OSX,

ATARI ST/TOS) have been built.  In case where no X11 window graphics system

implementation is available, X11-Basic can be compiled with a framebuoeer-device

graphics  engine.  The  Android  version  e.g.  uses  the  framebuoeer  interface.  Also

such  a  version  for  the  TomTom  navigation  devices  and  for  the  Raspberry  Pi  has

been  created.  The  SDL  (=Simple  Direct-Media  Library)  is  also  supported  as  an

alternative graphics engine.  The MS-Windows version makes use of this.  But it is

also possible to compile SDL support for other operating systems.

     Such,  Porting  X11-Basic  to  more  basic  and  embedded  systems  with  a  very

low  amount  of  RAM  and  processing  speed  is  well  possible.   It  is  even  possible

to  compile  a  version  of  X11-Basic  without  graphics  at  all.   This  way  a  very  light

script-engine, e.g. for building servers can be created.

     Sound  is  not  available  on  every  system.   Where  available,  X11-Basic  imple-

ments a 16 channel sound synthesizer as well as the option to play sound samples

from standard sound ole formats (line .wav and .ogg). On LINUX systems the ALSA

sound engine is used. The Android port of X11-Basic uses the Android sound and

speech engine.

     The  X11-Basic  environment  contains  a  library  of  GEM1  GUI2  functions.  This

makes  writing  GUI  programs  in  X11-Basic  faster,  easier  and  more  portable  than

programming with native GUI tools.

     The Android version of X11-Basic contains a full featured coloured VT100/ANSI

terminal emulation and support for unicode character sets (UTF-8 coded) for stan-

dard output.



     _______________________________________________________
    1GEM=Graphics Environment Manager, an operating environment created by Digital Research, Inc. (DRI), which

was used on the ATARI ST and GFA-BASIC.
    2GUI=Graphical User Interface



                                                             2




CHAPTER_1.__ABOUT_X11-BASIC_________________________________________________________________________________________________



Structured programming



X11-Basic is a structured procedural programming language.  Structure is a form

of  visual  and  functional  encapsulation  in  which  multiple-line  sections  of  program

look  and  act  like  single  units.   The  beginning  and  end  of  blocks  are  marked  by

descriptive keyword delimiters.

     In  contrast  to  more  traditional  BASIC  implementations,  line  numbers  are  not

used in X11-Basic.  Every line holds only one instruction.  Jumps with GOTO are

possible but not necessary.  All the well-known loops are available including addi-

tional commands for discontinuation (#  ! EXIT  IF, BREAK).

     Procedures and functions with return values of any type can be deoned.  This

way BASIC programs can be structured in a modular way.  A program can contain

a  main  part  to  call  subfunctions  and  subprocedures,  which  may  or  may  not  be

deoned in the same source ole. Distinct sources can form a library. Whole libraries

can be added with the merge command (#  ! MERGE).

     To help porting ANSI-Basic1  programs (with line numbers) to X11-Basic, a con-

verter (#  ! bas2x11basic) has been written.  It comes with the X11-Basic pack-

age.

     The  third-party  tool  gfalist2  by  Peter  Backes  even  allows  to  decode  GFA-

Basic .gfa oles to ASCII.



Optimality of code and code overhead



At a minimum the X11-Basic interpreter and the bytecode interpreter (virtual ma-

chine)  require  about  350  KB  of  memory  and  another  400  kB  of  ole  size,  which

includes the X11-Basic runtime-library.  So this is the overhead that all your pro-

grams will have.  Compared to some Windows programs, this isn't that bad.  Most

likely your bytecode is less than 50 kB anyway (for a moderate/large application),

plus any resources and graphics you may want to include of course.  In the end

the code produced will be reasonably small and light enough to be also used on

portable devices (e.g.  cell phones, e-book readers, and navigation devices) which

have only a small amount of native memory (and a relatively slow processor).



__________________________________________________
    1So-called ANSI-Basic has been standardized by the American National Standards Institute. ANSI-Basic uses

line numbers and the syntax can be quite dioeerent from X11-Basic.
    2You will ond a link to gfalist (the project name is ONS) on the X11-Basic homepage.



                                                             3




     __________________________________________________________________________CHAPTER_1.__ABOUT_X11-BASIC_________________________*
 *___



Copyright information



Copyright (C) 1997-2020 by Markus Hooemann

     Permission is granted to copy, distribute and/or modify this document under the

terms of the GNU Free Documentation License,  Version 1.2 or any later version

published by the Free Software Foundation; with no Invariant Sections, no Front-

Cover  Texts,  and  no  Back-Cover  Texts.   A  copy  of  the  license  is  included  in  the

section entitled "GNU Free Documentation License".

     X11-Basic  is  free  software;  you  can  redistribute  it  and/or  modify  it  under  the

terms of the GNU General Public License as published by the Free Software Foun-

dation; either version 2 of the License, or (at your option) any later version.

     This  program  is  distributed  in  the  hope  that  it  will  be  useful,  but  WITHOUT

ANY  WARRANTY;  without  even  the  implied  warranty  of  MERCHANTABILITY  or

FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License

for more details.

     Read the ole COPYING for details.

     (Basically  that  means,  free,  open  source,  use  and  modify  as  you  like,  don't

incorporate it into non-free software, no warranty of any sort, don't blame me if it

doesn't work.)



                                                             4




This  chapter  describes  how  to  install  X11-Basic  on  the  most  popular  operating

systems and how to run the interpreter and how to compile BASIC programs.

     The X11-Basic interpreter is called xbasic (xbasic.exe under Windows). The
X11-Basic2  Usage
compiler xbc (xbc.exe under Windows).  Under Unix these executables are usu-

ally installed in the /usr/bin/ (if installed via the package management system)

or in /usr/local/bin (if installed manually from the source package) path. Under

Windows, the oles are installed normally under the directory C:"x11basic. Under

Android you will not have to care about the individual components of X11-Basic,

because there the X11-Basic app comes with a little IDE (Integrated Development

Environment) which handles the terminal, editor, loading running and the compile

process for you.



2.1       Installing X11-Basic



For the most popular operating systems, ready-made packages are available which

allow an easy installation of X11-Basic without the need of compiling it from source

code.

     For  other  operating  systems  not  mentioned  here,  X11-Basic  may  or  may  not

work.  Generally no binary package might be available, so in these cases you will

have to compile all X11-Basic components (manually) by your own.  You may be

lucky  and  you  are  not  the  orst  trying  this,  so  searching  the  internet  for  hints  is

generally a good idea.

     But most likely you are reading this manual because you have already got X11-

Basic installed on your system, or you at least have a package ready to be installed

right away.



SuSE-Linux and RedHat


If you have got a Redhat-Package (RPM) e.g. a ole named X11Basic-1.27-1.i386.rpm,

then you can install this package (being root) with



rpm  -i  X11Basic-1.27-1.i386.rpm            .



     This is a very convenient way at least for the Linux distributions Feodora, Man-



                                                             5




2.1. _INSTALLING_X11-BASIC_____________________________________________________________________CHAPTER_2.__USAGE___________________*
 *___



driva,  SuSE  and  RedHat  (and  maybe  others,  basically  derived  distributions1 )  to

install the interpreter, the compiler, and its documentation, the man-pages and a

small collection of example programs.
      Following oles will be normally installed:

/usr/bin/xbasic                  --  the  X11-Basic  interpreter
/usr/bin/xbc                      --  the  compiler
/usr/bin/xbbc                     --  bytecode  compiler
/usr/bin/xvbm                     --  bytecode  interpreter  (virtual  machine)
/usr/bin/xb2c                     --  the  bytecode  to  C  translator
/usr/bin/bas2x11basic          --  the  ANSI  BASIC  to  X11-Basic  translator
/usr/lib/libx11basic.so       --  the  runtime  library  (shared  object)
/usr/lib/libx11basic.a         --  the  runtime  library  for  static  linking
/usr/include/x11basic/x11basic.h  --  the  header  file  for  library  API
/usr/include/x11basic/xb2csol.h   --  the  header  file  for  compilation  of  xb2c  output
/usr/share/man/man1/x11basic.1  --  the  man-page  of  X11-Basic
/usr/share/man/man1/xbasic.1    --  the  man-page  of  the  X11-Basic  interpreter
/usr/share/man/man1/xbc.1    --  the  man-page  of  the  compiler
/usr/share/man/man1/xbbc.1   --  the  man-page  of  the  bytecode  compiler
/usr/share/man/man1/xbvm.1   --  the  man-page  of  the  virtual  machine
/usr/share/man/man1/xb2c.1   --  the  man-page  of  the  X11-Basic  to  C  translator
/usr/share/man/man1/bas2x11basic.1  --  the  man-page  of  the  ANSI  to  X11-Basic   translator


      After having installed the package, you can execute the interpreter with xbasic

or read the man pages with man  xbasic or man  x11basic.
      The documentation should install into the /usr/share/doc/packages/X11Basic/
directory and you should ond the following oles:

-rw-r--r--      1005   ACKNOWLEGEMENTS         --  acknowledgments
-rw-r--r--         46   AUTHORS                    --  contact  addresses  of  the  author
-rw-r--r--    17982   COPYING                    --  copyright  information
-rw-r--r--      2960   INSTALL                    --  installation  instructions
-rw-r--r--      1752   README                     --  short  description
-rw-r--r--       170   RELEASE.NOTES           --  release  notes
-rw-r--r--   164370   X11-Basic-manual.txt  --  the  manual  (txt  version)
drwxr-xr-x      1024   editors/                  --  files  for  editors  /  syntax  highlighting
drwxr-xr-x      1024   examples/                 --  few  example  programs



Debian based distributions, Ubuntu and Knoppix


If your Linux distributions does not use the RedHat package system it is very likely

that it instead uses the Debian package system.  The most popular Debian based

Linux distributions are Knoppix and Ubuntu2 .
     _______________________________________________________
    1A list of RPM based Linux distributions can be found here:  http://en.wikipedia.org/wiki/Category:

RPM-based.Linux.distributions
    2A list of Debian based Linux distributions can be found here: http://en.wikipedia.org/wiki/Category:

Debian-based.distributions



                                                             6




CHAPTER_2.__USAGE____________________________________________________________________2.1.__INSTALLING_X11-BASIC_____________



     X11-Basic also comes in packages called (e.g.) x11basic.1.27-1.i386.deb.

Usually you can very easily install the ole from a ole browser with simply double

clicking on it. Also a



dpkg  -i  x11basic.1.27-1.i386.deb



from  a  terminal  will  do.   The  ole  system  structure  should  be  similar  to  what  is

described in the previous chapter (explaining the RedHat packages), so you should

expect  to  ond  the  same  oles  at  the  same  places.  Please  note,  that  you  need  a

special Debian package if you want to install it on 64 bit Linux installations, usually

called x11basic.1.27-1.amd64.deb.



Other Linux and UNIX distributions


The  author  currently  provides  only  32bit  and  64bit  Debian  binary  packages  for

Linux (speciocally Ubuntu Linux).  A rpm package can be made out of the Debian

packet with a tool called alien.

     For  exotic  Linux  based  devices  usually  binary  distributions  come  as  a  zip  ole

(like the TomTom version).  In these cases they are accompanied by a README

or  other  instructions  how  to  install  them.   The  package  for  Android  comes  in  a

ole  called  X11-Basic-1.27-57.apk  usually  provided  by  Google  Play  (formerly

known as Android Market), which also installs it for you.  If you do not like to use

Google Play for some reason, you can also install X11-Basic from any ole browser

taping on its .apk ole, downloaded from sourceforge.net.

     For all other systems you will have to get the source-package X11Basic-1.27.tar.gz

and compile the sources. This should work for all Linux distributions, and probably

with little modiocations also for HP-UX (Hewlett-Packard UniX), for DEC/alpha, for

MAC/OSX, for SUN/SOLARIS and FreeBSD and maybe others.  Also X11-Basic

compiles  on  Cygwin,  and  on  ARM-Linuxes  like  the  one  often  used  together  with

the Raspberry Pi. Please note that X11-Basic is designed for 32-bit operating sys-

tems.  X11-Basic will also compile on 64 bit systems.  But some of the functions

may  not  work,  especially  pointer  arithmetic  (VARPTR(),  PEEK(),  POKE,  etc.)  will

probably lead to segmentation faults when using huge amounts of memory.1  It has
__________________________________________________
    1In X11-Basic all pointers to memory addresses are stored in 32bit integer variables.  The upper 32bits of the

addresses are stored internally for further use. So if you calculate VARPTR(a), you would be able to POKE to the
address immediately after without error, because the upper part of the addresses was stored internally from the
previous call to VARPTR. X11-Basic will emit a warning, pointer base has changed, whenever this part is dioeerent
from what it was before. This way, pointer arithmetics can be used with care, even on 64 bit operating systems.



                                                             7




2.1. _INSTALLING_X11-BASIC_____________________________________________________________________CHAPTER_2.__USAGE___________________*
 *___



turned out, that also the GEM AES graphics functions make use of pointer conver-

sions (to stay compatible with the ancient ATARI ST format), also here a problem

might occur. Also the statically linked versions of X11-Basic are more likely to work

correctly,  because  the  shared  libraries  are  loaded  to  the  upper  address  space.

So  If  you  see  the  WARNING  messages,  try  to  use  a  static  version  of  X11-basic

(xbasic.static).



Compiling  X11-Basic  from  its  sources  under  UNIX  like  sys-


tems


If you have a binary package of X11-Basic, you can safely skip this section.

     In order to compile X11-Basic, you will need the following:



     #  A C compiler, preferably GNU C (but other ANSI C compilers will do),

     #  X11 libraries (for the graphics) or a framebuoeer device or the SDL library,

     #  optionally the readline library,

     #  optionally the LAPACK library,

     #  optionally the GMP library,

     #  optionally the ALSA sound library (libasound) and/or the SDL framework.



     These will suOEce to get you started.  If one or more of these libraries are not

present  on  your  system,  the  configure  and  make  scripts  will  try  to  compile  a

version, which does not need them (hence leaving out some of the functionality of

X11-Basic.).



    1.  Install the development environment packages, e.g. done by the command:


        sudo  apt-get  install  libx11-dev  libreadline6-dev  liblapack-dev  "

                                 libgmp-dev  libfftw-dev


    2.  Unpack X11Basic-1.27.tar.gz with


        tar  xzf  X11Basic-1.27.tar.gz


    3.  go into the X11Basic-1.27 directory and do a


        ./configure

        make

        sudo  make  install



                                                             8




CHAPTER_2.__USAGE____________________________________________________________________2.1.__INSTALLING_X11-BASIC_____________



That's all you will have to do (for more detailed installation instructions read the ole

INSTALL, which comes with the package.).

     If the `conogure' script fails, please contact me (kollo@users.sourceforge.

net) and send me the output it generated (config.log). I am going to try to help

you to ox the problem.



Special comments on the framebuoeer version


Very useful on the Raspberry pi and other low memory/low resources computers

is the option not to use X or SDL libraries at all.  You can have a full featured X11-

basic with graphics and mouse input anyway, if you compile the framebuoeer version

(make  fb).   This  will  produce  the  single  ole  xbasic.framebuffer  which  is  the

interpreter (and virtual machine) ready to be used from a console (and without X).

This way you have full control over the screen and mouse and keyboard.  Usually

everything you need to make the Raspberry pi interact with and display to the user.



Cross-compiling other Versions of X11Basic


The Makeole allows you to also produce the compiler (make  xbc),  the bytecode

compiler (make  xbbc), the virtual machine (make  xbvm), and the X11-Basic to C

translator (make  xb2c). If you need the separate libraries you can do a make  x11basic.a

and  a  make  libx11basic.so.   These  libraries  are  for  example  needed  by  the

compiler xbc.

     If  you  want  to  make  a  version  which  uses  the  framebuoeer  (instead  of  the  X-

Server) do a make  fb. If you want a version using the SDL library, do a make  sdl.

     The  TomTom  distribution  can  be  generated  with  make  TomTom.   (The  ARM-

Linux cross-compiler is needed).

     The  MS  WINDOWS  distribution  can  be  generated  with  make  windows.  (The

mingw cross-compiler is needed).



Support


If you have trouble with X11-Basic, you may send me a mail.  Please understand

that  I  need  to  ond  time  to  answer  your  mails.   On  http://sourceforge.net/

projects/x11-basic/ there is a forum (bug reports, patches, request for help,

feature requests) about X11-Basic. You can as well place your questions there, so

that also other users of X11-Basic have a chance to help. It is also worth browsing



                                                             9




2.2. _USING_THE_X11-BASIC_INTERPRETER__________________________________________________________CHAPTER_2.__USAGE___________________*
 *___



through the topics. Maybe someone has already found a solution to your problem.

It is as well ment for the users to share their experience with other X11-Basic users.

      If you have trouble with some X11-Basic command or program, and you think it

is a bug in the X11-Basic interpreter or compiler itself, you should create a minimum

sample program to reproduce the error; please keep this sample program as small

as possible.  Then take the program and send it to me.  Add a short description of

you problem, containing:


     #   Which operating system are you using: Windows or UNIX, Linux, Android?

     #   How does the program behave on your computer? What did you expect?

     #   Which version of X11-Basic are you using? Please try the latest one!



2.2       Using the X11-Basic Interpreter



There are several ways to start the X11-Basic interpreter depending on the oper-

ating system you are using it.



2.2.1         Using the X11-Basic Interpreter under UNIX, Linux


The simplest way is to just start it by the command xbasic from a terminal window

or a console. Then you can use the interpreter in interactive mode. Just try to enter

some X11-Basic commands. The interpreter itself also accepts several options via

the command line. Please also read the man-page (man  xbasic) for more details.

     In Ubuntu or Lubuntu you will also ond X11-Basic in the start menu.  When you

select X11-Basic from the start menu,  the interpreter should come up in its own

terminal window.



X11-Basic as a shell


X11-Basic  programs  can  be  executed  like  shell  scripts.  Make  sure  that  the  very

orst line of your X11-Basic program starts with the characters '#!' followed by the

full pathname of the X11-Basic interpreter xbasic (e.g. '#!/usr/bin/xbasic').

This  she-bang  line  ensures,  that  your  UNIX  will  invoke  xbasic  to  execute  your

program.  Moreover,  you  will  need  to  change  the  permissions  of  your  X11-Basic

program,  e.g.  chmod  755  myprog.bas.  After  that  your  program  can  simply  be

executed  from  your  shell  and  the  interpreter  works  in  the  background  like  shells

do. You need not even use the extension .bas for your scripts.



                                                             10




CHAPTER_2.__USAGE_______________________________________________2.2.__USING_THE_X11-BASIC_INTERPRETER_______________________



Example:  draftit


A tool to stamp a postscript ole with "draft" on every page.


#!/usr/bin/xbasic
i=1
WHILE  LEN(PARAM$(i))
   inputfile$=PARAM$(i)
   INC  i
WEND
CLR  flag,count
IF  NOT  EXIST(inputfile$)
   QUIT
ENDIF
OPEN  "I",#1,inputfile$
WHILE  NOT  EOF(#1)
   LINEINPUT  #1,t$
   IF  count=3
      PRINT  "%%  Created  by  draftit  X11-Basic  (c)  Markus  Hoffmann  from  "+inputfile$
   ENDIF
   IF  GLOB(t$,"%%Page:  *")  AND  NOT  GLOB(t$,"%%Page:  1  1*")
      IF  flag
         PRINT  "grestore"
      ENDIF
      flag=1
      PRINT  t$
      PRINT  "gsave"
      PRINT  ".80  setgray"
      PRINT  "/Helvetica-Bold  findfont  140  scalefont  setfont"
      PRINT  "0  80  800  --  306  exch  moveto"
      PRINT  "(Draft)  dup"
      PRINT  "stringwidth  pop  4  div  neg  0  rmoveto  6  rotate  show  "  for"
      PRINT  "grestore"
   ELSE
      PRINT  t$
   ENDIF
   INC  count
WEND
CLOSE
QUIT



2.2.2         Using the WINDOWS Version of X11-Basic


The installation is done in the usual way with a setup program, e.g. X11-Basic-1.27-57-setup.exe,

which you can download from the homepage.  All oles will be installed on the pro-



                                                             11




2.2. _USING_THE_X11-BASIC_INTERPRETER__________________________________________________________CHAPTER_2.__USAGE___________________*
 *___



gram folder on `C:`.

      In  the  case  you  have  got  a  .zip  ole,  e.g.  X11-Basic-1.27-1-win.zip,  you

should extract all oles and invoking the setup program (setup.exe).  This installs

X11-Basic into a folder C:""x11basic.  All oles you need for using X11-Basic are

located there:



    lib                      --  empty  folder  for  future  use

    bas.ico              --  the  icon  for  .bas  files

    demo.bas            --  one  of  the  example  programs

    readme.txt        --  short  description  of  X11-Basic

    SDL.dll              --  the  Simple  Direct  Media  Library

    setup.exe          --  Installation  and  uninstall  program

    x11basic.ico    --  another  X11-Basic  icon

    X11-Basic.pdf  --  The  X11-Basic  User  Manual

    xb2c.exe            --  bytecode  to  C  translator

    xbasic.exe        --  The  X11-Basic  interpreter

    xbc.exe              --  The  X11-Basic  compiler

    xbvm.exe            --  The  virtual  machine



      X11-Basic can be invoked in the following three ways:



    1.   Choose "X11-Basic" from the start-menu: You can choose between


         COMPILER            :  opens the compiler Application which then asks for a .bas ole

                to compile into .exe,

         DEMO        : Opens and runs the demo.bas example program,

         DOCU        : Opens the X11-Basic User Manual,

         X11-Basic         : Opens the X11-Basic interpreter. xbasic.exe will come up with

                a console window and the interpreter waits for commands to be typed in

                right away.


    2.   Click  with  the  right  mouse  button  on  your  desktop.  Choose  "new"  from  the

         context menu that appears; this will create a new icon on your desktop.  The

         context menu of this icon has three entries "Execute", "Edit" and "View docu"

         (which shows the embedded documentation, if any); a double-click executes

         the program.

    3.   Create  a  ole  containing  your  X11-Basic  program.  This  ole  should  have  the

         extension ".bas".  Double-click on this ole then invokes X11-Basic, to execute

         your program.



                                                             12




CHAPTER_2.__USAGE_______________________________________________2.2.__USING_THE_X11-BASIC_INTERPRETER_______________________



     The compiler has a rudimentary graphical user interface, which will ask for the

.bas ole to be compiled and later for the name of the executable to be written to.

     By default, the WINDOWS or DOS console does not support ANSI/VT100 cod-

ing.  So PRINT  AT() and line editing will probably not work.  To ox this, ANSI.SYS

has  to  be  installed  and  switched  on  for  the  console  windows.   Instructions  how

to install ANSI.SYS can be found on the Internet.  (Also an alternative extension

named ANSICON can be used.)



The Context Menu


Every icon under WINDOWS ooeers a context menu when you click on it with the

right mouse button. Clicking on an icon of a X11-Basic program as well opens this

context menu with following options:


Execute        will invoke the X11-Basic interpreter to execute your program. The same

        happens, if you double-click on the icon.

Edit    invokes notepad, allowing you to edit your program.

View docu          opens  a  window  which  shows  the  embedded  documentation  of  your

        program if there is any. Embedded documentation within a .bas ole are com-

        ments, which start with a double comment character (##).



2.2.3         The Android Version of X11-Basic


A version of X11-Basic ready to be installed on Android smart-phones and tablets

is available on the Android Market (nowadays also called Google Play).  A more

recent version usually can be found in the oles section of the project pages of X11-

Basic on sourceforge. Watch out for a ole named X11-Basic-1.27-57.apk which

contains  the  app.   Download  this  ole  to  your  Android  tablet  or  smart-phone  and

install  it,  allowing  installation  of  apps  from  other  sources  in  the  systems  settings

before if necessary.

     Unlike  the  other  versions  of  X11-Basic,  the  interpreter  and  virtual  machine  is

embedded in a little IDE (=Integrated Development Environment) which allows the

user to load, run, edit and compile the programs.

     The app registers itself as a viewer to .bas and .b oles on the system.  So from

any ole browser, basic programs can be started with a single touch.

     If you open the X11-Basic app itself,  you can directly type in commands with

the virtual keyboard.  Pressing the MENU button gives you the option to load and

run BASIC programs,  stop and continue execution,  open the keyboard (if its has



                                                             13




2.2. _USING_THE_X11-BASIC_INTERPRETER__________________________________________________________CHAPTER_2.__USAGE___________________*
 *___



vanished  from  the  screen)  and  compile  basic  programs  into  bytecode.   The  vir-

tual  machine  is  integrated,  so  bytecode  compiled  code  can  be  run.   Depending

on the endianess of the processor architecture of the platform,  bytecode may or

may not be compatible with those produced on a Linux PC or WINDOWS machine.

Standard output is rendered directly into the graphics screen with a VT100 com-

patible terminal emulation. Not all graphics features have the same result than on a

X11-Windows installation, the whole screen counts as a single full-screen window.

Finally  shortcuts  to  X11-Basic  programs  can  be  placed  on  the  desktop,  so  they

can be started with one click.  Also X11-Basic is registered as a method to open

oles (from a ole browser). A small selection of example programs is included in the

Android package. If you like to have some fun with a game, try ballerburg.bas.



Usage on Android devices


Android devices usually have a BACK button, a HOME button and a MENU button.



     #  The HOME button suspends X11-Basic and returns to the Android desktop.

        Selecting the X11-Basic app again will resume it.  If a BASIC program was

        running, it will continue to run in the background.

     #  With the BACK button, a running BASIC program will be stopped. If you press

        the BACK button again, the X11-Basic interpreter quits.

     #  The MENU button opens a menu with following options:  About,  LOAD pro-

        gram, RUN program, STOP/CONT program, NEW, Keyboard, Paste from clip-

        board, Info/Settings, Editor, Compile and Quit.


        About       shows information about the current version of X11-Basic, news and

               impressum.

        Load ...      opens a ole-selector which displays all .bas and all .b programs in

               the directory /mnt/sdcard/bas.  The selected program will be loaded

               into memory.  A program eventually stored there before will be overwrit-

               ten. You can display the source-code by entering LIST.

        Run      will simply start the execution of a program which has been loaded be-

               fore. (You can also enter RUN)

        STOP/CONT             will  interrupt  the  execution  of  the  program  or  resume  it.  (you

               can also press the BACK button once to stop the program, and you can

               enter CONT to continue it).

        New      will delete the currently loaded program from memory.

        Keyboard         will  show  or  hide  the  on-screen  virtual  keyboard.   If  you  have  a



                                                             14




CHAPTER_2.__USAGE_______________________________________________2.2.__USING_THE_X11-BASIC_INTERPRETER_______________________



               hardware or external USB/Bluetooth keyboard, you can also enter com-

               mands with that.

        Paste from Clipboard                will  paste  any  text  you  have  copied  to  the  clipboard

               (from any other application) before.

        Info/Settings         will open a dialog with additional information, links, and prefer-

               ence settings. The preferences can be set as follows:

               Show splash screen at X11-Basic start-up.                              This  can  be  switched  ooe

                     here.

               Select screen focus.               When the screen will be partially covered by the

                     on-screen  virtual  keyboard,  you  can  specify  which  portion  of  the

                     screen should be visible:  The top portion, bottom portion, the whole

                     screen but scaled to ot,  the portion with the text cursor in it,  or the

                     portion with the mouse pointer in it. The default is: scaled.

               Select font size.           If  the  screen  is  small,  but  the  resolution  is  high,  you

                     may want to change the font size to LARGE. This setting aoeects the

                     console  font  (text  mode)  as  well  as  the  graphics/user-interface  ap-

                     pearance.

        Show title        This can be switched ooe here.

        Show status bar             This can be switched ooe here.

        Show keyboard at start                 This can be switched ooe here.

        Editor     will execute a 3rd-party text editor (e.g. Ted or Jota or 920 Text Editor if

               installed) to edit the program currently loaded. If no program was loaded,

               the default ole name will be new.bas. After having saved and closed the

               text editor, the modioed program will be automatically reloaded into the

               X11-Basic interpreter.

        Compile        will compile the basic source code into bytecode which can be ex-

               ecuted about 20 times faster (but cannot be edited or merged anymore).

               The bytecode will be saved with .b extension in the bas/ folder.

        Help     will open a window in which you can search the command reference.

        Quit    will terminate the X11-Basic interpreter.



Editing a program


If  you  want  to  edit  an  existing  program,  do  following  steps  (in  this  example,  the

editor used is TED, but it works similar with Jota or many other text editors.):



    1.  Load an existing program with Menu ~? Load,



                                                             15




2.2. _USING_THE_X11-BASIC_INTERPRETER__________________________________________________________CHAPTER_2.__USAGE___________________*
 *___



    2.   choose Menu ! Editor to edit the program,

    3.   onish editing (and save it in the editor). Leave the editor by choosing EXIT in

         the menu or by using the BACK button (do not use the HOME button).

    4.   The program gets automatically reloaded,

    5.   choose menu ! run to run it.


      If you want to create a new program,  follow these steps (in this example,  the

editor used is TED):



    1.   Do a MENU -? New

    2.   Do a MENU -? Editor.  The editor will be executed with the default ole name

         (new.bas).   If  you  have  more  than  one  editors  installed,  you  will  be  asked

         which one to use. Select TED Text Editor.

    3.   Inside  the  editor  do  a  "Save  As"  and  give  it  a  dioeerent  name,  e.g.   "my-

         thing.bas", make sure that it is saved into the folder "bas".

    4.   Press the back button (not the HOME button), so the editor returns to X11-

         Basic.

    5.   X11-Basic now reloads new.bas, but this is not what you want, so

    6.   within X11-Basic load "mything.bas"



The next time you edit it, it has the correct name, and a regular save in the editor

should do as well as automatic reload in X11-Basic.

      If you get an error when calling the text editor, you need to install one.  There

are plenty around, e.g.  920 Text Editor or Ted (tiny text editor).  Install them from

the  Android  market.  You  can  install  multiple  editors.  Then  you  are  asked  which

one you like to use every time you call the editor.



LOAD ole select functions


To load a program, press menu ~? load.  You can now select a program ole (either

.bas  or  .b)  to  load.   If  you  touch  the  olename  long  you  get  another  menu  with

advanced functions:


LOAD       ~ load the program.

MERGE         ~  merge  the  program  to  the  one  already  loaded  (works  only  with  .bas

        oles).

LOAD + RUN             ~ load the program and immediately run it.

LOAD + LIST            ~ load the program an list it.



                                                             16




CHAPTER_2.__USAGE_______________________________________________2.2.__USING_THE_X11-BASIC_INTERPRETER_______________________



LOAD + edit          ~ load the program and immediately start the editor.

LOAD + compile              ~ load the program and compile it.

compile + RUN             ~  compile  the  program  and  immediately  run  the  compiled  pro-

        gram.

delete     ~ delete the selected ole (you will be asked to conorm).

CANCEL          ~ return to the ole menu.


     These  functions  are  here  for  convenience  only.    You  probably  want  to  use

LOAD+RUN or compile+RUN more often.



Running in the Background


When a program is running and you press the home button, the program will con-

tinue to run in the background.  If you select X11-Basic app again, it brings up the

screen output.

     Also:  When you rotate the screen the running program should continue to run.

It needs to ond out by using GET.GEOMETRY if the screen size has changed.



Desktop shortcuts


You  can  create  desktop  shortcuts  to  your  BASIC  programs.   You  can  place  an

application shortcut on the home screen by simply pressing anywhere (and hold

for 1 second) on the background of the desktop screen (on Android 4.x devices go

to Apps ! Widgets).  You orst are asked to place the shortcut somewhere on the

desktop. The X11-Basic launcher then asks for a .bas or .b ole and places the link

on the desktop.  Pressing this link will automatically load X11-Basic and the .bas

program and run it.

     You can select any ole from the /sdcard/bas folder which then is placed in the

desktop.



Updates of example programs


The X11-Basic app comes with a small selection of example programs.  They are

copied into the /mnt/sdcard/bas/ directory.  The X11-Basic app will never over-

write a ole in bas/ which is already there.  If you want a specioc example program

be  updated  (replaced  with  a  potentially  newer  version,  which  has  come  with  an

update  of  the  X11-Basic  app),  simply  delete  the  ole.  It  will  be  restored  after  the

next execution of X11-Basic.



                                                             17




2.2. _USING_THE_X11-BASIC_INTERPRETER__________________________________________________________CHAPTER_2.__USAGE___________________*
 *___



Troubleshooting the Android Version


SCREEN REFRESH PROBLEM:                              (Was  reported  sometimes  on  Samsung  Tabs,

        all  Android  versions)  e.g.  galaxy  note  1,  Android  4.1.2:  Symptoms:  Run-

        ning the X11-Basic app, the screen output is not updating or refreshing while

        X11-Basic runs a program. CURE: you should check the system settings:


        Developer  settings  --?    deactivate  Hardware  overlays:  ON

                                             --?    force  Gpu:  OFF


Characters typed are not visible                      If the whole line appears after you pressed EN-

        TER, but you like to see what you are typing, you need to modify the settings

        of the keyboard (switch ooe auto-completion and anything like that, which may

        make the keyboard hold text back until you press enter.)  If still nothing ap-

        pears after ENTER, then you probably have the Screen Refresh Problem (see

        above).



2.2.4         Command line parameters


If you are using X11-Basic under Android, you can skip this section. Command-line

parameters cannot be used on Android.

     The  X11-Basic  interpreter  xbasic  can  be  evoked  with  additional  but  optional

command line parameters. It takes the following ones:


  xbasic !olename?                    run Basic program [input.bas]

  -l                                  load only, don't execute

  -e !command?                        execute basic command

  --eval !expression?                 evaluate numerical expression

  --daemon                            switch ooe prompting and echoing

  -h  --help                          print a short help

  --help !topic?                      print help on a specioc topic

  --quitonend                         changes the behavior of the interpreter such that it quits

                                      after the program has onished.  The direct mode / inter-

                                      active mode will not be entered.



                                                             18




CHAPTER_2.__USAGE_______________________________________________________2.3.__EDITING_X11-BASIC_PROGRAMS____________________



Examples:


    xbasic  testme.bas

    xbasic  -l  dontrunme.bas

    xbasic  -e  'ALERT  1,"Hello  !",1,"  OK  ",b'

    xbasic  --eval  1+3-4*3



X11-Basic as daemon


The command line option --daemon forces the interpreter to run in daemon-mode

(with no terminal connected). No prompt is given and the input is not echoed back.

This is useful, if you want to run X11-Basic programs as a background service.



Additional  command  line  parameters  for  the  framebuoeer  ver-


sion


If X11-Basic was compiled to use the framebuoeer device for graphics output there

are  three  more  options  to  control  which  framebuoeer  device  is  to  be  used,  which

mouse device and which keyboard-device:


  --keyboard !device?                        set the keyboard device (default: /dev/input/event4)

  --mouse !device?                           set the mouse device (default: /dev/input/mice)

  --framebuffer !device?                     set the framebuoeer device (default: /dev/fb0)



     For example:  The sense hat for the Raspberry Pi uses the framebuoeer device

/dev/fb1  for  its  LED  matrix.   So  if  you  want  to  draw  to  the  LED  matrix  display

specify this for graphics output.



    xbasic  --framebuffer  /dev/fb1  led-blink.bas



2.3       Editing X11-Basic programs



X11-Basic programs (source code, .bas oles) are regular ASCII oles and therefore

can be created with any text editor available.

     Users  of  UNIX  like  operating  systems  are  one  with  every  text  editor.   Simple

ones like pico or nano will do.  MS-WINDOWS user can use the simple notepad

text editor.



                                                             19




2.3. _EDITING_X11-BASIC_PROGRAMS_______________________________________________________________CHAPTER_2.__USAGE___________________*
 *___



      Users of X11-Basic under Android need to install a good text editor.  TED (Text

Editor), 920  Text  Editor, or Jota will work one.  Other text editors which might

have  been  already  preinstalled  can  be  a  source  of  frustration  and  trouble.  So  if

unsure, please install one of the mentioned editors. If you have installed more than

one editor, this is no problem, you will be asked which one to use every time the

editor is invoked.

      Besides from the basic editing features I recommend to use a text editor with

syntax highlighting.  Currently X11-Basic syntax deonitions are available for nano

(available  for  the  text  consoles)  and  for  the  Nirvana  Editor  (nedit,  available  for

Linux, UNIX and WINDOWS) as well as for the 920  Text  Editor and Jota, avail-

able for Android.

      X11-Basic  can  support  foreign  language  characters.   Therefor  the  basic  pro-

gram may be coded in UTF-8 which is compatible to ASCII but has the ability to

use  and  encode  any  Unicode  character.   Such  characters  can  be  used  in  X11-

Basic string constants, but may not be used in variable names.  Currently only the

standard output (console) supports the full UTF-8 character sets.1



Using syntax highlighting with nedit



NEdit, the full featured, plain text Nirvana editor2  is a GUI style text editor for work-

stations with the X Window System.  Also a MS Windows port is available3 .  NEdit

provides  all  of  the  standard  menu,  dialog,  editing,  mouse  support,  macro  exten-

sion language,  syntax highlighting,  and a lot other nice features (and extensions

for programmers).  In short, it has everything you want to develop your X11-Basic

programs. Unfortunately nedit does not support UTF-8.

     If you like to use nedit as your favorite editor, a nedit.defs ole comes with

this  package.   This  enables  syntax  highlighting  for  X11-Basic  programs  in  nedit

(see og. 2.1).



Using syntax highlighting with nano and pico


GNU  nano  is  a  text  editor  for  Unix-like  computing  systems  or  operating  environ-

ments using a command line interface. It emulates the pico text editor, part of the
     _______________________________________________________
    1LTEXT will accept some of the special characters (currently only german), TEXT will work with UTF-8 only on

Android devices (all latin, greek, cyrillic).
    2http://nedit.org/
    3http://nedit.gmxhome.de/winport.html



                                                             20




CHAPTER_2.__USAGE___________________2.4.__THE_BYTE-CODE_COMPILER_AND_THE_VIRTUAL_MACHINE____________________________________



                                                               Figure 2.1   : The Nirvana Editor with syntax highlight-
                                                               ing for a X11-Basic program.



pine email client,  and also provides additional functionality.  Al though nano has

to be used on the console,  it can also use pointer devices,  such as a mouse,  to

activate functions that are on the shortcut bar, as well as position the cursor.  And

most important, it can handle UTF-8.

     If you like to use nano as your favorite editor, a x11basic.nanorc ole comes

with the X11-Basic package.  This enables syntax highlighting for X11-Basic pro-

grams in nano (see og. 2.2).



2.4       The Byte-code Compiler and the Virtual Machine



If you are using the Android version of X11-Basic,  you can skip this chapter.  All

you  need  to  know  is  that  there  is  the  option  to  compile  X11-Basic  programs  (to

byte-code) which makes them run much faster.

     Under UNIX, Linux and Windows a separate program need to be used to com-

pile .bas oles and make byte-code oles or standalone .exe oles out of it.

     If  you  are  using  WINDOWS,  the  most  convenient  way  to  compile  X11-Basic

programs is to execute the compiler xbc.exe which has a little use interface. Also

under UNIX/Linux it is very convenient to use the compiler manager xbc with ap-

propriate command line options (watch out for the -virtualm option).

     Advanced users probably want to deal with the byte-code oles produced in the

compiling process.  For each compilation step there are separate programs which

do it; namely: xbbc, xb2c and xbvm.



                                                             21




 2.4. _THE_BYTE-CODE_COMPILER_AND_THE_VIRTUAL_MACHINE___________________________________________CHAPTER_2.__USAGE__________________*
 *____



Figure 2.2   : The nano editor with syntax highlighting
for a X11-Basic program.



       xbbc compiles X11-Basic programs (.bas oles) to byte-code oles (.b). xb2c can

 translate byte-code oles to C source code.  xbvm is a virtual machine (interpreter

 for byte-code).

       The idea is to increase the execution speed of X11-Basic programs a lot by com-

 piling it to a byte-code, this still being portable.  The byte-code itself is interpreted

 by  a  byte-code  interpreter  (also  called  a  virtual  machine).   This  virtual  machine

 needs to be present on the target computer, and then all byte-code programs can

 be used there. This way, the X11-Basic compiler need not deal with dioeerent target

 machine  architectures,  and  also  the  byte-code  can  be  run  much  faster  than  the

 interpreted BASIC source code.

       The  conversion  to  byte-code  is  a  real  compilation.  The  step  to  assembler  or

 machine code is not far.  Also a translation to C or to JAVA or any other language

 will be straight forward.  As with JAVA, the byte-code is platform independent and

 can be run on any system, which has a virtual machine ported to.

       Also one point to mention (whether this is a feature or a disadvantage):  X11-

 Basic byte-code can not be converted back into BASIC source code (.bas), but is

 rather a very abstract representation of your program.

       If you want to get a feeling on what this is about, open a .c source ole, which

 has been produced by the byte-code to C translator xb2c.  Implemented with an



                                                              22




CHAPTER_2.__USAGE___________________2.4.__THE_BYTE-CODE_COMPILER_AND_THE_VIRTUAL_MACHINE____________________________________



additional macro translation step, the byte-code is in a way readable.  Here is an

example:



...
      PUSH2;                    /*  2   */
      ZUWEIS(2);              /*  I=  */
LBL.38:   PUSHV(2);         /*  I  */
      X2I;
      PUSHARRAYELEM(3,1);  /*  F(.)  */
      X2I;
      JUMPIFZERO  LBL.91;  /*  JEQ(0x91);  */
      PUSH2;                    /*  2  */
      PUSHV(2);                /*  I  */
      EXCH;
      X2F;
      MULf;
      PUSHV(0);                /*  S  */
      LESS;
      JUMPIFZERO  LBL.81;  /*  JEQ(0x81);  */
      PUSH2;
      PUSHV(2);                /*  I  */
      EXCH;
      X2F;
      MULf;
      ZUWEIS(5);              /*  K  */
LBL.61:   PUSHV(5);         /*  K  */
      X2I;
      PUSHVVI(3,1);          /*  F  */
      PUSHCOMM(30,1);       /*  CLR  */
      PUSHV(5);                /*  K  */
      PUSHV(2);                /*  I  */
      ADD;
      DUP;
      ZUWEIS(5);              /*  K  */
      PUSHV(0);                /*  S  */
      GREATER;
      JUMPIFZERO  LBL.61;  /*  BEQ.s(-29);  */
      PUSHCOMM(74,0);       /*  FLUSH  */
LBL.81:   PUSHX("I");
      PUSHLEER;
      PUSHCOMM(147,2);      /*  PRINT  */
      PUSHVV(4);              /*  C  */
      COMM.INC;                /*  INC  */
LBL.91:   PUSHV(2);         /*  I  */
      PUSH1;
      ADD;
      DUP;
      ZUWEIS(2);              /*  I=  */



                                                             23




2.5. _USING_THE_X11-BASIC_TO_C_TRANSLATOR______________________________________________________CHAPTER_2.__USAGE___________________*
 *___



      PUSHV(0);                /*  S  */
      GREATER;
      JUMPIFZERO  LBL.38;   /*  BEQ.s(-104);  */
...

This is bytecode made out of the (X11-Basic) lines:


...
FOR  i=2  TO  s
   IF  f(i)
      IF  2*i!s
         FOR  k=2*i  TO  s  STEP  i
           CLR  f(k)
         NEXT  k
         FLUSH
      ENDIF
      PRINT  i,
      INC  c
   ENDIF
NEXT  i
...


     You are not supposed to understand any of these, but it may give you a feeling

about  what  byte-code  really  is,  and  that  is  really  hard  to  reconstruct  the  original

BASIC lines out of it.

     Please try the byte-code compiler out and maybe you want to report errors etc.

Quite  a  lot  of  the  example  programs  are  known  to  work  well  with  the  byte-code

compiler:  e.g.  mandel-simple.bas.  The byte-code will execute about 10 times

faster than the interpreted program. Here is how to use it:



xbbc  myprogram.bas  -o  b.b

xbvm  b.b



2.5       Using the X11-Basic to C translator



It is possible to translate the byte-code generated by xbbc to C source code and

onally  compile  this  intermediate  C-source  to  a  native  executable  (e.g.   with  the

GNU C compiler gcc). This way the program will be a real native executable which

~again~ runs even a bit faster that the byte-code interpreted by the virtual machine.

     Such  programs  can  be  linked  against  the  dynamic  library  (.so  or  .dll)  or  the

static  library  (.a  or  .lib).   In  the  end  they  run  independently  of  any  interpreter  or

virtual machine.  However, some restrictions to the code apply.  Which means:  not

every program, which can be interpreted, can also be compiled.



                                                             24




CHAPTER_2.__USAGE________________________________________2.6.__THE_X11-BASIC_COMPILER_MANAGER_XBC___________________________



     The generated C-sources depend on the header ole xb2csol.h (normally in-

stalled under /usr/include/x11basic/) the x11basic.a or libx11basic.so

libraries, which therefore should be present.

     xb2c processes one input ole.  The suOEx of the input ole is usually .b (which

should be a bytecode ole produced by xbbc). The default output ole name is 11.c

but you can specify alternate names with the -o option.

     Actually xb2c is not a real compiler, but rather a translator.  The compilation is

already done by the byte-code compiler.  xb2c itself does a one to one translation

of the byte-code (currently only into C). This translation process is not yet highly

optimized,  but  quite  robust  and  portable.   There  is  no  way  to  recreate  the  .bas

source code from the .c ole.  But still the C ole is platform independent and can be

compiled on all platforms, where a C compiler is available (and the x11basic library

is ported to).

     Here is how to use it (examples are under Linux):



xbbc  myprogram.bas  -o  b.b

xbvm  b.b

xb2c  b.b  -o  11.c

gcc    11.c  -lm  -lX11  -lx11basic  -lasound  -lreadline  -lgmp  "

        -llapack  -o  a.out


     For convenience, a



xbc  -virtualm  myprogram.bas  -o  a.out


will exactly do the same.



2.6       The X11-Basic compiler manager xbc



The X11-Basic package is shipped with the X11-Basic compiler xbc, which makes

stand-alone binaries out of X11-Basic source code.  It also can produce .o object

oles, shared objects (or DLLs) and byte-code.

     There are three methods on how the compilation can be done:


1. The pseudo method:                   The source-code is bundled together with the X11-Basic

        interpreter into one executable ole, which can be run. Execution speed is not

        faster than the interpreted source code, but all programs will run and behave

        exactly the same as if they were run in the interpreter.  Currently this method



                                                             25




2.6. _THE_X11-BASIC_COMPILER_MANAGER_XBC_______________________________________________________CHAPTER_2.__USAGE___________________*
 *___



         is not available for WINDOWS since gcc is used to do the compression and

         linking  with  the  X11-Basic  runtime  library.  This  is  the  default  on  UNIX  and

         Linux operating systems.

2. The byte-code method:                    The source-code is compiled into byte-code and this

         byte-code  is  bundled  together  with  the  X11-Basic  virtual  machine  into  one

         executable ole,  which can be run.  Execution speed is much faster than the

         interpreted source code. However, some restrictions to the compiled source-

         code apply, e.g.  GOTOs across procedures are not possible, as well as ON

         ERROR and ON BREAK will currently not work.  So some obscure code will

         probably not compile correctly. However, this method is recommended as the

         preferred method and it is the default on MS WINDOWS.

3. The independent method:                       The source-code is compiled to byte-code and then

         translated to C source-code, which onally will be compiled using a C-Compiler

         (e.g.  GNU gcc) or a cross-compiler.  This is the preferred method on UNIX

         systems  (although  it  is  not  the  default)  where  a  development  environment

         (gcc  and  development  packages  for  libraries)  is  available.   On  WINDOWS

         this is usually not the case, so method 3 can not be used.  On Ubuntu Linux

         you will need to install at least following packages: gcc,  libreadline-dev,

         libasound-dev, libgmp-dev, liblapack-dev and maybe others.  If done

         so, the compiler with method 3 will work one.



      To select method 3 on UNIX/Linux systems, use the command line option -virtualm.

The windows version of the compiler will automatically use method 2 only.

      The  compiler  xbc  itself  is  written  in  X11-Basic  and  relies  on  the  presence  of

xbbc and xv2c (for methods 2 and 3). You can ond the compiler in examples/compiler/xbc.bas.

Yes, the compiler compiles itself.  Just make sure you have built the shared library

libx11basic.so and the library for static linking before



    make  lib  x11basic.a



and moved it to /usr/lib. Then do



    xbasic  xbc.bas



See the man page xbc(1) for further information on the compiler.



                                                             26




CHAPTER_2.__USAGE_____________________________________2.7.__THE_ANSI-BASIC_TO_X11-BASIC_CONVERTER___________________________



2.7       The ANSI-Basic to X11-Basic converter



X11-Basic packages come with a simple ANSI-Basic to X11-Basic converter bas2x11basic1 .

It helps converting old (real) Basic Programs with line numbers and multiple com-

mands per line to the X11-Basic structure.  Because there are so many dioeerent

BASIC versions around,  in most cases you will have to edit these oles produced

manually.  But most of the work will already have been done by this converter.  For

details on the compatibility to other dialects of BASIC, please read chapter 8.

     Example:



xbasic  bas2x11basic.bas  ansibasic.bas  -o  newname.bas


     For further options try



xbasic  bas2x11basic.bas  --help



and read the man-page man  bas2x11basic.  If you like to improve the converter

please feel free to do so. You may want to send me the result.



2.8       Using GFA-BASIC programs



GFA-Basic programs have a tokenized binary format and usually the suOEx .gfa.

This binary format has to be decoded to ASCII oles before they can be used with

X11-Basic. This job is done by the utility gfalist (sometimes also called gfa2lst

or ons-gfalist) by Peter Backes2 .

     The resulting GFA-Basic programs usually need some manual corrections. Very

simple ones may well work one with X11-Basic without. For details on the compat-

ibility, please read chapter 8.2.



__________________________________________________
    1The source-code bas2x11basic.bas of the converter can be found in the examples/compiler/ directory.
    2http://titan.plasma.xg8.de:8080/~rtc/



                                                             27




This chapter describes all you need to know to write your own programs in X11-

Basic.
X11-Basic3  Programming  in  X11-Basic



3.1       The dialect of X11-BASIC



The programming language BASIC has been around since the 1960s.  BASIC is

an  acronym  and  it  stands  for  Beginners  All  Purpose  Symbolic  Instruction  Code.

BASIC was originally designed to be a programming language that is easy to use

for a wide range of projects by anyone.  X11-Basic is a dialect of this but it is not

a  BASIC  in  its  original  form.   It  is  more  a  mix  of  classic  BASIC  with  structured

languages like PASCAL and Modula-2. The Syntax of X11-Basic is oriented to the

famous GFA-BASIC which was developed for the ATARI ST in 1985.  GFA BASIC

(as of version 3.5, the most popular one) was, by the standards of its time, a very

modern programming language. Like X11-Basic, it does without line numbers and

has a reasonable range of structured programming commands.

     X11-Basic has a lot of features which make the language dioeerent from the origi-

nal (ANSI-Basic) intention. As with GFA-Basic these modiocations help developing

programs  with  having  a  more  structured  look  and  which  make  use  of  the  more

modern graphical user interfaces available on computers since the mid 1980's:


     #  One command or declaration per line for better readability,

     #  use  of  subroutines  (procedures)  and  functions  with  local  variables  and  pa-

        rameter passing by value or by reference,

     #  data statements and arrays,

     #  powerful loop and program AEow constructs,

     #  ole and socket operations,

     #  complex number mathematics,

     #  operations for handling arbitrary/inonite precision numbers,

     #  commands to directly access the operation system shell,

     #  commands for using graphics in multiple windows,

     #  a port of the AES (the graphical user interface from the ATARI ST), allowing

        for easy use of graphics in your program,

     #  commands for direct memory manipulation, allowing you to access the com-

        puter almost as with machine language,



                                                             28




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC______________________________________________________3.2.__GETTING_STARTED_____________



     #  possibility to merge source code for libraries and reuse,

     #  inline data compression and encryption (disabled in US-versions),

     #  Unicode (UTF-8) support,

     #  support to access USB and bluetooth devices,

     #  powerful mathematics (including complex numbers, matrix/equation solving,

        big integers, and fast Fourier transformations), and

     #  a compiler is available.



Interpreter and Compiler



X11-Basic  programs  (or  scripts)  are  interpreted  by  default.   This  means  the  so-

called interpreter takes each line of your code and looks what to do with it.  The

compiler  does  it  dioeerently,  it  will  take  your  code  once,  translate  it  into  bytecode

or  machine  code  resulting  in  a  more  speedy  program  execution  as  the  step  for

command look-up does not appear anymore.  The compiled program just can be

executed out of the box. On the other hand, the advantage of an interpreter is that

you can directly test and run your program without running a compiler orst. This is

helpful while developing but of course a compiler is available as well allowing you

to produce rather fast machine code from your X11-Basic program,  once testing

has been onished.



3.2       Getting started



To write a orst X11-Basic program you will need an editor, where you can type in

the  source  code.   The  X11-Basic  package  does  not  include  an  editor,  but  many

so-called text editors are readily available nearly everywhere and by chance they

are already installed on your system.  You can use Notapad2 on MS WINDOWS

systems,  pico,  nano,  vi,  emacs,  nedit,  gedit  and  many  more  on  UNIX  and  Linux

systems,  pico on the TomTom device,  Ted or 920 text editor on Android.  This is

just a small list of possibilities here.

     Open such an editor, and you can start programming.



3.3       Your orst X11-Basic program



We  assume,  that  you  have  opened  a  console  window  (a  shell)  on  linux  or  WIN-

DOWS. The Android version is a bit dioeerent.



                                                             29




3.3. _YOUR_FIRST_X11-BASIC_PROGRAM_____________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



      Open your favorite editor and type the following line of code into the editor.



PRINT  "Hello  X11-Basic!"


     Now save the ole as "hello.bas" and run the interpreter with



xbasic  hello.bas


     X11-Basic should not complain.  If it does, check carefully for typing mistakes.

The  Program  now  should  print  out  your  hello  message  at  the  console  or  in  the

console window the interpreter was started from.  It will not return to the shell, but

just prompt for additional commands. Now type



?  quit


and you return to the shell.

     Of course you can include the quit command in your hello.bas:



PRINT  "Hello  X11-Basic!"

QUIT


Now the program always returns to the shell prompt when done.

     Now lets compile it:



xbbc  hello.bas  -o  hello.b


will produce a bytecode binary hello.b.

     You can run this:



xbvm  hello.b


will give you the same output "Hello X11-Basic!".

     Real compilation will need two more steps:



xb2c  hello.b  -o  hello.c


     produced a translated C-sourceole hello.c.

     If you have the gnu C compiler available you can compile it to an independent

executable program called hello with:



                                                             30




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC_______________________________________________3.4.__PROGRAM_STRUCTURE__________________



gcc  hello.c  -o  hello  -lm  -lX11  -lx11basic  -lasound  -lreadline


     There you go. Your program can now directly be started with



./hello



3.4       Program structure



If  you  want  to  write  more  sophisticated  programs  than  the  Hello-example,  you

should understand the general structure of a X11-Basic program.

     A  X11-Basic  program  consist  of  a  main  program  block  and  subroutines.  The

main program block is the shell of the program and is the section between the orst

line and the keyword END (or QUIT). The code in the main block drives the logic

of your program.  In a simple program this is all that is needed.  In larger and more

complex programs, putting all your code in the main block makes the program hard

to read and understand.  Subroutines let you divide your program in manageable

sections, each performing its own specioc, but limited, tasks.



3.5       General Syntax



The syntax of a typical X11-Basic line is


COMMAND  parameters


parameters  usually  consists  of  a  list  of  comma  separated  expressions.   Another

type of X11-Basic lines are variable assignments


variable=expression


variables  typically  have  a  name  and  can  have  dioeerent  types.   The  result  of  the

expression will be stored under that name for further reference.  Each line of X11-

Basic code can contain exactly one command or one assignment (or a comment).

     Here is a typical piece of X11-Basic code:



    LOCAL  l,ll,content$,g$,gg$,comp

    CLR  comp

    IF  EXIST(f$)

        OPEN  "I",#1,f$

        ll=LOF(#1)



                                                             31




3.5. _GENERAL_SYNTAX___________________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



        content$=INPUT$(#1,ll)

        CLOSE  #1

    ENDIF

    '  and  so  on



Appending lines


With many editors a limitation on the maximal line length applies (e.g. 4096 charac-

ters/line1 ). In X11-Basic a single command may in very rare cases consist of more

than 4096 characters (e.g.  by assigning an array constant to an array).  Therefor

a possibility of splitting lines into two (or more) has been implemented.  If the last

character of a line is a '"' (it must be really the last character of the line and may

not be followed by a space character!), the following line will be appended to this

line by replacing the '"' and the following newline character by spaces.

Example:



PRINT  "Hello,";  "

  "  that's  it"


will be treated as:



PRINT  "Hello,";"  that's  it"



     Please note:  The '"' character must be placed at a position within the com-

mand where a space would be allowed, too.



Comments


A  comment  can  be  inserted  into  your  program  code  with  the  REM  command  or

the abbreviation '.  Also the '#' as a orst character of the program line reserves

the  rest  of  the  line  for  a  comment.  Anything  behind  the  REM  will  be  ignored  by

X11-Basic.

     If you want to place comments at the end of a line,  they have to be prefaced

with '!'.



     _______________________________________________________
    1Note, that in X11-Basic itself there is no limitation on the line lengths.



                                                             32




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC3.6.__THE_VERY_BASIC_COMMANDS:_PRINT,_INPUT,_IF_AND_GOTO________________________________



Example:


'  This  is  a  demonstration  of  comments

DO        !  endless  loop

LOOP    !  with  nothing  inside


Note: These end of line comments can not be used after DATA (and REM).



3.6       The very BASIC commands:  PRINT, INPUT, IF and GOTO



The PRINT-command is used to put text on the text screen.  Text screen means

your  terminal  (under  UNIX)  or  the  console  window  (under  Windows).   PRINT  is

used  to  generate  basic  output,  e.g.   text,  strings,  numbers,  e.g.   the  result  of  a

calculation. Some basic formatting is possible.



Example:


PRINT  "The  result  of  1+1  is:  ";1+1


     With the INPUT command you let the user input data,  p.ex.  numbers or text.

The data can be entered on the text screen/console window. Together with PRINT

this allows already to implement a very simple user interface.



Example:


INPUT  "Please  enter  your  name:  ",name$

PRINT  "Hello  ";name$


     The  IF  command  let  the  program  do  dioeerent  things  depending  on  the  result

of a calculation.  Therefor the code is grouped into a block which should only be

executed if the result of the expression after IF is TRUE (this means, not zero). The

block starts with the IF command and ends with an ENDIF command.  If the result

of the expression after IF is not TRUE, means it is FALSE (or zero), the program

will  be  continued  after  the  ENDIF  and  the  lines  of  code  between  the  IF  and  the

ENDIF are not run.



Example:


INPUT  "Please  enter  a  number:  ";a

IF  a=13



                                                             33




3.7. _VARIABLES________________________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



    PRINT  "Oh,  you  obviously  like  the  thirteen!"

ENDIF

PRINT  "Thank  you  for  the  ";a;"."


     With GOTO you can branch to a dioeerent part of your program.  GOTO, despite

its bad reputation ([goto considered harmful]), has still its good uses. Since no line

numbers are used, you must use a label to deone lines where the GOTO command

can jump to.



Example:


again:

INPUT  "Please  enter  a  number,  but  not  the  13:  ";a

IF  a=13

    PRINT  "Oh,  you  obviously  like  the  thirteen!"

    PRINT  "But,  please  enter  a  different  number."

    GOTO  again

ENDIF

PRINT  "Thank  you  for  the  ";a;"."



     Besides these four very basic commands (which exist in every BASIC dialect)

X11-Basic has many more features which make life easier and your programs more

user friendly.



3.7       Variables



Variables in BASIC programming are analogous to variables in mathematics. Vari-

able identioers (names) consist of alphanumeric strings. These identioers are used

to refer to values in computer memory. In the X11-Basic program, a variable name

is  one  way  to  bind  a  variable  to  a  memory  location;  the  corresponding  value  is

stored  as  a  data  object  in  that  location  so  that  the  object  can  be  accessed  and

manipulated later via the variable's name.



Example:


a=1          !  Assigns  a  1  to  a  variable  named  a

b=a+1      !  The  variable  a  can  be  referred  to,  to  make  a  calculation

PRINT  "The  variable  b  contains  now  a  ";b



                                                             34




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC_________________________________________________________________3.7.__VARIABLES________



     Variable names can be very long if you like and also can contain digits and an

underscore, with the exception, that the orst letter of the variable name must not

be a digit.



Example:


my.very.long.variable.name=1.23456

PRINT  my.very.long.variable.name



     You can refer to a variable by giving its name in the place you want the value of

the variable to be used. X11-Basic will automatically know where to store the data

and how to deal with it.

     It is also important to tell X11-Basic what sort of data you want to store. You can

have variables that store only numbers but also variables that deal with a character

or a whole string, a line of text for example.  The following line of X11-Basic code

will create a variable called age for you and assign it the value of 18.



age=18



But if you want to store a text, the variable needs to be capable to hold characters

instead of numbers.  Therefore, in that case you mark the variable with a $ to tell

that it should store text, not numbers:



name$="Robert"



Text constants, by the way, need to be enclosed with "", to tell X11-Basic that the

text should not be interpreted as program code, but just be treated as any text.

     The assignment is done with the '=' operator.  The '=' operator is also used in

expressions, e.g.  after an IF command.  But there it is not used as an assignment

operator but instead there it is treated as a comparison operator. In X11-Basic both

operators are '='. The interpreter distinguishes between them just by context.



Example:


x=(a=3)



Here  the  orst  =  is  an  assignment  and  the  second  is  the  comparison  operator.  x

will  be  assigned  a  -1  (TRUE)  if  a  is  3  and  a  0  (FALSE)  else.   The  brackets  are



                                                             35




3.7. _VARIABLES________________________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



not necessary here they just help reading this expression.  Confused?  Well, you

eventually will get used to it.

      Last to say, such an assignment will overwrite any old data that has been stored

before in that variable. As long as you don't assign a value to a variable, it will hold

a default value, 0 in most cases.



3.7.1         The scope of a Variable


X11-Basic uses two scopes for variables: global (which is the default) and local.

     Global variables can be modioed from anywhere within the program,  and any

part of the program may depend on it.  Unless otherwise declared with LOCAL, all

X11-Basic variables are global by default and this need not be explicitly declared.

     But there is one downside of global variables: The use of global variables makes

software harder to read and understand. Since any code anywhere in the program

can  change  the  value  of  the  variable  at  any  time,  understanding  the  use  of  the

variable may entail understanding a large portion of the program. They can lead to

problems of naming because a global variable makes a name dangerous to use for

any other local scope variable.  Also recursive programming is nearly impossible

with only global variables, last but not least, the usage of procedures and functions

becomes  much  more  clear,  if  you  are  able  to  encapsulate  all  internal  variables

of that function and you do not bother outside of the functions scope if you acci-

dentally use one of these internal variables somewhere else in the code, possibly

altering the functions behavior.

     Because  of  all  this,  X11-Basic  also  provides  local  variables,  which  live  only

within a certain function or procedure and their context.

     Local variables need to be declared with the command LOCAL inside the func-

tion od procedure where they belong to. Outside this specioc procedure or function

they simply do not exist, or if a global variable of the same name exists, they refer

to dioeerent contents.



3.7.2         Data types


Now,  lets  come  back  to  the  type  of  a  variable.   How  can  one  see  what  kind  of

content a variable can store?  How does X11-Basic know?  By the way the name

of  the  variable  has  been  written.   To  distinguish  between  dioeerent  ways  of  data

types X11-Basic appends a special typing sign as a suOEx to the variable name to

distinguish between several ways to store data in variables.



                                                             36




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC_________________________________________________________________3.7.__VARIABLES________



     The  X11-Basic  interpreter  uses  64-bit  AEoating  point  variables,  32-bit  integer

variables,  character  strings  and  arrays  of  these  variables  of  arbitrary  dimension.

A declaration of the variables and of their type is not necessary (except for arrays

! DIM), because the interpreter recognizes the type of the variable from the suOEx:

32bit integer variables have the suOEx %, arbitrary precision integer variables have

a &, complex variables a #, character strings a $, arrays a (). Variables without suf-

ox are treated as real 64bit AEoating point variables.  Pointers are integers, function

calls are marked by @. Logical expressions are also of type integer. It is important

that variables with a special suOEx are dioeerent from those (even if the rest of the

name is identical) without.



Examples:


x=10.3                !  this  is  a  number  variable  (64bit  floating  point)

x$="Hello"        !  this  is  a  different  character  string  variable

x%=5                    !  this  is  a  (32bit)  integer  variable,  different

x&=79523612688076834923316  !  this  is  a  big  integer  variable,

                                                     !  still  different

x#=3+4i              !  this  is  a  complex  number  variable,

@x                        !  this  refers  to  a  function  or  procedure  x

x()=[1,2,3,4]  !  this  beast  refers  to  an  array.



3.7.3         Variable naming


You  can  use  all  letters  and  numbers  for  your  variable  names.   Spaces  are  not

allowed  but  underscores  inside  the  variable  name.   The  variable  name  can  be

of  any  length.   X11-Basic  limits  you  only  in  the  following  ways:  a  variable  may

not begin with a number or an underscore, only with letters.  Avoid to name your

variables  like  X11-Basic  commands.  It  will  work  but  it  can  cause  troubles.  As  a

rule, never try to assign values to X11-Basic system variables (like TRUE, FALSE,

TIMER, PC, TERMINALNAME$).  The values indeed will be assigned, but you never

can use the assigned values, since always the internal values will be used.

     Valid variable names look like the following:


x,  auto%,  lives%,  bonus1%,  x.1,  city.name$,  debit,  z#      .


     Invalid variable names look like this and X11-Basic will complain:


.blank,  1x,  ?value%,  5s$,  1i,  #u.



                                                             37




3.7. _VARIABLES________________________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



Always remember:  begin your variable names with a letter from A-Z and you are

on the safe side!

      Variable names and commands are case insensitive.  Each name is bound to

only  one  kind  of  variable;  A$  is  a  whole  dioeerent  variable(value)  than  A  which  is

dioeerent from A% or A$(1,1).

      Space between commands will be ignored,  but note that no space is allowed

between the name of a variable or command and the '(' of its parameter list.  So,

ASC("A") is good, ASC(          "A"          ) also, but ASC  ("A") isn't.



Examples:



integer variables:           i%=25

                                     my.adr%=VARPTR(b$)

                                     b%=MALLOC(100000)

big integer variables:     i&=79523612688076834923316

                                     a&=FACT(100)

AEoat variables:               a=1.2443e17

                                     b=@f(x)

complex variables:         a#=1.2443e17+1.2i

                                     b#=CONJ(a#)

character strings:           t$="Hello  everybody  !"

oelds and arrays:           i%(),a(),t$(),  [1,3,5;7,6,2]



3.7.4         Numbers


X11-Basic normally uses integer numbers (32 Bit) which range from -2147483648

to  2147483647,  and  AEoating  point  numbers,  which  are  64Bit  IEEE  754  standard

values.   These  64bit  AEoating  point  numbers  have  a  mantissa  of  of  52  bits  and

an  exponent  of  11  bits  and  a  sign  bit.   These  numbers  can  represent  15  to  16

signiocant digits and powers of 1e-308 to 1e308. Complex numbers consist of two

64bit AEoating point values.

     X11-Basic  currently  also  support  inonite  precision  integer  numbers.   These

numbers are stored in a variable size portion of memory, so that an arbitrary num-

ber of digits can be stored. However, calculation with big interges is slow and only

a few built-in functions can be used on them.



                                                             38




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC_________________________________________________________________3.7.__VARIABLES________



     Number  (constants)  can  be  preceded  by  a  sign,  +  or  -,  and  are  written  as  a

string of numeric digits with or without a decimal point and can also have a positive

or negative exponent as a power of 10 multiplier e.g.



  -253    67.3    0.25    -127.42E-3    -1.3E7    1



     The imaginary part of complex number constants are market with a trailling "i",

e.g.



  -2i    1i    0.25+3i          -127.42E-3i



Note:  A single "i" is always treated as a real variable name.  If you want the imagi-

nary unit, please always use "1i".

     Integer  numbers,  with  no  decimal  fraction  or  exponent,  can  also  be  in  either

hexadecimal  or  binary.   Hexadecimal  numbers  should  be  preceded  by  $  (or  0x)

and binary numbers preceded by %, e.g.



%101010          -$FFE0        0xA0127BD          -%10001001          %00011010



3.7.5         Strings


String  variables  can  contain  sequences  of  characters  (bytes)  of  arbitrary  length.

There is no length limit for a string other than the virtual memory of the machine.

Strings generally contain ASCII text, but can hold arbitrary byte sequences, even

characters that have the ASCII code zero.  In other words a string is a collection

of bytes of certain length.  You can treat strings as arbitrary length of binary data

if you need.  Strings are automatically elastic,  meaning they automatically resize

to contain whatever number of bytes are put into them.  When a string resizes, its

location in memory may change, as when a longer string is assigned and there is

insuOEcient room after the string to store the extra bytes.

     String variables are distinguished by the $ suOEx.

     String constants are enclosed with pairs of "" (double quote).

     A wealth of intrinsics and functions are provided to support eOEcient string pro-

cessing and manipulating.

     There is a way to include special characters into string constants.  The usual

way in BASIC is to split the string into sub strings and concatenate the parts during

run time, like in the code fragment:



                                                             39




3.7. _VARIABLES________________________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



Example:


st$="This  is  a  special  string,  containing  a  bell  character  at  the  end"+CHR$(7)



     By the way, the double quote character can be added with CHR$(34).



3.7.6         Arrays


Arrays are memory locations that store many values of the same type at the same

time.  While normal variables store a single value at a time, an array variable can

store many values.  The values are accessed via the name of the variable and the

appropriate indexes. The index or indexes follow the name of the variable between

( and ).

     There  is  no  limit  on  the  number  of  indexes  (the  dimension).  You  can  use  as

many as you like.  Also there is no limit on the index values other than the index

values have to be positive integer and that memory may limit the array sizes.

     X11-Basic arrays can contain variables of any data type, including strings.  All

arrays, even multi-dimensional arrays, can be re-dimensioned without altering the

contents.   A  special  feature  of  X11-Basic  is  the  implicit  dimensioning  of  arrays

and the existence of array constants.  You may deone an array by using the DIM

command. You might also deone the array by an assignment like



DIM  b(10)

a()=b()



if b() already has been DIMed or by



a()=[1,2,3,4;6,7,8,9]



assigning an array constant. (In this example a 2 dimensional array will be created

and the rows are separated by ';'.)



3.7.7         Arbitrary precision numbers


X11-Basic also support inonite or arbitrary precision numbers with a sprecial data

type.  Arbitrary-precision arithmetic, also called bignum arithmetic, multiple preci-

sion  arithmetic,  or  sometimes  inonite-precision  arithmetic,  indicates  that  calcula-

tions are performed on numbers whose digits of precision are limited only by the



                                                             40




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC_________________________________________________________________3.7.__VARIABLES________



available  memory  of  the  computer.  This  contrasts  with  the  faster  oxed-precision

arithmetic, normally used.

     Inonite precision math is slow,  and not all functions are available for this data

type.  Arbitrary precision is used in applications where the speed of arithmetic is

not a limiting factor, or where precise results with very large numbers are required.

     The data type with the suOEx & supports (big) integers only.  It is up to the user

(and  straight  forward)  to  write  routines  for  handling  rational  numbers  (using  two

big interges, numerator and denominator), and corresponding routines for adding,

subtracting, multiplication and division of thouse fractions.  Multiple precision Irra-

tional numbers using a AEoiting point representation are (currently) not supported.

If somebody needs this, please let me know.

     Supported operators (for big integers) are + - * / = !? ! ? MOD and DIV. Sup-

ported functions are ABS(), SQRT(), NEXTPRIME(), FACT(), PRIMORIAL(), FIB(),

LUCNUM(), RANDOM(), ADD(), SUB(), MUL(), DIV(), MOD(), POWM(), ROOT(),

GDC(),  LCM(),  INVERT(),  MIN(),  MAX()  and  many  more.   Also  STR$(),  BIN$(),

OCT$() and HEX$() work with big integers.

     The  advantage  is,  that  you  can  handle  big  integer  numbers  without  loosing

precision, as it is useful for cryptography and number theory.

     Also  rounding  errors  can  be  avoided  by  using  inonite-precision  rational  num-

ber arithmetic (which is not implemented by X11-Basic itself,  but which could be

realized using pairs of big integers.)

     Variables of either type may be used and mixed in expressions.  They will be

converted to big integer or from big integer to AEoat or 32bit integers when needed.

One should j ust be aware of the eventual loss of precision.

     Here is an example how to use big number arithmetrics in X11-Basic to factorize

a big number into its prime factors:



Example:


'  Factorize  (big)  Integer  numers  into  prime  factors.

'  with  X11-Basic    ?=  V.1.23

'

DIM  smallprimes&(1000000)

CLR  anzprimes

smallprimes&(0)=2

INC  anzprimes



                                                             41




3.7. _VARIABLES________________________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



INPUT  "Enter  a  (big)  number:  ",a&

PRINT  "Calculating  primes  up  to  ";lim&;".  Please  wait..."

lim&=SQRT(a&)      !  Limit  up  to  which  the  primes  are  searchd

FOR  i=1  TO  DIM?(smallprimes&())-1

    b&=NEXTPRIME(smallprimes&(i-1))

    EXIT  IF  b&?lim&

    smallprimes&(i)=b&

NEXT  i

anzprimes=i

PRINT  "calculated  ";anzprimes;"  primes  up  to:  ";b&



PRINT  "Factorization:"

PRINT  a&;"=";

FOR  i=0  TO  anzprimes-1

    WHILE  (a&  MOD  smallprimes&(i))=0

        PRINT  smallprimes&(i);"*";

        FLUSH

        a&=(a&  DIV  smallprimes&(i))

        lim&=SQRT(a&)

    WEND

    EXIT  IF  smallprimes&(i)?lim&

NEXT  i

IF  nextprime(a&-1)=a&  or  a&=1

    PRINT  a&

ELSE

    '  The  number  is  too  big  and  we  cannot  be  sure

    '  that  this  is  a  prime

    PRINT  "----incomplete  test  -----";a&

ENDIF

END



     Note  that  the  list  of  small  primes  could  also  be  generated  by  a  sieve.   The

method used is based on prime number tests (using the function NEXTPRIME())

and may be not optimal.



                                                             42




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC_______________________________3.8.__ARITHMETICS_AND_CALCULATIONS_______________________



3.8       Arithmetics and Calculations



X11-Basic handles numbers and arithmetic: You may calculate trigonometric func-

tions  like  SIN()  or  ATAN(),  or  logarithms  (with  LOG()).  Bitwise  operations,  like

AND  or  OR  are  available  as  well  as  MIN()  and  MAX()  (calculate  the  minimum  or

maximum of its argument) or MOD or INT() (reminder of a division or integer part

or a number). Many other statements give a complete set of math functions.

     Most of these functions can work on dioeerent input data types. E.g. you can use

the SQRT() function also on complex numbers, thus returning a complex result.



3.8.1         Expressions and Conditions


No dioeerence makes the dioeerence.



Expressions           are needed to calculate values. The simplest expression is a numer-

        ical  or  string  constant.   More  complex  expressions  may  contain  constants,

        variables,  operators,  function  calls  and  possibly  parentheses.   The  expres-

        sion  format  used  by  X11-Basic  is  identical  with  that  of  many  other  BASIC

        packages:  The operators have precedence of the usual order and you can

        alter the order of operator evaluation using parentheses. Here is an example

        numeric expression following after a PRINT statement:



        PRINT  (x-1)*10+SIN(x)



Conditions          and expressions are treated the same in X11-Basic.  Because X11-

        BASIC doesn't have separate Boolean operators for conditions and expres-

        sions, the operators (AND, OR, XOR, NOT) actually operate on binary values.

        Therefore a TRUE is -1, which means, that every bit is one. So the operators

        will operate on each of these bits.  Such:  a condition is considered TRUE if

        the  expression  is  not  FALSE  (means  the  result  must  be  a  value  other  than

        zero).



3.8.2         Operators


X11-Basic provides operators for numerical expressions, character strings and ar-

rays of either type and any dimension.



                                                             43




3.8. _ARITHMETICS_AND_CALCULATIONS_____________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



Numerical Operators


Numerical operators are roughly categorized in following categories:


     #  arithmetical operators: ^  *  /  +  -

     #  comparison operators: =  !?  !  ?  !=  ?=

     #  logical operators: NOT  AND  OR  XOR  ...


     X11-Basic  recognizes  the  following  operators,  in  order  of  falling  precedence

(the precedence of BASIC operators aoeects the order of expression evaluation):


                       ________________________________________________________________________________
                       |  Order  |   Operator  |       Description                            |
                       |_________|_____________|______________________________________________|________
                       |         1  |(  )           |  parenthetical expression          |
                       |            |               |                                    |
                       |         2  |#             |   sign (negation)                        |
                       |            |              |                                          |
                       |         2  |+             |   sign                                        |
                       |            |              |                                               |
                       |         3  |^              |  exponent/power                       |
                       |            |               |                                       |
                       |         3  |=              |  divide                                      |
                       |            |               |                                              |
                       |         3  |*               | multiply                                   |
                       |            |                |                                            |
                       |         4  |+              |  add                                         |
                       |            |               |                                              |
                       |         4  |-               | subtract                                   |
                       |            |                |                                            |
                       |         5  |!!          |     bitwise shift to the left (*)         |
                       |            |            |                                           |
                       |         5  |??          |     bitwise shift to the right (*)       |
                       |            |            |                                          |
                       |         6  |=              |  logical "equals"                        |
                       |            |               |                                          |
                       |         6  |!?            |   logical "not equal"                    |
                       |            |              |                                          |
                       |         6  |!              |  logical "less than"                    |
                       |            |               |                                         |
                       |         6  |?              |  logical "greater than"               |
                       |            |               |                                       |
                       |         6  |!=            |   logical "less than or equal"       |
                       |            |              |                                      |
                       |         6  |?=            |   logical "greater than or equal"  |
                       |            |              |                                    |
                       |         7  |NOT         |     bitwise not                               |
                       |            |            |                                               |
                       |         8  |DIV           |   integer division                        |
                       |            |              |                                           |
                       |         9  |MOD        |      modulus (rest of division)         |
                       |            |           |                                         |
                       |       10  | IMP          |    implies                                    |
                       |           |              |                                               |
                       |       10  | EQV         |     equivalence                             |
                       |           |             |                                             |
                       |       10  | XOR         |     bitwise exclusive or                 |
                       |           |             |                                          |
                       |       10  | NOR         |     bitwise not or                           |
                       |           |             |                                              |
                       |       10  | NAND       |      bitwise not and                        |
                       |           |            |                                             |
                       |       10  | AND         |     bitwise and                              |
                       |           |             |                                              |
                       |       10  | OR           |    bitwise or                                |
                       |           |              |                                              |


                                                             44




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC_______________________________3.8.__ARITHMETICS_AND_CALCULATIONS_______________________



                      |       11  |  =              |  assignment                             |
                      |           |                 |                                         |
                      |       12  |  ,               | comma                                    |
                      |___________|__________________|__________________________________________|_____



(*) = not implemented



Addition and subtraction operators                         are  both  binary  and  unary  operators.   In

        their  unary  form  they  are  used  out  of  the  precedence  orders.   Unary  oper-

        ators are always applied orst,  unless parentheses drive dioeerent calculation

        order.

The power operator                a^b  calculates  the  b-th  power  of  a.  The  actual  implemen-

        tation of the power operator always uses the pow() function,  which always

        treats all operants as real numbers.  Under some circumstances it might be

        more optimal to use a*a instead of a^2.

The multiplication operator                   multiplies the operands. If any of the operands is an

        array then the result will be an array.

The division operator               divides  the  orst  operand  with  the  second.   If  the  second

        operand is zero then an error will occur.

The integer division operator                    divides the orst operand with the second. The cal-

        culation  is  performed  using  integer  numbers  and  the  result  is  truncated  to-

        wards zero.

Bit-wise and logical NOT                  This unary operator calculates the logical negate (the

        complement)  of  the  operand.   The  calculation  is  done  on  integer  numbers,

        thus the operand is converted to an integer value.  The operator inverts each

        bit of the operand.

Logical operators (AND, OR, XOR)                         These operators can be used for both logical

        and bit-wise operations.  X11-Basic does not have a separate type for logical

        values.  The logical TRUE is represented as integer value -1 (all bits set to

        1)  and  the  logical  FALSE  is  0.   The  operators  AND,  OR  and  XOR  perform

        the  calculation  on  integer  values.  If  any  of  the  operands  is  not  integer  it  is

        converted to integer value before the operation takes place.  The operations

        are performed on each bit of the operands.



Operators for Character Strings


There are a few operations which can directly be done to character strings or string

variables, using operators.



                                                             45




3.8. _ARITHMETICS_AND_CALCULATIONS_____________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



plus operator, conjunction                    The plus '+' operator used on strings, links two strings

         together.



        Example:


          a$="X11"

          b$="-"

          c$="BASIC"

          d$=a$+b$+c$



        results in a string "X11-BASIC".

comparison operators, !, !=, =, =?, ?, !?                          comparison functions belong to numer-

        ical (Boolean) functions because the result is a number, although they can be

        used with strings.



        Example:


          IF  a$="X11"

              ...

          ENDIF

          result=(a$!?"Hello")



code evaluation operator, &                    the eval operator evaluates command or expression

        which is given by the String. Example see below.



Rules for comparison of strings:



    1.  Two  strings  are  equal  if  all  the  characters  inside  are  identical  (also  spaces

        and punctuation marks).

        Example:

        "  123  v  fdh.-,"  =  "  123  v  fdh.-,"

    2.  The comparison of strings with the greater and smaller operator works char-

        acter by character until one of them is smaller or one of the strings ends orst,

        this is the smaller one.

        Examples:



                                                             46




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC_______________________________3.8.__ARITHMETICS_AND_CALCULATIONS_______________________



        "X11"?"X11"          result:    0

        "X11"!"x11"          result:  -1

        "123"!"abc"          result:  -1

        "123"?"1234"        result:    0



The Evaluation Operator &:   The &-operator followed by a string evaluates it for pro-

gram code.



Example:


REM  generate  ten  times  the  command  'print  a$'

CLR  i

a$="print  a$"

label1:

INC  i

IF  i?10

    b$="label2"

ELSE

    b$="label1"

ENDIF

&a$

GOTO  &b$

label2:

END


To program like this can produce a really unreadable code.



3.8.3         String processing


X11-Basic has the usual functions to extract parts from a string: LEFT$(), MID$()

and RIGHT$().

     If you want to split a string into tokens you should use the command SPLIT or

the function WORD$() .

     There is quite a bunch of other string-processing functions like UPPER$() (con-

verting to upper case), INSTR() (onding one string within the other), CHR$() (con-

verting an ASCII-code into a character), GLOB() (testing a string against a pattern)

and more.



                                                             47




3.8. _ARITHMETICS_AND_CALCULATIONS_____________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



3.8.4         Arrays


Arrays  are  special  variables  which  consist  of  many  values  (of  the  same  type).

There can be AEoating point arrays, integer arrays, string arrays, and arrays of ar-

rays. The memory for an array need to be declared before it can be used. This can

be done with the DIM statement or by direcly assigning a value to the array.



Array constants


The common way to assign data to a whole array is to put the input ogures into list

into square brackets (which forms an array constant) and assign this to an array

variable like:



a()=[1,2,3;4,5,6]



A comma is used to separate columns elements, and semicolon is used to sepa-

rate rows. So [1, 2, 3] is a row vector, and [1; 2; 3] is a column vector.

     Now that you know how to deone a simple array, you should know how to access

its elements. Accessing the content of an array is done through the operator (), with

the index inside the parenthesis; the indexing of the orst element is 0:



b=a(0)

a(1)=5



     Accessing  an  element  outside  the  bounds  will  result  in  an  error:  "Field  index

too large."

     To access a single matrix element, you can use the (i,j) subscript, where i is the

index in the row, and j in the column:



b=a(1,2)

a(3,4)=3



     It is also possible to access blocks of matrices using the colon (:) operator. This

operator is like a wildcard; it tells X11-Basic that you want all elements of a given

dimension or with indexes between two given values.  For example, say you want

to access the entire orst row of matrix a above, but not the second row.  Then you

can write:



                                                             48




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC_______________________________3.8.__ARITHMETICS_AND_CALCULATIONS_______________________



b()=a(1,:)



     Now say you only want the orst two elements in the orst row. To do this, use the

following syntax:



b()=a(1,1:2)



     It is also possible to use arrays of any higher dimension.



DIM  a(10,10,10,10,10)

b=a(2,5,4,2,7)



Array operators


Arrays are not only good for storing information in tables, but one can apply opera-

tions on arrays.  You can for example use the classic arithmetic operations + and -

on any array in X11-Basic: this results in the vector addition and subtraction as de-

oned in classic vector vectors spaces, which is simply the addition and subtraction

elements wise.


            _____________________________________________________________________________________________________
            |  Array Operator  |          Description                                                   |
            |__________________|________________________________________________________________________|________
            |             +             | Vector/Matrix addition element by element       |
            |                           |                                                 |
            |             -             | Vector/Matrix subtraction element by element  |
            |                           |                                               |
            |             *             | Array/Matrix multiplication                               |
            |                           |                                                           |
            |              :              |Subarray (a block)                                           |
            |                             |                                                             |
            |           =,!?           |  comparison element by element                      |
            |                          |                                                     |
            |       !,?,!=,?=       |     comparison using a norm                                |
            |_______________________|____________________________________________________________|_______________



     Array  functions  and  operators  act  on  entire  arrays.  Some  return  a  list,  which

can then either be used as a value for another array function, or assigned into an

array variable.

     Array comparisons compare the array contents element-by-element, using the

default  comparison  function  for  the  element  data  type  (=,?,!).    In  multidimen-

sional arrays the elements are visited in row-major order (last subscript varies most



                                                             49




3.9. _PROCEDURES_AND_FUNCTIONS_________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



rapidly).  If the contents of two arrays are equal but the dimensionality is dioeerent,

the orst dioeerence in the dimensionality information determines the sort order.



3.9       Procedures and Functions



In X11-Basic there are two types of subroutines:  procedures and functions.  The

main dioeerence between the two is that a function returns a single value and can

be used in expressions, while a procedure never returns a value.  A procedure or

function must appear after the main program block.  Therefore, the structure of an

X11-Basic program is as follows:



Main  program  block

END

Procedures  and  Functions



Procedures           are blocks of code that can be called from elsewhere in a program.

        These subroutines can take arguments but return no results.  They can ac-

        cess all variables available but also may have local variables (~? LOCAL).

Functions         are blocks of code that can be called from elsewhere within an expres-

        sion (e.g a=3*@myfunction(b)). Variables are global unless declared local.

        For local variables changes outside a function have no eoeect within the func-

        tion  except  as  explicitly  specioed  within  the  function.   Functions  arguments

        can be variables and arrays of any data types. Functions can return variables

        of any data type. By default, arguments are passed by value.



3.9.1         Procedures


A procedure starts with the keyword PROCEDURE followed by the procedure name

and the parameters being passed to the procedure.  All procedures must end with

the keyword RETURN. Procedures use the following format:



PROCEDURE  ProcName(parameters)

    LOCAL  vars

    procedure  logic

RETURN



     The parameters of the subroutine are placed between parenthesis behind the

subroutine  name  and  must  be  in  the  same  order  as  the  procedure  call  from  the



                                                             50




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC____________________________________3.9.__PROCEDURES_AND_FUNCTIONS______________________



main program.  All variables used within the subroutine should be declared local

using  the  LOCAL  statement.   The  rest  of  the  procedure  determines  the  task  the

subroutine must perform.

     A  procedure  can  be  called  in  two  ways:   by  using  the  keyword  GOSUB  or  @.

For instance, the procedure progress(), which shows a progress bar on the text

console  given  the  total  amount  a  and  the  fraction  b,  can  be  called  the  following

ways:



GOSUB  progress(100,i)

@progress(100,i)



PROCEDURE  progress(a,b)

    LOCAL  t$

    IF  verbose

        PRINT  CHR$(13);"[";STRING$(b/a*32,"-");"?";

        PRINT  STRING$((1.03-b/a)*32,"-");"---  ";

        PRINT  STR$(INT(b/a*100),3,3);"%  ]";

        FLUSH

    ENDIF

RETURN



3.9.2         Functions


A function starts with a FUNCTION header followed by a function name, and ends

with the keyword ENDFUNCTION. The function is either a numeric or a string func-

tion.   A  numeric  function  defaults  to  the  AEoating  point  data  type  and  needs  no

postox. A string function returns a string and the function name ends with a $ post-

ox.  A function must contain at least one RETURN statement to return the function

value. Functions use this format:


FUNCTION  FuncName[$](parameters)

    LOCAL  vars

    function  logic

    RETURN  value[$]

ENDFUNCTION


     The type of the return value must match the function type. A string function must

return a string and a numeric function a numeric value. The function returns to the



                                                             51




3.9. _PROCEDURES_AND_FUNCTIONS_________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



caller when the RETURN statement is executed.  The ENDFUNCTION statement only

indicates the end of the function declaration and will cause an error if the program

tries to execute this statement.

      A function is called by preceding the function name with @.  As an example, the

string function Copy$() is called as follows:



Right$=@Copy$("X11-Basic",4)



where the function Copy$() might be deoned as:



FUNCTION  Copy$(a$,p)

    LOCAL  b$

    b$=MID$(a$,p)

    RETURN  b$

ENDFUNC



     Of course you are as well free to deone



FUNCTION  Copy$(a$,p)

    RETURN  MID$(a$,p)

ENDFUNC



instead.

     An alternative for FUNCTION is the DEFFN statement, which deones a one line

function.  The  function  Copy$()  used  in  the  example  above,  might  be  used  in  a

DEFFN statement as well:



DEFFN  Copy$(a$,p)=MID$(a$,p)



     In  contrast  with  procedures  and  functions,  DEFFN  functions  may  be  placed

within  a  procedure  or  function  body,  although  it  doesn't  use  the  local  variables

of  the  subroutine.   There  is  another  dioeerence  between  DEFFN  and  FUNCTION:

The  compiler  will  use  the  DEFFN  expression  as  an  inline  expression  and  will  not

produce a function with a symbol name.  This is a bit faster, but produces longer

code.



                                                             52




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC____________________________________3.9.__PROCEDURES_AND_FUNCTIONS______________________



3.9.3         Parameters and local variables


Any X11-Basic variable type can be passed to a procedure or function.  By default

all  parameters  are  passed  "'by  value"'.  Though  parameters  can  also  be  passed

"'by reference"' by using the VAR statement.

     The keyword VAR precedes the list of variables that are being passed as call by

reference parameters.  These variables should always be listed at the end of the

parameter list in the procedure or function heading.  The dioeerence between the

two is that a call by value parameter gets a copy of the passed value and a call by

reference does not.  A VAR variable references the same variable that is passed to

the subroutine.  The original variable will change when a subroutine modioes the

corresponding VAR variable. In fact, both variable names reference the same piece

of memory that contains the variable value.

     Internally, X11-Basic maintains a list of all variables. Each entry in the list points

to a memory location that contains the variable value.  A call by reference variable

points  to  the  same  location  as  the  passed  variable.  Therefore,  constants  or  ex-

pressions can not be passed to a VAR variable.

     All  though  a  (copy  of  an)  Array  can  be  passed  to  a  subroutine  by  value,  the

functions cannot return arrays1 .

     If  a  function  needs  to  return  information  in  form  of  an  array,  the  return  array

sould be passed as a VAR parameter in the parameter list.  The return values can

then be assigned to it inside the function.

     The following example shows a simple function,  which searches a name in a

given string array:



idx%=@SearchName("Jack",Name$())



FUNCTION  SearchName(n$,VAR  n$())

    LOCAL  idx

    CLR  idx

    WHILE  idx!DIM?(n$())  AND  n$(idx)!?n$

        INC  idx

    WEND

    RETURN  idx

ENDFUNC
__________________________________________________
    1This may be possible in future versions of X11-Basic



                                                             53




3.10.__SIMPLE_INPUT/OUTPUT_____________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



      The  locally  used  array  n$()  references  the  global  array  Name$().  The  array

n$()  is  only  valid  within  the  procedure,  where  it  points  to  the  descriptor  of  the

Name$() array.

      You could as well declare the FUNCTION like



FUNCTION  SearchName(n$,n$())



     Then a local copy of the whole array Name$() would be used inside the function,

any changes to n$() would have no eoeect on the original array Name$().  But win

case you wanted to make changes to the array, like in following example:



idx%=@EliminateName("Jack",Name$())



FUNCTION  EliminateName(n$,VAR  n$())

    LOCAL  i

    FOR  i=0  TO  DIM?(n$())

        IF  n$=n$(i)

            n$(i)="deleted."

        ENDIF

    NEXT  i

    RETURN  i

ENDFUNC



you need to use VAR.

     The LOCAL statement lists the variables only known to a procedure or function.

Subroutine parameters are local variables as well. When a subroutine calls another

subroutine the local variables of the calling routine are known in the called routine

as if they were global variables.

     Several  local  variables  separated  by  commas  may  be  listed  after  the  LOCAL

statement. Multiple LOCAL lines are allowed.



3.10         Simple Input/Output



There are many ways in X11-Basic to take data by the user and display other data.

This can be done by taking data from the keyboard, the mouse, a microphone, etc.

and by displaying data to the text console, the graphics window, the speaker, etc.

Also reading and writing to oles and internet connections can be done.



                                                             54




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC______________________________________________3.10.__SIMPLE_INPUT/OUTPUT________________



     The most basic input and output from and to the user is by using the text con-

sole, the so-called standard input and standard output.  This is done in X11-Basic

like in all BASIC dialects with the basic commands PRINT and INPUT.



3.10.1          Printing data to the console


You  actually  already  know  a  X11-Basic  command  to  write  data  on  screen.  This

command is PRINT. It is very versatile and you can extend it in various ways.

     The syntax of PRINT is simple:


PRINT  !data?


where !data? is whatever sort of data you want to print on screen.  That can be

variables,  numbers,  the result of a calculation,  a string or a mix of them all.  You

can even add special commands and functions to your PRINT statement for screen

control such as cursor positioning and formatting of the data.  A few examples for

the PRINT command can be found here:



PRINT  10+5

PRINT  x%

PRINT  10;20;30

PRINT  10,20,30

PRINT  "Hello!"

PRINT  10.123  USING  "+##.###"

PRINT  "y=  ";y

PRINT  "x=";x;"  y=";y;"  z=";z

PRINT  "Your  name  is  ";nam$

PRINT  AT(5,5);"AT()  is  one  of  my  favorites"

PRINT  CHR$(27);"[2J  This  is  a  cleared  console..."



     These  are  the  most  simple  variations  of  the  PRINT  command.   They  can  of

course be more complicated and all features can be combined.

     Now  why  do  you  write  PRINT  "y  =";y  instead  of  PRINT  "y  =",y?   Using

;  will  add  the  following  data  directly  behind  your  text  without  altering  the  cursor

position  while  the  ,  will  advance  the  cursor  to  the  next  vertical  tabular  position.

You  can  use  that  to  align  your  data  in  tables  on  screen.  In  short,  if  you  want  to

write data directly to some sort of prompt or behind some text, use the ; notation.

Put  a  ;  as  the  last  data  on  your  PRINT  statement  to  let  the  cursor  stay  on  the



                                                             55




3.10.__SIMPLE_INPUT/OUTPUT_____________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



current line.  You can use this to prevent a scrolling on the last line of the screen

or  if  you  simply  want  to  split  writing  of  prompt  and  data  into  two  lines  of  code.

Technically speaking giving the ; last will suppress a carriage return.



3.10.2          Screen control


Now that you know how to write your data on screen, you will also want to know

how to handle screen output in detail. How do I leave a line of text blank might you

ask? Write simply PRINT without any data behind to output a blank line on screen.

Try this 3 lines program:



PRINT  "Hello!"

PRINT

PRINT  "This  is  the  first  example  for  screen  control!"



     As you see it prints the greeting and the other line with an empty line between.

     A very important thing is how to clear the screen.  For obvious reasons, you'll

sometimes prepare a screen layout that requires you not to have other text or old

data on screen. You'll simply clear the screen with the following command.



CLS


     A neat thing is to write on screen exactly on a position where you want and not

following the listed AEow of ordinary PRINT statements. You can use the AT() state-

ment.  This special addition for PRINT allows you to position the cursor freely on

screen so you can write your data where you want. Let's try the following example

program:



CLS

PRINT  AT(1,1);"Top  left"

PRINT  AT(5,13);"Middle  line,  text  indented  5  chars"

PRINT  AT(20,25);"bottom  line";



     The syntax for PRINT  AT(); is PRINT  AT(column,  row);, where row 1 is on

top of the screen and column 1 on the left end. Column and row can be variables,

expressions or simply a plain number. Valid PRINT  AT() commands are:



                                                             56




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC______________________________________________3.10.__SIMPLE_INPUT/OUTPUT________________



PRINT  AT(1,5);"Hello"

PRINT  AT(5+x%,10);"x"

PRINT  AT(4+8,y%);"y  =  "


     How  many  character  positions  you  have  depends  on  the  current  text  console

screen  size.   You  have  almost  always  at  least  24  lines  of  text.   80  columns  are

standard.  If you want to exactly know the number of rows and columns of the text

screen, you can use the (system) variables ROWS and COLS.



?  PRINT  ROWS,COLS

24            80


     There  are  more  commands  you  can  use  with  PRINT  like  SPC()  and  TAB().

Refer to the command reference on them.



3.10.3          Formatting output with PRINT USING


X11-BASIC normally prints numbers in a form convenient for most purposes.  But

on occasion you may prefer a more elaborate form.  For example,  you may want

to print onancial quantities with two decimal places (for cents) and, possibly, with

commas inserted every three digits to the left of the decimal point.  Or, you want

to print the numbers in scientioc notation.  PRINT  USING provides a way to print

numbers in this and almost any other form1 .

     The generic syntax is


PRINT  !expression?  USING  "!format  string?"


.  The result of the expression should be a number.  The format string deones how

you want your data to be formatted on screen.  The format string may be a string

variable, a quoted string, or a more general string expression.

     PRINT  USING also allows one to print strings centered or right-justioed, as well

as left justioed.

     The function USING$() duplicates the PRINT USING statement almost exactly2

but returns the result as a string rather than printing it on the screen.

     Unlike STR$(),  where you can specify the length of the string,  the number of

signiocant digits of the number and a AEag, where there leading zeroes should be
__________________________________________________
    1There are also other built-in commands for formatting data on output.  X11-Basic ooeers e.g.  STR$().  Please

refer to the sections on functions for details on the syntax of STR$().
    2only numbers can be formatted, no strings.



                                                             57




3.10.__SIMPLE_INPUT/OUTPUT_____________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



used, USING$() and PRINT  USING use a classic and BASIC-style formatter string

for formatting numbers.  The dioeerence between USING$() and PRINT  USING is

just, that PRINT  USING immediately prints out the formatted number and USING$()

converters it into a string containing the formatted number, suitable for further pro-

cessing.



Formatting Numbers


The format string can contain any letters,  but some have a special meaning.  All

other characters are just taken as they are. The length of the format string deones

the length of the output oeld.  Whatever is formatted,  it will exactly take as many

characters as the length of the format string.

     The most important special character in the format string is the symbol #, which

stands for a digit position to be olled with one digit from the number to be formatted.

For example, compare the output resulting from two similar PRINT statements, the

orst a normal PRINT statement and the second employing USING.



x=      ---PRINT  x---  PRINT  x  USING  "###"

-----+-------+--------------------

1        ---  1          ---      1

12      ---  12        ---    12

123    ---  123      ---  123

1234  ---  1234    ---  ***

-12    ---  -12      ---  -12



     Without USING, the number is printed left justioed and occupying only as much

space as needed.  With USING, the format string "###" specioes a oeld length of

exactly three characters. The number is printed right-justioed in this oeld. If the oeld

is not long enough to print the number properly, asterisks are printed instead. If all

you need to do is to print integer numbers in a column but with right-justiocation,

then the preceding example will suOEce. Note that a negative number will be printed

with the sign occupying one of the digit oelds.

     With  printing  onancial  quantities  it  is  conventional  that  the  decimal  points  are

aligned.  Also, you may want to print two decimal places (for the cents) even when

they  are  zero.   The  following  example  shows  how  to  do  this.   (In  order  to  print

negative numbers and have the sign at a oxed position,  the format string should

start with a minus sign.)



                                                             58




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC______________________________________________3.10.__SIMPLE_INPUT/OUTPUT________________



x=        ---PRINT  x  USING  "-##.##"

------+-----------------------

1          ---    1.00

1.9      ---    1.90

-3.14  ----  3.14

1.238  ---    1.24

123      ---******

0          ---    0.00

-123    ---******



     Notice  that  in  this  example  two  decimal  digits  are  always  printed,  even  when

they consist of zeroes. Also, the result is orst rounded to two decimals. If the num-

ber is negative, the minus sign occupies the leading digit position or the position

given by a - or + in the format string. If the number is too long to be printed properly

(possibly because of a minus sign), asterisks are printed instead.

     Financial  quantities  are  often  printed  with  a  leading  dollar  sign  ($),  and  with

commas forming three-digit groups to the left of the decimal point.  The following

example shows how to do this with PRINT  USING.



x=                  ---PRINT  x  USING  "$#,###,###.##"

-----------+------------------------------

0                    ---$                0.00

1                    ---$                1.00

1234              ---$        1,234.00

1234567.89  ---$1,234,567.89

1e6                ---$1,000,000.00

1e7                ---10,000,000.00

1e8                ---*************



     The dollar sign is only printed if the space is not needed for a digit.  It is always

in  the  same  position  (orst)  in  the  oeld.  The  separating  commas  are  printed  only

when needed.

     In case you want the dollar sign ($) to AEoat to the right, so that it appears next

to the number, avoiding all those blank spaces between the dollar sign and the orst

digit in the preceding example. The following example shows how to do this.



x=                  ---PRINT  x  USING  "$$,$$$,$$#.##"

-----------+----------------------------



                                                             59




3.10.__SIMPLE_INPUT/OUTPUT_____________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



0                    ---                $0.00

1                    ---                $1.00

1234              ---        $1,234.00

1234567.89  ---$1,234,567.89



      The format string can also allow leading zeroes to be printed, or to be replaced

by asterisks (*). You might ond the latter useful if you are preparing a check-writing

program.



x=                  ---PRINT  x  USING  "$0,000,000.##"

-----------+------------------------------

0                    ---$0,000,000.00

1                    ---$0,000,001.00

1234              ---$0,001,234.00

1234567.89  ---$1,234,567.89



x=                  ---PRINT  x  USING  "$*,***,***.##"

-----------+------------------------------

0                    ---$********0.00

1                    ---$********1.00

1234              ---$****1,234.00

1234567.89  ---$1,234,567.89



x=                  ---PRINT  x  USING  "*$$,$$$,$$#.##"

-----------+------------------------------

0                    ---*********$0.00

1                    ---*********$1.00

1234              ---*****$1,234.00

1234567.89  ---*$1,234,567.89



      For  compatibility  reasons,  a  %  can  be  used  instead  of  the  0's  in  the  format

string,  with one exception:  The orst character in the format string must not be a

%1 .

      You can also format numbers using scientioc notation. Because scientioc nota-

tion has two parts, the decimal-part and the exponent-part, the format string must

also  have  two  parts.  The  decimal-part  follows  the  rules  already  illustrated.  The
     _______________________________________________________
    1If the orst character is a % the format string is interpreted as a C style printf format string (see below).



                                                             60




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC______________________________________________3.10.__SIMPLE_INPUT/OUTPUT________________



exponent-part consists of from three to ove carets (#) that should immediately follow

the decimal-part. The following example shows how.


x=                    ---PRINT  x  USING  "+#.#####^^^^"

------------+-----------------------------

0                      ---+0.00000e+00

123.456          ---+1.23456e+02

-.001324379  ----1.32438e-03

7e30                ---+7.00000e+30

0.5e100          ---+5.00000e+99

5e100              ---************


     The  leading  plus  sign  (+)  in  the  format  string  guarantees  that  the  sign  of  the

number  will  be  printed,  even  when  the  number  is  positive.   Notice  that  the  last

number  cannot  be  formatted  because  the  exponent  part  would  have  been  100,

which requires an exponent oeld of ove carets.  Notice also that if there are more

carets than needed for the exponent, leading zeroes are inserted.  Finally, notice

that trailing zeroes in the decimal part are printed.

     In  addition  to  the  format  rules  explained  above,  X11-Basic  ooeers  another  but

dioeerent set of format strings.  If the orst character of the format string is a % the

format string is treated as a C style so-called printf-formatter.

     Here are some examples:


x=                    ---format$=          ---PRINT  x  USING  format$

------------+------------------------------------

0                      ---  "%012g"          ---000000000000

123.456          ---  "%.1g"            ---1e+02

-.001624        ---  "%.1g"            ----0.002


     These formatting strings follow some standard which is normally not used in BA-

SIC. The standard is well explained in Wikipedia:  http://en.wikipedia.org/

wiki/Printf.format.string#Format.placeholders.



Formatting Strings


Strings  can  also  be  formatted  through  PRINT  USING  but  not  with  the  function

USING$(), although there are fewer options for strings than for numbers.  Strings

can be printed in the formatted oeld either left justioed, centered, or right-justioed.

As with numbers, if the string is too long to ot, then asterisks are printed.



                                                             61




3.10.__SIMPLE_INPUT/OUTPUT_____________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



      These examples should make it clear:



PRINT  "---";"OK"  USING  "#####";"---"          !  result:  ---  OK    ---

PRINT  "---";"OK"  USING  "?####";"---"          !  result:  ---      OK---

PRINT  "---";"Hello"  USING  "?####";"---"    !  result:  ---Hello---

PRINT  "---";"Goodby"  USING  "?####";"---"  !  result:  ---*****---



     If centering cannot be exact, the extra space is placed to the right. Actually any

string  can  be  used  as  a  format  string.   Only  the  length  of  the  string  deones  the

length of the output oeld.  Only the orst character of the format string matters.  If it

is a ! the string will be left justioed, if it is a ? it will be right-justioed and centered in

any other case. This is especially valuable for printing headers for a numeric table.

The following example shows how you can format headers using the same format

string we used earlier for numbers.



s$=                                     ---PRINT  s$  USING  "$#,###,###.##"

----------------------+-------------------------------

"Cash"                               ---                                       Cash

"Liabilities"                  ---                                 Liabilities

"Accounts  Receivable"  ---                               *************



3.10.4          Gathering User Input


You can make your program interactive and ask the user to enter data on runtime

of your program.

     The command INPUT allows the user to enter one line of data with the keyboard

on the text console.  The data is interpreted and stored in one or more variables

specioed by the INPUT statement.  If you specify a string variable, you can enter

text while you can only enter numeric data if you use a numeric variable.  A minus

sign and optional decimal point are allowed for numeric input.  Also numbers can

be entered in scientioc notation. Hexadecimal values are possible, too.



INPUT  "x=  ",x

INPUT  "What  is  your  name?  ",your.name$



     This will prompt the user to enter a value for x which will be stored into a (AEoating

point) variable x.  You can then use this variable in your program as normal, doing



                                                             62




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________________________________3.11.__FLOW_CONTROL_____________



calculations with it.  Please note that your program will stop until the RETURN key

or the ENTER key has been pressed to terminate the input.

     You can read more than one variable with one INPUT statement, just list your

variables where you want your input to go to with separating commas.



PRINT  "enter  3  values,  separated  with  commas  (eq  3,4,5):"

INPUT  x%,y%,z%


     The user has then to enter commas at the appropriate places to tell which input

goes to which variable. To the example above the user would respond with 5,6,7.



CLS

INPUT  "Enter  a  value  for  x:",x

PRINT  "x  =  ";x

INPUT  "What  is  your  name?",your.name$

PRINT  "Your  name  is  ";your.name$;"."

PRINT  "Bye,  ";your.name$;"!"


     While entering strings you may have already noticed that X11-Basic will treat

entering a comma again as a delimiter, eoeectively cutting your string at that comma.

Use the command LINEINPUT instead of INPUT to read strings.



LINEINPUT  txt$


     You  can  now  enter  strings  with  a  comma  in  and  it  will  be  saved  to  the  string

variable as well. You can read multiple strings with LINEINPUT as well but the user

has to press the RETURN key terminating each string to be entered.



3.11         Flow Control



This time you'll onally make your programs do things more then once without hav-

ing  to  retype  your  code.   The  creation  of  so-called  loops  is  essential  for  making

complex programs work. The concept of looping and simple counting loops

     Before going further let me explain you the fundamental idea of looping.  The

idea is to make your program repeat a section of code for a deoned amount of time.

You may let X11-Basic count a variable for you and you can then use the value of

that  variable  in  an  ongoing  calculation.  Or  you  can  let  X11-Basic  loop  a  certain

part of code until a special condition has been met.  Take a look at the following

sample program:



                                                             63




3.11.__FLOW_CONTROL____________________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



FOR  i%=1  TO  5

    PRINT  i%

NEXT  i%



     This little example program loops 5 times and counts the variable i% from 1 to

5  and  prints  the  current  value  to  the  screen.   This  sort  of  loop  is  called  a  FOR-

NEXT-loop.  You can use any numerical variable to count.  Most often this sort of

loop  is  used  to  do  things  a  certain  amount  of  time  or  to  iterate  over  a  list.   The

loop will repeat the code between the FOR and its corresponding NEXT. Each time

X11-Basic reaches the NEXT, it will increment the count variable and will stop the

loop if the maximum count has been reached.

     You can of course have another loop inside the current one. Just make sure not

to use the same variable for counting or X11-Basic will do unpredictable things:



FOR  i%=1  TO  5

    FOR  j%=1  TO  10

        PRINT  i%;"  *  ";j%;"  =  ";i%*j%

    NEXT  j%

NEXT  i%



     That sample program has one FOR-NEXT-loop in another and it calculates the

product  of  the  both  counter  variables  creating  some  sort  of  multiplication  table.

Some rules and advice to keep in mind with FOR-NEXT-loops:



    1.  Always terminate an opened FOR with a corresponding NEXT.

    2.  Always terminate FOR-loops in the correct order. If you write FOR  i%=. . . orst

        and FOR  j%=. . . next, make sure to terminate the inner loop orst.

    3.  You can count downwards with the word DOWNTO instead of TO. Try:



        FOR  i%=5  DOWNTO  1



    4.  You can count in steps not equal 1 with the keyword STEP:



        FOR  i%=1  TO  10  STEP  2



        That will increment i% in steps of 2 until it reaches 10.

    5.  You can terminate the FOR-NEXT-loop with the EXIT  IF statement.



                                                             64




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________________________________3.11.__FLOW_CONTROL_____________



Conditions


A very fundamental idea in programming is to create and use conditionals.  These

will  allow  you  to  make  decisions  when  certain  conditions  are  met  and  let  your

program take an alternative code segment.

     Try to imagine that you count a special variable and want to do something else

when the value of your counter is 5:



FOR  i%=1  to  10

    IF  i%=5

        PRINT  "i%  is  now  5"

    ELSE

        PRINT  "i%  is  not  5"

    ENDIF

NEXT  i%


     This program loops 10 times and counts in the variable i%.  For each iteration

of the loop it checks if i% is 5 in the IF line.  If that condition is true, i% is 5, then

it executes the program branch until the ELSE and omits the following part.  If the

condition is not true, X11-Basic will only execute the part behind the ELSE. Make

sure to terminate each IF conditional with an ENDIF or X11-Basic will get lost and

produce an error message.

     You may leave out the ELSE fork. X11-Basic will then do nothing if the condition

is not true.



3.11.1          Conditional and endless loops


Sometimes you don't know how far you need to count for a special operation.  Or

imagine a game.  You don't want to let it run just for 10 frames but until the player

sprite did collide or something like that. The orst new loop will loop until a condition

is fulolled:



REPEAT

...

UNTIL  !condition?



     This is a so-called REPEAT-UNTIL-loop.  It loops at least once and checks for

the condition after the loop contents have been executed by X11-Basic.  Use it for



                                                             65




3.11.__FLOW_CONTROL____________________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



things that need to be done at least once. You can emulate FOR-NEXT-loops with

it if you want trickier counting:



i%=1

REPEAT

    PRINT  "i%=";i%

    i%=i%+1

UNTIL  i%?5


     Surely you can test the condition before entering a loop.  This is useful if you

want to loop only when a certain condition is already true:


WHILE  !condition?

...

WEND


     This is the so-called WHILE-WEND loop.  It checks the condition orst and it will

not execute the loop body if the condition is not fulolled.  Sometimes you want to

loop endless. X11-Basic has a special loop construct for this purpose although you

can create never ending loops easily with the types above if you use a condition

that will never get true.  The never ending loop is called DO-loop.  The 3 loops in

the example are all equal in functionality and will loop endless.



DO

    PRINT  "endless"

LOOP



i%=0

REPEAT

    PRINT  "endless"

UNTIL  i%=1



i%=0

WHILE  i%=0

    PRINT  "endless"

WEND


     At this point it is important that you know you can terminate at your X11-Basic

program at any point.  This is useful if your program gets stuck in an endless loop



                                                             66




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC____________________________________________________________3.12.__DIAGNOSTICS__________



which was not intended.  Press CONTROL-c together and X11-Basic will stop the

program. Another CONTROL-c will quit the interpreter.

     Sometimes you will want to terminate a running loop at another point than the

oOEcial  loop  beginning  or  loop  end.  Use  the  EXIT  IF  statement  in  your  loop  for

extra conditions.  This will also terminate FOR-NEXT-loops if you wish to and it is

the only way to terminate a DO-LOOP.



i%=1

DO

    PRINT  "i%=";i%

    EXIT  IF  i%=5

    i%=i%+1

LOOP


     Please note that the EXIT  IF statement has no ENDIF or the like. It just termi-

nates the loop and continues your program behind the loop end.



3.12         Diagnostics



Some  errors  can  be  caught  by  the  user  program  using  the  ON  ERROR  GOTO  or

ON  ERROR  GOSUB command.  If no error trapping routine has been supplied then

program execution is terminated and a message is printed with the corresponding

line  number.  The  error  messages  are  standardized.  Each  error  message  has  a

corresponding number which can be referenced by the system variable ERR. A list

of standard error messages by number can be found in chapter 5.25.



                                                             67




3.13.__ADDRESS_SPACES__________________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



3.13         Address Spaces



The full accessible Program memory can be accessed by PEEK/POKE, LPEEK/LPOKE,

DPEEK/DPOKE. Be careful. You can manipulate all symbols of the interpreter and or

dynamically linked libraries and your program.  Address spaces belonging to other

programs which are not shared memory blocks can not be accessed.  You will get

a segmentation fault on trying this.



3.14         Graphics:  Drawing and Painting



A graphics window will be automatically opened when the orst graphic command

appears in your program.  Without using any graphic commands no X11-Server is

needed at all and your programs also runs under a text console or as a daemon

or  as  CGI  scripts.   But  if  you  want  to  draw  anything  with  e.g.   LINE,  CIRCLE  or

BOX, control the MOUSE pointer, the keyboard or use the graphical user interface

with  e.g.   ALERT  or  MENU,  a  graphic  window  will  open  with  the  default  geometry

640x400.  All  graphic  output  can  be  done  in  full  color  which  can  be  set  with  the

GET.COLOR() and the COLOR statements. Moreover, there can be up to 16 dioeerent

graphic windows opened at a time.  Please note that all graphics is displayed after

a SHOWPAGE command only. This allows fast animations.

     To  allow  for  animated  bitmap  graphics  and  icons,  X11-Basic  ooeers  the  com-

mands GET and PUT, which retrieve rectangular regions from the graphics-window

into a string or put back bitmap graphics data from the string to the graphics screen

or window. The ole format used with PUT is a standard .BMP bitmap, so also exter-

nally created icons can be used. Transparency and alpha channels are supported.



3.15         Reading from and Writing to Files



Before  you  may  read  from  or  write  to  a  ole,  you  need  to  open  it;  once  you  are

done, you should close it. Each open ole is designated by a simple number, which

might be stored within a variable and must be supplied to the PRINT and INPUT

commands if you want to access the ole.

     If you need more control, you may consider reading and writing one byte at a

time, using the multi-purpose commands INP() and OUT, or reading the whole ole

as a binary block with BLOAD.



                                                             68




CHAPTER_3.3.PROGRAMMING1IN6X11-BASIC.__INTERNET_AND_BLUETOOTH_CONNECTIONS,_SPECIAL_FILES_AND_SOCKETS________________________



3.16         Internet and bluetooth connections, special oles and sock-


             ets



X11-Basic allows to connect a program to another program on a dioeerent (or the

same) host computer via standard internet or bluetooth protocols or pipes.

     Basically there are two methods of connections to other computers on a net-

work:  A stream based connections (well known is the TCP/IP protocol for internet

connections)  and  a  connectionless,  unreliable  datagram  packet  service  (UDP,  in

case of internet connections, and e.g. L2CAP for bluetooth).

     Another method of passing data between two applications on the same com-

puter is using so-called pipes. Pipes are special oles which are created in the local

olesystem.



3.16.1          Local inter process communication:  Pipes


A pipe is a unidirectional data channel that can be used for interprocess communi-

cation.  The UNIX kernel usually supports this mechanism.  The pipe can be used

to send information or data from one process to another.  Here is a little example

progam you can use to play with it:



PIPE  #1,#2
a=FORK()
IF  a=0      !  Child  instance
   GPRINT  "Hi,  I  am  Child  !",b
   DO
      SHOWPAGE
      LINEINPUT  #1,t$
      GPRINT  t$
   LOOP
   '  This  instance  never  ends  ...
ELSE  IF  a=-1
   PRINT  "ERROR,  fork()  failed  !"
   QUIT
ELSE         !  parent  instance
   DO
      DUMP
      ALERT  1,"Hi,  I  am  Parent.  Child  PID="+str$(a),1,"  OK  ---  Kill  Child  !  ",b
      DUMP
      PRINt  #2,SYSTEM$("date")
      FLUSH  #2
      IF  b=2
         SYSTEM  "kill  "+str$(a)



                                                             69




3.16.__INTERNET_AND_BLUETOOTH_CONNECTIONS,_SPECIAL_FILES_AND_SOCKETSCHAPTER_3.__PROGRAMMING_IN_X11-BASIC___________________________*
 *___



         ALERT  1,"Child  PID="+str$(a)+"  killed  !",1,"  OK  ",b
         QUIT
      ENDIF
   LOOP
ENDIF
QUIT


     Instad of with pipes,  the interprocess communication can also be done using

a shared memory segment.  X11-Basic also supports commands for creating and

accessing such shared memory segments.



3.16.2          World-Wide communication:  Sockets


Most inter-process communication uses the client server model. These terms refer

to the two processes which will be communicating with each other. One of the two

processes, the client, connects to the other process, the server, typically to make

a request for information.  A good analogy is a person who makes a phone call to

another person.

     Notice that the client needs to know of the existence of and the address of the

server, but the server does not need to know the address of (or even the existence

of)  the  client  prior  to  the  connection  being  established.   Notice  also  that  once  a

connection is established, both sides can send and receive information.

     When a socket is created, the program has to specify the address domain and

the  socket  type.   Two  processes  can  communicate  with  each  other  only  if  their

sockets are of the same type and in the same domain.  There are two widely used

address  domains,  the  (local)  Unix  domain,  in  which  two  processes  which  share

a common ole system communicate,  and the Internet domain,  in which two pro-

cesses running on any two hosts on the Internet communicate. Each of these has

its own address format.  Another domain to be mentioned is the bluetooth domain

for short range radio connections.  It works similar to the internet connections, but

uses its own address space.

     The address of a socket in the Unix domain is a character string which is basi-

cally an entry in the ole system. It can be acced from there like a ole. In X11-Basic

the normal ole i/o commands can be used.

     The address of a socket in the Internet domain consists of the Internet address

of the host machine (every computer on the Internet has a unique 32 bit address,

often referred to as its IP address or the bluetooth id, if we are takling about blue-

tooth  connections).   In  addition,  each  socket  needs  a  port  number  on  that  host.

Port numbers are 16 bit unsigned integers. The lower numbers are reserved in the



                                                             70




CHAPTER_3.3.PROGRAMMING1IN6X11-BASIC.__INTERNET_AND_BLUETOOTH_CONNECTIONS,_SPECIAL_FILES_AND_SOCKETS________________________



internet for standard services.  For example,  the port number for the FTP server

is 21.  It is important that standard services be at the same port on all computers

so that clients will know their addresses.  However, port numbers above 2000 are

generally available.



Socket Types   There are two widely used socket types, stream sockets, and data-

gram  sockets.   Stream  sockets  treat  communications  as  a  continuous  stream  of

characters, while datagram sockets have to read entire messages at once.  Each

uses  its  own  communications  protocol.   Stream  sockets  for  internet  connections

use TCP (Transmission Control Protocol), which is a reliable, stream oriented pro-

tocol, and datagram sockets use UDP (Unix Datagram Protocol), which is unreli-

able and message oriented.

     The same applies for bluetooth connections, stream sockets use the so-called

RFCOMM protocol and datagram sockets use the L2CAP protocol.

     Sockets in X11-Basic can be crated with the OPEN command.



TCP/IP   Transmission Control Protocol (TCP) provides a reliable byte-stream trans-

fer  service  between  two  endpoints  on  an  internet.  TCP  depends  on  IP  to  move

packets around the network on its behalf.  IP is inherently unreliable, so TCP pro-

tects against data loss, data corruption, packet reordering and data duplication by

adding checksums and sequence numbers to transmitted data and, on the receiv-

ing side, sending back packets that acknowledge the receipt of data.

     Before sending data across the network, TCP establishes a connection with the

destination via an exchange of management packets. The connection is destroyed,

again  via  an  exchange  of  management  packets,  when  the  application  that  was

using TCP indicates that no more data will be transferred.

     TCP has a multi-stage AEow-control mechanism which continuously adjusts the

sender's data rate in an attempt to achieve maximum data throughput while avoid-

ing congestion and subsequent packet losses in the network.  It also attempts to

make the best use of network resources by packing as much data as possible into

a single IP packet.

     The system calls for establishing a connection are somewhat dioeerent for the

client  and  the  server,  but  both  involve  the  basic  construct  of  a  socket.  A  socket

is one end of an inter-process communication channel.  The two processes each

establish their own socket.

     The steps involved in establishing a socket on the client side are as follows:



                                                             71




3.16.__INTERNET_AND_BLUETOOTH_CONNECTIONS,_SPECIAL_FILES_AND_SOCKETSCHAPTER_3.__PROGRAMMING_IN_X11-BASIC___________________________*
 *___



    1.   Create a socket with the OPEN command providing a port number



            OPEN  "US",#1,"client",5000


    2.  Connect the socket to the address of the server using the CONNECT com-

        mand



            CONNECT  #1,"ptbtime1.ptb.de",13



    3.  Instead of using Steps 1 and 2, you can alternatively use the combined com-

        mand:



            OPEN  "UC",#2,"ptbtime1.ptb.de",13



    4.  Send  and  receive  data.   There  are  a  number  of  ways  to  do  this,  but  the

        simplest is to use the PRINT, SEND, WRITE, READ, RECEIVE INPUT com-

        mands.



            PRINT  #2,"GET  /index.html"

            FLUSH  #2

            WHILE  INP?(#2)

                LINEINPUT  #2,t$

                PRINT  "got:  ";t$

            WEND


    5.  close the connection with



          CLOSE  #1



     The steps involved in establishing a socket on the server side are as follows:



    1.  Create a socket with the OPEN command and bind the socket to a port num-

        ber on the host machine.



            OPEN  "US",#1,"server",5000


    2.  Listen for connections and

    3.  Accept a connection with this other OPEN command, which opens a connec-

        tion to the connected client:



                                                             72




CHAPTER_3.3.PROGRAMMING1IN6X11-BASIC.__INTERNET_AND_BLUETOOTH_CONNECTIONS,_SPECIAL_FILES_AND_SOCKETS________________________



            OPEN  "UA",#2,"",1



        This call typically blocks until a client connects with the server.

    4.  Send and receive data on the accepted connection



            PRINT  #2,"Welcome  to  X11-Basic  test-server  ..."

            FLUSH  #2

            DO

                IF  INP?(#2)

                    LINEINPUT  #2,t$

                    PRINT  "got:  ";t$

                ENDIF

                EXIT  IF  t$="quit"

            LOOP

            PRINT  #2,"goodbye..."

            FLUSH  #2



    5.  close the established connection with



          CLOSE  #2



        and listen to the next connection (folow step 3) or

    6.  close the socket if not further needed.



          CLOSE  #1



UDP   User Datagram Protocol (UDP) provides an unreliable packetized data trans-

fer service between endpoints on a network.

     First, a socket has to be crated with the OPEN command:



    OPEN  "UU",#1,"sender",5556



     When a UDP socket is created, its local and remote addresses are unspecioed.

Datagrams can be sent immediately using SEND with a valid destination address

and port as argument:



SEND  #1,"This  is  my  message",CVL(CHR$(131)+CHR$(195)+CHR$(15)+CHR$(200)),5000



                                                             73




3.17.__BLUETOOTH_CONNECTIONS___________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



      UDP uses the IPv4 address format, so a long integer has to be passed.

      When CONNECT is called on the socket the default destination address is set

and  datagrams  can  now  be  sent  using  SEND  without  specifying  an  destination

address.  It is still possible to send to other destinations by passing an address to

SEND.



CONNECT  #1,"localhost",5555

SEND  #1,"This  is  my  message"



     All receive operations return only one packet.



IF  INP?(#1)

    RECEIVE  #1,t$,adr

    PRINT  "Received  Message:  ";t$;"  from  ";HEX$(adr)

ENDIF


     INP?(#n) Returns the size of the next pending datagram in bytes, or 0 when no

datagram is pending.

     The Socket should be closed when the connection is not going to be used any

more:



CLOSE  #1


     UDP  does  not  guarantee  to  actually  deliver  the  data  to  the  destination,  nor

does it guarantee that data packets will be delivered to the destination in the order

in which they were sent by the source,  nor does it guarantee that only one copy

of the data will be delivered to the destination. UDP does guarantee data integrity,

and it does this by adding a checksum to the data before transmission.



3.17         Bluetooth connections



Establishing a connection between two devices with a bluetooth adapter is similar

to  the  internet  connections.   Also  here  you  can  use  a  stream  based  connection

(using RFCOMM) or a datagram based one (using L2CAP).

     The  X11-Basic  commands  for  doing  so  are  also  similar.   The  only  noticable

dioeerence is that instead of a IP address a bluetooth id need to be used and there

is  no  domain  name  system  which  can  be  asked  for  the  address/id  of  a  device

knowing its name.



                                                             74




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC_______________________________________3.17.__BLUETOOTH_CONNECTIONS_____________________



     That means, if you want to connect to a bluetooth device, you need to know its

id before.  The id consists of six bytes (instead of four in case of a IPV4 internet

address). They are usually noted as a string of the format: hh:hh:hh:hh:hh:hh with

all 6 bytes in two-digit hex values separated by colons: e.g. "78:F5:FD:15:4A:3A".

     You  can  either  hardcode  the  id  in  your  program,  or  you  can  scan  for  visible

bluetooth devices.

     The scan can be done in X11-Basic with the FSFIRST$() and FSNEXT$() func-

tions:



a$=FSFIRST$("","*","b")

WHILE  LEN(a$)

    PRINT  a$

    PRINT  "Adress:  ";WORD$(a$,1)

    PRINT  "Name:      ";WORD$(a$,2)

    adr$=WORD$(a$,1)

    a$=FSNEXT$()

WEND



RFCOMM   RFCOMM (Radio frequency communication) provides a simple reliable

data stream to the user, similar to TCP.

     Many Bluetooth applications use RFCOMM because of its widespread support

and  publicly  available  API  on  most  operating  systems.  Additionally,  applications

that used a serial port to communicate can be quickly ported to use RFCOMM.

     As with TCP/IP establishing a connection via RFCOMM involves the basic con-

struct of a socket.  The two processes (server and client) each establish their own

socket.

     The  steps  involved  in  establishing  a  socket  on  the  client  side  are  as  follows

(assuming, that the bluetooth id you ant to connect to is in adr$):



    1.  Create a socket with the OPEN command providing a port number (TODO??)

    2.  Connect the socket to the address of the server using the CONNECT com-

        mand

    3.  Instead of using Steps 1 and 2, you can alternatively use the combined com-

        mand:

    4.  Send  and  receive  data.   There  are  a  number  of  ways  to  do  this,  but  the

        simplest is to use the PRINT, SEND, WRITE, READ, RECEIVE INPUT com-

        mands.



                                                             75




3.17.__BLUETOOTH_CONNECTIONS___________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



            PRINT  #2,"Hello"

            FLUSH  #2

            WHILE  INP?(#2)

                LINEINPUT  #2,t$

                PRINT  "got:  ";t$

            WEND


    5.  close the connection with



          CLOSE  #1



     The steps involved in establishing a socket on the server side are as follows:



    1.  Create a socket with the OPEN command and bind the socket to a port num-

        ber on the host machine. (TODO: port number ????)

    2.  Listen for connections and

    3.  Accept a connection with this other OPEN command, which opens a connec-

        tion to the connected client:



            OPEN  "UA",#2,"",1



        This call typically blocks until a client connects with the server.

    4.  Send and receive data on the accepted connection



            PRINT  #2,"Welcome  to  X11-Basic  test-server  ..."

            FLUSH  #2

            DO

                IF  INP?(#2)

                    LINEINPUT  #2,t$

                    PRINT  "got:  ";t$

                ENDIF

                EXIT  IF  t$="quit"

            LOOP

            PRINT  #2,"goodbye..."

            FLUSH  #2


    5.  close the established connection with



                                                             76




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC__________________________________________3.18.__ACCESSING_USB_DEVICES__________________



          CLOSE  #2


        and listen to the next connection (folow step 3) or

    6.  close the socket if not further needed.



          CLOSE  #1



L2CAP   (Logical link control and adaptation protocol)

     First, a socket has to be crated with the OPEN command:

     When a L2CAP socket is created, its local and remote addresses are unspec-

ioed.   Datagrams  can  be  sent  immediately  using  SEND  with  a  valid  destination

address and port as argument:

     TODO.... uses the IPv4 address format, so a long integer has to be passed.

     When CONNECT is called on the socket the default destination address is set

and  datagrams  can  now  be  sent  using  SEND  without  specifying  an  destination

address.  It is still possible to send to other destinations by passing an address to

SEND.

     All receive operations return only one packet.

     INP?(#n) Returns the size of the next pending datagram in bytes, or 0 when no

datagram is pending.

     The Socket should be closed when the connection is not going to be used any

more:



CLOSE  #1


     The maximum packet size should not exceed 672 bytes.

     Bluetooth  support  is  work  in  progress  and  may  not  yet  work  on  Android  and

WINDOWS.



3.18         Accessing USB devices



X11-Basic has a builtin USB interface, which allows X11-Basic programs to access

USB-Devices,  which  are  connected  to  the  computer.  The  interface  is  on  a  near

hardware level, so the driver for the specioc hardware connected must be written

in  X11-Basic.   Hence,  it  is  well  possible  to  use  dataloggers  and  USB-to-RS232

adapters with this methods. In principle every USB-Device can be accessed, if the

protocol for data transfers and data interpretation is known.



                                                             77




3.19.__DATA_WITHIN_THE_PROGRAM_________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



      Please  see  the  example  program  usb-VDL101T.bas  for  an  example,  how  to

readout data from a VOLTCRAFT  VDL101-T datalogger.

      USB support is work in progress and may not yet work on Android and WIN-

DOWS.

      USB-Devices are opened with the OPEN command.  Instead of a olename,  a

combination if PID/VID is used.  Once opened, the commands CLOSE, IOCTL(),

SEND and RECEIVE can be used on that device. (PRINT and INPUT currently will

not work).



3.19         Data within the program



You may store data within your program within DATA-statements; during execution

you will probably want to READ it into variables or arrays.  Also the assignment of

constant to arrays may be used to store data in your program and last but not least

the INLINE$() function may be used to store huge binary data segments.

     The orst example shows how to store conventional data (numbers and strings)

within the sourcecode of a basic program:



'  example  how  to  use  the  DATA  statement



RESTORE  mydata

READ  name$,age,address$,code



mydata:

DATA  "Bud  Spencer",30,"Holywood  Street",890754

DATA  "Hannelore  Isendahl",15,"Max-Planck-Allee",813775


     The following example shows how to store arbitrary binary data, which can be

used e.g.  to store the bitmapdata for a bitmap (    ).  Or also for other resources

like pictograms and any other bitmap or icon.



'  output  of  inline.bas  for  X11-Basic  23.04.2002
'  demo  104  Bytes.
demo$=""
demo$=demo$+"5*II@V%M@[4D=*9V,)5I@[4D=*9V,(IR?*IR=6Y*A:]OA*IS?F".&IAI?J"D8ZII"
demo$=demo$+",*5M=;1I@V%P=;1I?F%OaJ]R=:"P,*5E?J"D?*)X,*9W,*AI?ZUE@+%X/F"R&JAV"
demo$=demo$+"A;1W&HXR&DL$"
a$=INLINE$(demo$)
PRINT  len(a$),a$

'  show  a  bitmap



                                                             78




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC___________________________________________3.20.__DYNAMIC-LINK_LIBRARIES________________



biene$="($$43$%*!(1G,=E5Z&MD%.DVW'b*%H-^,EQ6?VTL$$$$"

CLEARW
t$=INLINE$(biene$)
COLOR  GET.COLOR(65535,65535,65535)
FOR  i=0  TO  40
   PUT.BITMAP  t$,i*16,0,16,16
NEXT  i


     For  convenience,  a  program  called  inline.bas  shippes  with  X11-Basic.   It

does the conversion from and compression of any binary ole to ready-to-use X11-

Basic sourcecode.



3.20         Dynamic-link libraries



A dynamic-link library (.so =shared object) is a collection of functions (subroutines)

that can be used by programs or by other .so's.  A .so function must be called,

directly or indirectly, from a running application and can not be run as a separate

task.

     Dynamic link libraries save memory space and reduce memory swapping. Mem-

ory  is  saved,  because  many  applications  can  use  a  single  .so  simultaneously,

sharing a single copy of the .so in memory.  Another feature of .so's is the ability

to change the functions in a .so without modifying the applications that use them,

as long as the function's arguments and return values do not change. A disadvan-

tage to using .so's is that an application depends on the existence of a separate

.so module. If the .so is not found, the application is terminated.

     All documented functions from the shared objects of other software packages

can be used and invoked from within yout X11-Basic program.

     X11-Basic  will  perform  no  check  on  the  number  and  type  of  the  API  function

parameters.



3.20.1          Using shared libraries and C functions


Before an application can use a function from a .so (if you want to use your own

functions written in C you have to compile them to a shared object ole), it must load

the .so explicitly using the LINK statement.



LINK  #n,"myfile.so"



     The process of loading a .so explicitly is called run-time linking.



                                                             79




3.20.__DYNAMIC-LINK_LIBRARIES__________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



      For  instance,  to  use  the  binit()  function  from  the  trackit.so  library,  an

application must include following lines of code (supposing, you want to use your

own shared object made out of the c-code trackit.c):



IF  NOT  EXIST("./trackit.so")

    SYSTEM  "gcc  -O3  -shared  -o  trackit.so  trackit.c"

ENDIF

LINK  #11,"./trackit.so"

~CALL(SYM.ADR(#11,"binit"),L:n,L:200,P:VARPTR(x(0)),  "

                                                                    P:VARPTR(bins(0)))



     The ole trackit.c contains:



#include  !stdlib.h?

#include  !stdio.h?

#include  !math.h?



void  binit(int  n,int  dn,double  *x,double  *data)  --

    int  i,j;

    int  over=0,under=0;

        for(i=0;i!n;i++)  --

            j=(int)((x[i]+PI)/2/PI*dn);

            if(j!0)  under++;

            else  if(j?=dn)  over++;

            else  data[j]++;

        "

"



     X11-Basic  applications  can  load  up  to  99  shared  object  oles  simultaneously,

although the channel number space is shared with the open oles..

     To do this, parameter n must specify a value between 1 an 99. X11-Basic main-

tains  an  internal  table  with  99  entries  to  store  the  handle  of  the  loaded  shared

object modules.  These handles are necessary to unload the .so when the appli-

cation is onished using them.

     The .so's are unloaded by invoking the UNLINK command:



                                                             80




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC_____________________________________________3.21.__MEMORY_MANAGEMENT___________________



UNLINK  #11


     The CALL() function allows only an integer (int) type for the return value.  To

get a AEoating point return value, use CALLD() instead. If the called function returns

a complicated data structure, use CALL$() instead.

     There is currently a limitation for the use of CALL(), CALLD() and CALL$() on

64bit operating systems.  Here only integer and pointer parameters are correctly

passed  to  the  function  called.   If  you  have  written  the  library  function  yourself,

you could bypass this limitation by passing a pointer to the AEoating point variables

instead (double  *).1

     The following parameter types are possible:

                                  _________________________________________________________
                                  |  D:  |         64-bit AEoat (double)          |
                                  |      |                                        |
                                  |   L:   |      32-bit integer (int) (%)        |
                                  |        |                                      |
                                  |  W:  |         16-bit signed (short)         |
                                  |      |                                       |
                                  |  B:  |          8-bits signed (char)          |
                                  |      |                                        |
                                  |  F:  |           4 byte AEoat (AEoat)           |
                                  |      |                                          |
                                  |  R:  |  8 byte long integer (long long)  |
                                  |      |                                   |
                                  |  P:  |     4 or 8 byte pointer (void *)     |
                                  |______|______________________________________|__________


     The  Option  P:  behaves  the  same  as  L:  on  32bit  operating  systems.  But  you

should use P: for pointers (VARPTR() etc...)  into memory so that it can be trans-

lated  from  X11-Basic  internal  32bit  representation  to  the  64bit  adresses  on  64it

operating systems. The B: and W: options behave the same as the L: option.

     The  SYM.ADR  function  determines  the  address  of  the  function  from  its  name.

The spelling of the function name must therefore be identical to the spelling of the

function in the .so.

     When passing the address of a string, a null byte must be added to the end of

the string.



3.21         Memory management



Normally, X11-Basic takes care of most of the memory management for the pro-

grammer.   When  a  variable,  string  or  array  is  declared,  X11-Basic  allocates  the
__________________________________________________
    1The calling mechanism depends on the Application Binary Interface, which dioeers for dioeerent platforms. Unfor-

tunately the AMD86x64 interface is already that complicated that there is n direct portable way to fully implement it.
The hope is, that an external library could be used in future whch provides a portable way to do it. A good candidate
would be the foreign function interface library libOE.



                                                             81




3.21.__MEMORY_MANAGEMENT_______________________________________CHAPTER_3.__PROGRAMMING_IN_X11-BASIC________________________________*
 *___



required  memory  and  releases  it  when  the  application  is  terminated.   However,

there may be situations when a programmer wants to allocate additional memory.



3.21.1          Allocating memory


If  an  application  needs  to  store  small  amounts  of  memory,  it  should  use  strings.

Strings are often used as a buoeer for functions. The address of the memory occu-

pied by a string can be obtained by the VARPTR() function. Its length by the LEN()

function.

     To allocate memory from the global and system-wide program user space mem-

ory  pool  you  might  use  the  function  MALLOC().   For  instance,  to  allocate  2000

bytes, you might use:



ptr%=MALLOC(2000)



     A global memory block allocated with MALLOC must be freed using the FREE()

function.  An application should always free all memory blocks before exiting.  For

instance:



FREE  ptr%



3.21.2          Shared memory


Memory  which  has  been  allocated  with  MALLOC()  can  only  be  accessed  from

within a single process. If you want two dioeerent X11-Basic instances or in general

two dioeerent running X11-Basic programs access the same memory (e.g. to share

data or to communicate with each other), you need to use shared memory instead.

     The  shared  memory  segment  needs  to  be  created  and  allocated  orst.   This

should  be  done  only  by  one  of  the  programs.  The  creator  will  also  select  a  key

(which is just an integer number) and must be known by all other programs who

want to access this memory later. For example, the key is choosen to be 4711. For

instance, to allocate 2000 bytes, you might use:



id=SHM.MALLOC(2000,4711)



     Unlike MALLOC(),  SHM.MALLOC() does not return an adress directly.  Instead

it returns the identioer of the shared memory segment associated with key.  The



                                                             82




CHAPTER_3.__PROGRAMMING_IN_X11-BASIC_____________________________________________________3.22.__OTHER_FEATURES______________



identioer is also just an integer number. A new shared memory segment is created

if no shared memory segment corresponding to key exists.

     To get an address, which you then can use normally as all other adresses, you

need to involke the function SHM.ATTACH():



adr%=SHM.ATTACH(id)



     Once  the  other  process  knows  the  key  and  the  size  of  the  shared  memory

segment (or at least once it knows its id), it can attach the same segement also to

his address space.  It eventually will get a dioeerent address (adr%) but writing to

the memory and reading from it will now also aoeect all other processes using this

shared segment.

     If not used anymore, the segment should be detached from the adress space

(so  that  adr%  cannot  be  used  anymore)  by  any  of  the  processes  using  it.  If  the

shared memory segment should be removed from memory completely (and all its

contend sould be discarded), the creator of that segment can free it with SHM.FREE.



SHM.DETACH  adr%

SHM.FREE  id



     If  not  freed,  the  segment  resists  in  memory  until  the  operating  system  shuts

down.



3.22         Other features



     #  X11-Basic programs may start other programs with the commands SYSTEM

        and SYSTEM$().

     #  The ENV$() function allows access to environment variables.

     #  The current time or date can be retrieved with TIME$ and DATE$.

     #  The interpreter allows self modifying code.



                                                             83




This chapter describes how to use the graphical user interface (GUI) built into X11-

Basic.


X11-Basic4  Graphical  User  Interface

4.1       ALERT and FILESELECT



Two most often used graphic functions are implemented as a full functional graph-

ical user interface dialog: Message boxes and a ole selector. Arbitrary dialogs can

be created with the object and resource functions. Also a pull down menu function

is implemented.

     Fig. 4.1 shows a typical messagebox. The command which produces it is:



ALERT  3,"This  file  is  write  protected.---You  can  only  read  or  "

                  delete  it.",1,"OK---DELETE---CANCEL",sel


     ALERT boxes can also be used to manage simple input forms like the one you

can see in og. 4.2. Here is a little example program:



CLEARW

i=1

name$="TEST01"

posx$="N54#50'32.3"

posy$="E007#50'32.3"

t$="Edit  waypoint:------Name:      "+CHR$(27)+name$+"---"

t$=t$+"Breite:  "+chr$(27)+posx$+"---"

t$=t$+"L#nge:    "+chr$(27)+posy$+"---"

t$=t$+"H#he:      "+chr$(27)+str$(alt,5,5)+"---"

t$=t$+"Typ:        "+chr$(27)+hex$(styp,4,4)+"---"

ALERT  0,t$,1,"OK---UPDATE---L#SCHEN---CANCEL",a,f$

WHILE  LEN(f$)



             Figure 4.1   : A message box.



                                                             84




CHAPTER_4.__GRAPHICAL_USER_INTERFACE_______________________________________________________________4.2.__RESOURCES__________



                                                                            Figure 4.2  : A simple input box.



    WORT.SEP  f$,CHR$(13),0,a$,f$

    PRINT  "Feld";i;":  ",a$

    INC  i

WEND

QUIT


     Fig. 4.4 shows the oleselector box. The command which produces it is:



FILESELECT  "load  program:","./*.bas","in.bas",f$



     The complete path and olename of the selected ole will be returned in f$.



4.2       Resources



X11-Basic resources consist of object trees, strings, and bitmaps used by a basic

program. They encapsulate the user interface and make internationalization easier

by placing all program strings in a single ole. The data format of X11Basic resource

is downwards compatible with the Atari-ST GEM implementation.

     Resources are generally created using a Resource Construction Set (RCS) and

saved to a .RSC ole which is loaded by RSRC.LOAD() at program initialization time.

     Resources may also be embedded as data structures in source code (the utility

programs  rsc2gui.bas  and  gui2bas.bas  convert  .RSC  oles  to  source  code).

Resources contain pointers and coordinates which must be oxed up before being

used.   RSRC.LOAD()  does  this  automatically,  however  if  you  use  an  embedded

resource you must take care of this by yourself on each object in each object tree

to  convert  the  initial  character  coordinates  of  to  screen  coordinates.  This  allows

resources  designed  on  screens  with  dioeerent  aspect  ratios  and  system  fonts  to

appear the same. Once a resource is loaded use rsrc.gaddr() to obtain pointers



                                                             85




4.2. _RESOURCES_______________________________________________CHAPTER_4.__GRAPHICAL_USER_INTERFACE_________________________________*
 *___



 Figure 4.3  : The oleselecetor



                         Figure 4.4   : A pull down menu



                                                             86




CHAPTER_4.__GRAPHICAL_USER_INTERFACE_______________________________________________________________4.2.__RESOURCES__________



                                    Figure 4.5: Examples of forms in X11-Basic



to individual object trees which can then be manipulated directly or with the X11-

Basic built-in functions.



4.2.1         Objects


Objects can be boxes, buttons, text, images, and more.  An object tree is an array

of OBJECT structures linked to form a structured relationship to each other.  The

object itself is a section of data which can be held by a string in X11-Basic.

     The OBJECT structure is format is as follows:



object$=MKI$(ob.next)+MKI$(ob.head)+MKI$(ob.tail)+

                MKI$(ob.type)+MKI$(ob.flags)+MKI$(ob.state)+

                MKL$(ob.spec)+MKI$(ob.x)+MKI$(ob.y)+MKI$(ob.width)+

                MKI$(ob.height)



     An Object tree is a collection of objects:



tree$=object0$+object1$+  ...  +objectn$



                                                             87




4.2. _RESOURCES_______________________________________________CHAPTER_4.__GRAPHICAL_USER_INTERFACE_________________________________*
 *___



      The  orst  object  in  an  OBJECT  tree  is  called  the  ROOT  object  (OBJECT  0).

It's  coordinates  are  relative  to  the  upper-left  hand  corner  of  the  graphics  win-

dow.   The  ROOT  object  can  have  any  number  of  children  and  each  child  can

have children of their own.  In each case, the OBJECT's coordinates, ob.x, ob.y,

ob.width, and ob.height are relative to that of its parent. The X11-Basic function

objc.offset() can, however, be used to determine the exact screen coordinates

of a child object.  objc.find() is used to determine the object at a given screen

coordinate.

      The  ob.next,  ob.head,  and  ob.tail  oelds  determine  this  relationship  be-

tween parent OBJECTs and child OBJECTs.



ob.next         the index (counting objects from the orst object in the object tree) of the

         object's  next  sibling  at  the  same  level  in  the  object  tree  array.   The  ROOT

         object  should  set  this  value  to  -1.  The  last  child  at  any  given  nesting  level

         should set this to the index of its parent.

ob.head          the  index  of  the  orst  child  of  the  current  object.   If  the  object  has  no

         children then this value should be -1.

ob.tail       the index of the last child:  the tail of the list of the object's children in the

         object tree array If the object has no children then this value should be -1.

ob.type         the  object  type.   The  low  byte  of  the  ob.type  oeld  specioes  the  object

         type as follows:



                ________________________________________________________________________________________________
                |  ob.type        Name                     Description                                |
                |_____________________________________________________________________________________|_________
                |       20        G.BOX                    Box                                             |
                |                                                                                          |
                |       21        G.TEXT                   Formatted Text                            |
                |                                                                                    |
                |       22        G.BOXTEXT                Formatted Text in a Box               |
                |                                                                                |
                |       23        G.IMAGE                  Monochrome Image                     |
                |                                                                               |
                |       24        G.PROGDEF                Programmer-Deoned Object        |
                |                                                                          |
                |       25        G.IBOX                   Invisible Box                                |
                |                                                                                       |
                |       26        G.BUTTON                 Push Button w/String                   |
                |                                                                                 |
                |       27        G.BOXCHAR                Character in a Box                       |
                |                                                                                   |
                |       28        G.STRING                 Un-formatted Text                        |
                |                                                                                   |
                |       29        G.FTEXT                  Editable Formatted Text               |
                |                                                                                |
                |       30        G.FBOXTEXT               Editable Formatted Text in a Box  |
                |                                                                            |
                |       31        G.ICON                   Monochrome Icon                        |
                |                                                                                 |
                |       32        G.TITLE                  Menu Title                                   |
                |                                                                                       |
                |       33        G.CICON                  Color Icon                                   |
                |_______________________________________________________________________________________|_______


                                                             88




CHAPTER_4.__GRAPHICAL_USER_INTERFACE_______________________________________________________________4.2.__RESOURCES__________



ob.AEags        The ob.AEags oeld of the object structure is a bitmask of dioeerent AEags

        that can be applied to any object.  You may want to apply one ore more AEags

        at once. Just add the values ob.AEags.



_____________________________________________________________________________________________________________________________
|  ob.AEags        Name                     Description                                                                    |
|__________________________________________________________________________________________________________________________|__
|        0         NONE                     No AEag                                                                        |
|__________________________________________________________________________________________________________________________|__
|        1         SELECTABLE               object is selected.  state may be toggled by clicking                          |
|                                                                                                                          |
|                                           on it with the mouse.                                                          |
|__________________________________________________________________________________________________________________________|__
|        2         DEFAULT                  An  EXIT  object  with  this  bit  set  will  have  a  thicker                 |
|                                                                                                                          |
|                                           outline and be triggered when the user presses re-                             |
|                                                                                                                          |
|                                           turn.                                                                          |
|__________________________________________________________________________________________________________________________|__
|        4         EXIT                     Clicking on this OBJECT and releasing the mouse                                |
|                                                                                                                          |
|                                           button while still over it will cause the dialog to exit.                      |
|__________________________________________________________________________________________________________________________|__
|        8         EDITABLE                 Set for FTEXT and FBOXTEXT objects to indicate                                 |
|                                                                                                                          |
|                                           that they may receive edit focus.                                              |
|__________________________________________________________________________________________________________________________|__||
|       16         RBUTTON                  This object is one of a group of radio buttons. Click-                         |
|                                                                                                                          |
|                                           ing  on  it  will  deselect  any  selected  objects  at  the                   |
|                                                                                                                          |
|                                           same  tree  level  that  also  have  the  RBUTTON  AEag                        |
|                                                                                                                          |
|                                           set.   Likewise,  it  will  be  deselected  automatically                      |
|                                                                                                                          |
|                                           when any other object is selected.                                             |
|__________________________________________________________________________________________________________________________|__
|       32         LASTOB                   This AEag signals that the current OBJECT is the last                          |
|                                                                                                                          |
|                                           in the object tree. (Required!)                                                |
|__________________________________________________________________________________________________________________________|__
|       64         TOUCHEXIT                Setting  this  AEag  causes  the  OBJECT  to  return  an                       |
|                                                                                                                          |
|                                           exit state immediately after being clicked on with the                         |
|                                                                                                                          |
|                                           mouse.                                                                         |
|__________________________________________________________________________________________________________________________|__
|      256         HIDETREE                 This  OBJECT  and  all  of  its  children  will  not  be                       |
|                                                                                                                          |
|                                           drawn.                                                                         |
|__________________________________________________________________________________________________________________________|__
|      512         INDIRECT                 This AEag cause the ob.spec oeld to be interpreted                             |
|                                                                                                                          |
|                                           as  a  pointer  to  the  ob.spec  value  rather  than  the                     |
|                                                                                                                          |
|                                           value itself.                                                                  |
|__________________________________________________________________________________________________________________________|__
|     1024         FL3DIND                  Setting  this  AEag  causes  the  OBJECT  to  be  drawn                        |
|                                                                                                                          |
|                                           as a 3D indicator.  This is appropriate for radio and                          |
|                                                                                                                          |
|                                           toggle buttons.                                                                |
|__________________________________________________________________________________________________________________________|__
|     2048         FL3DACT                  Setting this AEag causes the OBJECT to be drawn as                             |
|                                                                                                                          |
|                                           a 3D activator. This is appropriate for EXIT buttons.                          |
|__________________________________________________________________________________________________________________________|_

                                                             89




4.2. _RESOURCES_______________________________________________CHAPTER_4.__GRAPHICAL_USER_INTERFACE_________________________________*
 *___



     ______________________________________________________________________________________________________________________________*
 *__||
     |||||     3072 FL3DBAK                  If these bits are set, the object is treated as an AES                         |
     |||||                                                                                                                  |
     |||||                                   background object.  If it is OUTLINED, the outlined                            |
     |||||                                                                                                                  |
     |||||                                   is drawn in a 3D manner. If its color is set to WHITE                          |
     |||||                                                                                                                  |
     |||||                                   and its oll pattern is set to 0 then the OBJECT will                           |
     |||||                                                                                                                  |
     |||||                                   inherit the default 3D background color.                                       |
     |||||__________________________________________________________________________________________________________________|______*
 *___||
     |||||     4096 SUBMENU                  This  bit  is  set  on  menu  items  which  have  a  sub-                      |
     |||||                                                                                                                  |
     |||||                                   menu  attachment.   This  bit  also  indicates  that  the                      |
     |||||                                                                                                                  |
     |||||                                   high byte of the ob.type oeld is being used by the                             |
     |||||                                                                                                                  |
     |||||                                   menu system.                                                                   |
     |||||__________________________________________________________________________________________________________________|______*
 *___



ob.state         The ob.state oeld determines the display state of the object as follows:



     ______________________________________________________________________________________________________________________________
     ||||  ob.state  Name                    Description                                                                    |
     ||||___________________________________________________________________________________________________________________|______
     ||||        0   NORMAL                  Normal state                                                                   |
     ||||___________________________________________________________________________________________________________________|______
     ||||        1   SELECTED                The  object  is  selected.   An  object  with  this  bit  set                  |
     ||||                                                                                                                   |
     ||||                                    will be drawn in inverse video except for G.CICON                              |
     ||||                                                                                                                   |
     ||||                                    which will use its 'selected' image.                                           |
     ||||___________________________________________________________________________________________________________________|______
     ||||        2   CROSSED                 An OBJECT with this bit set will be drawn over with                            |
     ||||                                                                                                                   |
     ||||                                    a  white  cross  (this  state  can  only  usually  be  seen                    |
     ||||                                                                                                                   |
     ||||                                    over a colored or SELECTED object).                                            |
     ||||___________________________________________________________________________________________________________________|______
     ||||        4   CHECKED                 An OBJECT with this bit set will be displayed with a                           |
     ||||                                                                                                                   |
     ||||                                    check mark in its upper-left corner.                                           |
     ||||___________________________________________________________________________________________________________________|______
     ||||        8   DISABLED                An OBJECT with this bit set will ignore user input.                            |
     ||||                                                                                                                   |
     ||||                                    Text  objects  with  this  bit  set  will  draw  in  grey  or  a               |
     ||||                                                                                                                   |
     ||||                                    dithered pattern.                                                              |
     ||||___________________________________________________________________________________________________________________|______
     ||||       16   OUTLINED                G.BOX,   G.IBOX,   G.BOXTEXT,   G.FBOXTEXT,                                    |
     ||||                                                                                                                   |
     ||||                                    and G.BOXCHAR OBJECTs with this bit set will be                                |
     ||||                                                                                                                   |
     ||||                                    drawn with a double border.                                                    |
     ||||___________________________________________________________________________________________________________________|______
     ||||       32   SHADOWED                G.BOX,   G.IBOX,   G.BOXTEXT,   G.FBOXTEXT,                                    |
     ||||                                                                                                                   |
     ||||                                    and  G.BOXCHAR  OBJECTs  will  be  drawn  with  a                              |
     ||||                                                                                                                   |
     ||||                                    shadow.                                                                        |
     ||||___________________________________________________________________________________________________________________|______



ob.spec         The object-specioc oeld



                                                             90




CHAPTER_4.__GRAPHICAL_USER_INTERFACE_______________________________________________________________4.2.__RESOURCES__________



        The  ob.spec  oeld  contains  dioeerent  data  depending  on  the  object  type  as

        indicated in the table below:


         ____________________________________________________________________________________________________________||
         |  G.BOX                   The  low  16  bits  contain  a  WORD  containing  color                        |
         |                                                                                                         |
         |                          information  for  the  OBJECT.  Bits  23-16  contain  a                        |
         |                                                                                                         |
         |                          signed  BYTE  representing  the  border  thickness  of                         |
         |                                                                                                         |
         |                          the box.                                                                       |
         |_________________________________________________________________________________________________________|__
         |  G.TEXT                  The ob.spec oeld contains a pointer to a TEDINFO                               |
         |                                                                                                         |
         |                          structure.                                                                     |
         |_________________________________________________________________________________________________________|__
         |  G.BOXTEXT               The ob.spec oeld contains a pointer to a TEDINFO                               |
         |                                                                                                         |
         |                          structure.                                                                     |
         |_________________________________________________________________________________________________________|__
         |  G.IMAGE                 The ob.spec oeld points to a BITBLK structure.                                 |
         |_________________________________________________________________________________________________________|__
         |  G.PROGDEF               The ob.spec oeld points to a APPLBLK structure.                                |
         |_________________________________________________________________________________________________________|__||
         |  G.IBOX                  The  low  16  bits  contain  a  WORD  containing  color                        |
         |                                                                                                         |
         |                          information  for  the  OBJECT.  Bits  23-16  contain  a                        |
         |                                                                                                         |
         |                          signed  BYTE  representing  the  border  thickness  of                         |
         |                                                                                                         |
         |                          the box.                                                                       |
         |_________________________________________________________________________________________________________|__
         |  G.BUTTON                The ob.spec oeld contains a pointer to the text to                             |
         |                                                                                                         |
         |                          be contained in the button.                                                    |
         |_________________________________________________________________________________________________________|__||
         |  G.BOXCHAR               The  low  16  bits  contain  a  WORD  containing  color                        |
         |                                                                                                         |
         |                          information  for  the  OBJECT.  Bits  23-16  contain  a                        |
         |                                                                                                         |
         |                          signed  BYTE  representing  the  border  thickness  of                         |
         |                                                                                                         |
         |                          the box.  Bits 31-24 contain the ASCII value of the                            |
         |                                                                                                         |
         |                          character to display.                                                          |
         |_________________________________________________________________________________________________________|__
         |  G.STRING                The ob.spec oeld contains a pointer to the text to                             |
         |                                                                                                         |
         |                          be displayed.                                                                  |
         |_________________________________________________________________________________________________________|__
         |  G.FTEXT                 The ob.spec oeld contains a pointer to a TEDINFO                               |
         |                                                                                                         |
         |                          structure.                                                                     |
         |_________________________________________________________________________________________________________|__
         |  G.FBOXTEXT              The ob.spec oeld contains a pointer to a TEDINFO                               |
         |                                                                                                         |
         |                          structure.                                                                     |
         |_________________________________________________________________________________________________________|__
         |  G.ICON                  The  ob.spec  oeld  contains  a  pointer  to  an  ICON-                        |
         |                                                                                                         |
         |                          BLK structure.                                                                 |
         |_________________________________________________________________________________________________________|__
         |  G.TITLE                 The ob.spec oeld contains a pointer to the text to                             |
         |                                                                                                         |
         |                          be used for the title.                                                         |
         |_________________________________________________________________________________________________________|__
         |  G.CICON                 The  ob.spec  oeld  contains  a  pointer  to  a  CICON-                        |
         |                                                                                                         |
         |                          BLK structure.                                                                 |
         |_________________________________________________________________________________________________________|__



                                                             91




4.2. _RESOURCES_______________________________________________CHAPTER_4.__GRAPHICAL_USER_INTERFACE_________________________________*
 *___



         objc.colorword             Almost all objects reference a WORD containing the object

                color as deoned below.



                objc.colorword=bbbbcccctpppcccc



                Bits  15-12  contain  the  border  color

                Bits  11-8    contain  the  text  color

                Bit      7        is  1  if  opaque  or  0  if  transparent

                Bits  6-4      contain  the  fill  pattern  index

                Bits  3-0      contain  the  fill  color



                Available colors for oll patterns, text, and borders are listed below:
                                         ____________________________________________________________
                                         |  Value      Name                  Color               |
                                         |_______________________________________________________|___
                                         |     0       WHITE                 White               |
                                         |                                                       |
                                         |     1       BLACK                 Black               |
                                         |                                                       |
                                         |     2       RED                   Red                 |
                                         |                                                       |
                                         |     3       GREEN                 Green              |
                                         |                                                      |
                                         |     4       BLUE                  Blue                 |
                                         |                                                        |
                                         |     5       CYAN                  Cyan                |
                                         |                                                       |
                                         |     6       YELLOW                Yellow              |
                                         |                                                       |
                                         |     7       MAGENTA               Magenta          |
                                         |                                                    |
                                         |     8       LWHITE                Light Gray        |
                                         |                                                     |
                                         |     9       LBLACK                Dark Gray        |
                                         |                                                    |
                                         |    10       LRED                  Light Red         |
                                         |                                                     |
                                         |    11       LGREEN                Light Green      |
                                         |                                                    |
                                         |    12       LBLUE                 Light Blue        |
                                         |                                                     |
                                         |    13       LCYAN                 Light Cyan       |
                                         |                                                    |
                                         |    14       LYELLOW               Light Yellow      |
                                         |                                                     |
                                         |    15       LMAGENTA              Light Magenta  |
                                         |__________________________________________________|________

         TEDINFO          G.TEXT, G.BOXTEXT, G.FTEXT, and G.FBOXTEXT objects all
                reference  a  TEDINFO  structure  in  their  ob.spec  oeld.   The  TEDINFO
                structure is deoned below:

                tedinfo$=MKL$(VARPTR(te.ptext$))+MKL$(VARPTR(te.ptmplt$))+
                             MKL$(VARPTR(te.pvalid$))+MKI$(te.font)+MKI$(te.fontid)+
                             MKI$(te.just)+MKI$(te.color)+MKI$(te.fontsize)+
                             MKI$(te.thickness)+MKI$(te.txtlen)+MKI$(te.tmplen)



                                                             92




CHAPTER_4.__GRAPHICAL_USER_INTERFACE_______________________________________________________________4.2.__RESOURCES__________



               The  three  character  pointers  point  to  text  strings  required  for  G.FTEXT

               and  G.FBOXTEXT  objects.   te.ptext  points  to  the  actual  text  to  be  dis-

               played and is the only oeld used by all text objects.  te.ptmplt points to

               the  text  template  for  editable  oelds.   For  each  character  that  the  user

               can  enter,  the  text  string  should  contain  a  tilde  character  (ASCII  126).

               Other  characters  are  displayed  but  cannot  be  overwritten  by  the  user.

               te.pvalid  contains  validation  characters  for  each  character  the  user

               may enter. The current acceptable validation characters are:



               Char    Allows

               9          Digits 0-9

               A         Uppercase letters A-Z plus space

               a          Upper and lowercase letters plus space

               N         Digits 0-9, uppercase letters A-Z and space

               n          Digits 0-9, upper and lowercase letters A-Z and space

               F          Valid DOS olename characters plus question mark and asterisk

               P         Valid DOS pathname characters, backslash, colon,

                          question mark, asterisk

               p          Valid DOS pathname characters, backslash and colon

               X         All characters



               te.font may be set to any of the following values:
                          _______________________________________________________________________________________
                          |  te.font       Name          Description                                     |
                          |______________________________________________________________________________|_______
                          |       3        IBM           Use the standard monospaced font.  |
                          |                                                                 |
                          |       5        SMALL         Use the small monospaced font.       |
                          |___________________________________________________________________|__________________

               te.just sets the justiocation of the text output as follows:
                                         _________________________________________________________
                                         |  te.just      Name                 Description  |
                                         |_________________________________________________|______
                                         |      0        TE.LEFT              Left Justify    |
                                         |                                                    |
                                         |      1        TE.RIGHT             Right Justify  |
                                         |                                                   |
                                         |      2        TE.CNTR              Center          |
                                         |____________________________________________________|___

               te.thickness sets the border thickness (positive and negative values are

               acceptable) of the G.BOXTEXT or G.FBOXTEXT object.

               te.txtlen  and  te.tmplen  should  be  set  to  the  length  of  the  starting  text

               and template length respectively.



                                                             93




4.2. _RESOURCES_______________________________________________CHAPTER_4.__GRAPHICAL_USER_INTERFACE_________________________________*
 *___



         BITBLK        G.IMAGE  objects  contain  a  pointer  to  a  BITBLK  structure  in  their

                ob.spec oeld. The BITBLK structure is deoned as follows:


                bitblk$=MKL$(VARPTR(bi.pdata$))+MKI$(bi.wb)+MKI$(bi.hl)+
                           MKI$(bi.x)+MKI$(bi.y)+MKI$(bi.color)


                bi.pdata should contain a monochrome bit image. bi.wb specioes the

                width (in bytes) of the image. All BITBLK images must be a multiple of 16

                pixels wide therefore this value must be even. bi.hl specioes the height

                of the image in scan lines (rows). bi.x and bi.y are used as ooesets into

                bi.pdata. Any data occurring before these coordinates will be ignored.

                bi.color  is  a  standard  color  WORD  where  the  oll  color  specioes  the

                color in which the image will be rendered.

         ICONBLK          The ob.spec oeld of G.ICON objects point to an ICONBLK struc-

                ture as deoned below:


                iconblk$=MKL$(VARPTR(ib.pmask$))+MKL$(VARPTR(ib.pdata$))+MKL$(VARPTR(ib.ptext$))+
                             MKI$(ib.char)+MKI$(ib.xchar)+MKI$(ib.ychar)+
                             MKI$(ib.xicon)+MKI$(ib.yicon)+MKI$(ib.wicon)+MKI$(ib.hicon)+
                 MKI$(ib.xtext)+MKI$(ib.ytext)+MKI$(ib.wtext)+MKI$(ib.htext)


                ib.pmask  and  ib.pdata  contain  the  monochrome  mask  and  image

                data respectively. ib.ptext is a string pointer to the icon text. ib.char

                deones the icon character (used for drive icons) and the icon foreground

                and background color as follows:


                ---                                          ib.char                                           ---
                ---         Bits  15-12         ---         Bits  11-8          ---          Bits  7-0          ---
                ---Icon  Foreground  Color  ---Icon  Background  Color  ---ASCII  Character  (or  0  ---
                ---                               ---                               ---   for  no  character).   ---


                ib.xchar and ib.ychar specify the location of the icon character rela-

                tive to ib.xicon and ib.yicon.  ib.xicon and ib.yicon specify the

                location of the icon relative to the ob.x and ob.y of the object. ib.wicon

                and  ib.hicon  specify  the  width  and  height  of  the  icon  in  pixels.   As

                with images,  icons must be a multiple of 16 pixels in width.  ib.xtext

                and ib.ytext specify the location of the text string relative to the ob.x

                and ob.y of the object.  ib.wtext and ib.htext specify the width and

                height of the icon text area.

         CICONBLK            The G.CICON object deones its ob.spec oeld to be a pointer to

                a CICONBLK structure as deoned below:


                ciconblk$=monoblk$+MKL$(VARPTR(mainlist$))



                                                             94




CHAPTER_4.__GRAPHICAL_USER_INTERFACE_______________________________________________________________4.2.__RESOURCES__________



               monoblk contains a monochrome icon which is rendered if a color icon

               matching the display parameters cannot be found.  In addition, the icon

               text,  character,  size,  and  positioning  data  from  the  monochrome  icon

               are always used for the color one.  mainlist contains the orst CICON

               structure in a linked list of color icons for dioeerent resolutions.  CICON is

               deoned as follows:


               cicon$=MKI$(num.planes)+MKL$(VARPTR(col.data$))+MKL$(VARPTR(col.mask$))+
                         MKL$(VARPTR(sel.data$))+MKL$(VARPTR(sel.mask$))+
                         MKL$(VARPTR(cicon2$))


               num.planes indicates the number of bit planes this color icon contains.

               col.data and col.mask contain the icon data and mask for the unse-

               lected icon respectively.  Likewise, sel.data and sel.mask contain the

               icon  data  and  mask  for  the  selected  icon.   cicon2$  contains  the  next

               color icon deonition. Use MKL$(0) if no more are available.

               The GUI library searches the CICONBLK object for a color icon that has

               the  same  number  of  planes  in  the  display.   If  none  is  found,  the  GUI

               library simply uses the monochrome icon.

        APPLBLK           G.PROGDEF objects allow programmers to deone custom objects

               and link them transparently in the resource. The ob.spec oeld of G.PROGDEF

               objects contains a pointer to an APPLBLK as deoned below:


               applblk$=MKL$(SYM.ADR(#1,"function"))+MKL$(ap.parm)


               The  orst  is  a  pointer  to  a  user-deoned  routine  which  will  draw  the  ob-

               ject.  This routine must be a c-Function, which has to be linked to X11-

               basic with the LINK command.  The routine will be passed a pointer to

               a PARMBLK structure containing the information it needs to render the

               object. The routine must be deoned with stack checking ooe and expect to

               be passed its parameter on the stack.  ap.parm is a user-deoned value

               which is copied into the PARMBLK structure as deoned below:


               typedef  struct  parm.blk  --
                          OBJECT              *tree;
                          short                 pb.obj;
                          short                 pb.prevstate;
                          short                 pb.currstate;
                          short                 pb.x;
                          short                 pb.y;
                          short                 pb.w;
                          short                 pb.h;
                          short                 pb.xc;



                                                             95




4.2. _RESOURCES_______________________________________________CHAPTER_4.__GRAPHICAL_USER_INTERFACE_________________________________*
 *___



                           short                 pb.yc;
                           short                 pb.wc;
                           short                 pb.hc;
                           long                  pb.parm;
                "  PARMBLK;


                tree points to the OBJECT tree of the object being drawn. The object is

                located at index pb.obj.

                The routine is passed the old ob.state of the object in pb.prevstate

                and the new ob.state of the object in pb.currstate. If pb.prevstate

                and pb.currstate is equal then the object should be drawn completely,

                otherwise only the drawing necessary to redraw the object from pb.prevstate

                to pb.currstate are necessary.

                pb.x, pb.y, pb.w, and pb.h give the screen coordinates of the object.

                pb.xc, pb.yc, pb.wc, and pb.hc give the rectangle to clip to.  pb.parm

                contains  a  copy  of  the  ap.parm  value  in  the  APPLBLK  structure.  The

                custom routine should return a short containing any remaining ob.state

                bits you wish the GUI Library to draw over your custom object.



Dialogs


Dialog boxes are modal forms of user input.  This means that no other interaction

can occur between the user and applications until the requirements of the dialog

have been met and it is exited. A normal dialog box consists of an object tree with

a BOX as its root object and any number of other controls that accept user input.

Both alert boxes and the ole selector are examples of dialog boxes.

     The form.do() function performs the simplest method of using a dialog box.

Simply construct an OBJECT tree with at least one EXIT or TOUCHEXIT object

and call form.do()1 .  All interaction with the dialog like editable oelds, radio but-

tons,  and selectable objects will be maintained by the X11-Basic library until the

user strikes an EXIT or TOUCHEXIT object.



4.2.2         The gui ole format


The *.gui ole format,  which is basically an ASCII representation of the ATARI ST

resource oles (*.rsc), can be converted to X11-Basic code, which then can handle
     _______________________________________________________
    1Before you should display the dialog box using the objc.draw() function. Maybe you also want to center the

dialog with form.center() and save and redraw the background with form.dial().



                                                             96




CHAPTER_4.__GRAPHICAL_USER_INTERFACE_______________________________________________________________4.2.__RESOURCES__________



message boxes and forms.  The converter gui2bas(1) does this job.  For conver-

sion of ATARI ST resource oles to *.gui Files see rsc2gui(1).

     The *.gui ole consists of Lines and Blocks which specify objects and their hier-

archical dependencies. The generic format of such an object is:



label:  TYPE(variables)  --

  ...  block  ...

"



     The label is optional and gives the object a name.  Depending on TYPE of the

object, one or more variables are given as a comma separated list in brackets.

     Each object may start a block with '--' at the end of the line. Inside this block there

might be one or more objects given which then are considered as sub-objects of

the one which opened the block. The block will be closed by a '"' in a single line.



Example:


'  Little  selector  box   (c)  Markus  Hoffmann      07.2003
'  convert  this  with  gui2bas  !
'  as  an  example  for  the  use  of  the  gui  system
'  with  X11-Basic

BOX(X=0,Y=0,W=74,H=14,  FRAME=2,  FRAMECOL=1,  TEXTCOL=1,  BGCOL=0,  PATTERN=0,  TEXTMODE=0,
      STATE=OUTLINED+)  --
   BOXTEXT(X=2,Y=1,W=70,H=1,  TEXT="Select  option  ...",  FONT=3,  JUST=2,  COLOR=4513,
              BORDER=253,  STATE=SHADOWED+)
   BOX(X=2,Y=3,W=60,H=10,  FRAME=-1,  FRAMECOL=1,  TEXTCOL=1,  BGCOL=0,  PATTERN=0,
         TEXTMODE=0)  --
      FTEXT(X=1,Y=1,W=30,H=1,COLOR=4513,FONT=3,BORDER=1,TEXT="Line  1",
              PTMP=".......................................",
              PVALID="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",  FLAGS=EDITABLE)
      FTEXT(X=1,Y=2,W=30,H=1,COLOR=4513,FONT=3,BORDER=1,TEXT="",
              PTMP=".......................................",
              PVALID="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",  FLAGS=EDITABLE)
      FTEXT(X=1,Y=3,W=30,H=1,COLOR=4513,FONT=3,BORDER=1,TEXT="",
              PTMP=".......................................",
              PVALID="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",  FLAGS=EDITABLE)
      FTEXT(X=1,Y=4,W=30,H=1,COLOR=4513,FONT=3,BORDER=1,TEXT="",
              PTMP=".......................................",
              PVALID="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",  FLAGS=EDITABLE)
      BOX(X=2,Y=6,W=50,H=3,  FRAME=-1,  FRAMECOL=1,  TEXTCOL=1,  BGCOL=1,  PATTERN=5,
              TEXTMODE=0)  --
         BUTTON(X=2,Y=1,W=4,H=1,  TEXT="ON",STATE=SELECTED,
                  FLAGS=RADIOBUTTON+SELECTABLE,FRAME=2,  FRAMECOL=1,  TEXTCOL=1,
                  BGCOL=1,  PATTERN=0,  TEXTMODE=0)
         BUTTON(X=8,Y=1,W=4,H=1,  TEXT="OFF",FLAGS=RADIOBUTTON+SELECTABLE,FRAME=2,
                  FRAMECOL=1,  TEXTCOL=1,  BGCOL=1,  PATTERN=0,  TEXTMODE=0)
      "
   "



                                                             97




4.3. _MENUS___________________________________________________CHAPTER_4.__GRAPHICAL_USER_INTERFACE_________________________________*
 *___



   ok:    BUTTON(X=65,Y=4,W=7,H=4,  TEXT="OK",  FLAGS=SELECTABLE+DEFAULT+EXIT)
   cancel:  BUTTON(X=65,Y=9,W=7,H=4,  TEXT="CANCEL",  FLAGS=SELECTABLE+EXIT+LASTOB+)
"



4.3       Menus



Most applications use a menu bar to allow the user to navigate through program

options.

     Here is a simple example program, which demonstrates the handling of a drop

down menu.



'  Test-program  for  Drop-Down-Menus
'
DIM  field$(50)
FOR  i=0  TO  50
   READ  field$(i)
   EXIT  IF  field$(i)="***"
NEXT  i
oh=0
field$(i)=""
DATA  "INFO","   Menutest"
DATA  "---------------"
DATA  "-  Access.1","-  Access.2","-  Access.3","-  Access.4","-  Access.5"
DATA  "-  Access.6",""
DATA  "FILE","   new","   open  ...","   save","   save  as  ...","--------------"
DATA  "   print","--------------","   Quit",""
DATA  "EDIT","   cut","   copy","   paste","----------","   help1","   helper"
DATA  "   assist",""
DATA  "HELP","   online  help","--------------","   edifac","   editor","   edilink"
DATA  "   edouard",""
DATA  "***"

grau=GET.COLOR(32000,32000,32000)
COLOR  grau
PBOX  0,0,640,400
MENUDEF  field$(),menuaction
DO
   PAUSE  0.05
   MENU
LOOP
QUIT

PROCEDURE  menuaction(k)
   LOCAL  b
   IF  (field$(k)="   Quit")  OR  (field$(k)="   exit")
      QUIT
   ELSE  IF  field$(k)="   online  help"
      oh=not  oh
      MENUSET  k,4*abs(oh)
   ELSE  IF  field$(k)="   Menutest"
      ~FORM.ALERT(1,"[0][-  Menutest  -------(c)  Markus  Hoffmann  2001---X11-Basic  V.1.03][  OK  ]")
   ELSE
      PRINT  "MENU  selected  ";k;"  contents:  ";field$(k)
      b=FORM.ALERT(1,"[1][---  Menutest  ---------You  selected  item  (No.  "+str$(k)+  "
                           "),---  for  which  was  no---function  defined  !][  OK  ---disable]")



                                                             98




CHAPTER_4.__GRAPHICAL_USER_INTERFACE_______________________________________________________________________4.3.__MENUS______



      IF  b=2
         MENUSET  k,8
      ENDIF
   ENDIF
RETURN



                                                             99




5.1       Reserved variable names



X11-Basic5ThQuickerreferencee  are  some  reserved  variables.   Some  Keywords  may  not  work  as  variable
names  as  well.  Although  there  is  no  checking  done,  parsing  errors  could  occur.

Please try the command LET in such cases. In general, as long as an ending of a

variable name is dioeerent from any command or keyword, it's usable as name.

     Reserved and system variables are:



        int    ANDROID?                     -1 on Android systems, else 0                                   p.141

        int    COLS                         number of columns of the text terminal                          p.201

        int    CRSCOL                       text cursor position: current column                            p.212

        int    CRSLIN                       text cursor position: current line                              p.212

        AEt    CTIMER                       CPU system timer (seconds)                                      p.213

        int    ERR                          number of the last error                                        p.264

        int    FALSE                        constant: 0                                                     p.285

        int    GPS?                         TRUE if GPS is available, else 0                                p.337

        AEt    GPS.ALT                      Altitude in m received from GPS                                 p.338

        AEt    GPS.LAT                      latitude in degrees received from GPS                           p.338

        AEt    GPS.LON                      longitude in degrees received from GPS                          p.339

        int    MOUSEK                       mouse button state                                              p.427

        int    MOUSES                       state of the shift, alt, ctrl, caps keys                        p.427

        int    MOUSEX                       x coordinate of mouse position                                  p.427

        int    MOUSEY                       y coordinate of mouse position                                  p.427

        int    PC                           program counter                                                 p.467

        AEt    PI                           constant: 3.14159265359...                                      p.471

        int    ROWS                         number of rows of the text terminal                             p.542

        int    SENSOR?                      TRUE if sensor phalanx is available                             p.560

        int    SP                           internal stack pointer                                          p.589

        int    STIMER                       integer system timer                                            p.598

        AEt    TIMER                        Unix system timer, AEoat                                        p.619

        int    TRUE                         constant: -1                                                    p.627

        int    UNIX?                        TRUE if OS is UNIX like (Linux, BSD)                            p.634

        int    WIN32?                       TRUE if OS is MS WINDOWS 32 bit                                 p.660

               DATE$                        current date                                                    p.221



                                                            100




CHAPTER_5.__QUICK_REFERENCE________________________________________________________________________5.2.__CONDITIONS_________



               FILEEVENT$                  get events about oles                                           p.290

               INKEY$                      content of the keyboard-buoeer                                  p.357

               TERMINALNAME$               device name of the standard terminal                            p.616

               TIME$                       current time                                                    p.618

               TRACE$                      current program code line                                       p.623



5.2       Conditions



Conditions and expression are the same, FALSE is deoned as 0 and TRUE as -1. As

a consequence, Boolean operators like AND, OR, XOR etc.  are applied as a bitwise

operation. This way they can be used in expressions as well as in conditions.



5.3       Numbers and Constants



Number constants may precede 0x to represent hex values.  String constants are

marked with pairs of "". Array constants have following format: [  ,  ,  ;  ,  ,  ;  ,  ,  ].



5.4       Operators



Precedence is deoned as follows (highest orst):



0. ()                                             (brackets)

1. ^                                               (power)

2. *  /                                           (multiplication, division)

3. "                                               (modulo)

4. -  +                                           ()

5. MOD  DIV                                   (modulus, ...)        p.421,240

6. !  ?  =  !?  !=  ?=                      (comparison operators)

7. AND  OR  XOR  NOT  EQV  IMP      (logical operators)p.140,461, 444,262,354



                                                            101




5.5. _ABBREVIATIONS__________________________________________________________CHAPTER_5.__QUICK_REFERENCE___________________________*
 *___



5.5        Abbreviations



In direct mode in the interpreter every command can be abbreviated as long as the

command parser can identify uniquely the command. So you may use q instead of

QUIT.

     In addition there are abbreviations which are actually alternate commands like:

                              ________________________________________________________________
                              |  '   REM                                            p.521  |
                              |                                                            |
                              |  ?   PRINT                                          p.489  |
                              |                                                            |
                              |  @   GOSUB                                          p.328  |
                              |                                                            |
                              |  ~   VOID                                           p.651  |
                              |                                                            |
                              |  !   comment at the end of a line                             |
                              |                                                               |
                              |  &   EVAL / indirect command                        p.267  |
                              |____________________________________________________________|__



5.6       Interpreter Commands



CLEAR                             clear and remove all variables                            p.192

CONT                               continue (after STOP)                                        p.206

DUMP                               lists all used variable names                               p.246

DUMP  "@"                        list of functions and procedures                          p.246

DUMP  ":"                        list of all labels                                                   p.246

DUMP  "#"                        list of open oles                                                  p.246

DUMP  "K"                        list of implemented commands                           p.246

DUMP  "F"                        list of internal functions                                      p.246

ECHO  ON/OFF                  same as TRON * TROFF                                   p.248

EDIT                               call default editor to edit program                        p.249

HELP  !expr?                  prints short help on expr                                     p.345

LIST  [s,e]                    List program code (from line s to e)                    p.388

LOAD  file$                    load program                                                     p.390

NEW                                 clear all variables, erase program and stop         p.437

PLIST                             formatted listing                                                 p.475

PROGRAM options              set title and compiler options                              p.496

QUIT                               quits the X11-BASIC-Interpreter                         p.504

REM comment                  remark in program                                             p.521

RUN                                 start program                                                     p.545

STOP                               stop program                                                     p.599



                                                            102




CHAPTER_5.__QUICK_REFERENCE_________________________________________________5.7.__FLOW_CONTROL_COMMANDS_____________________



SAVE  [file$]                writes the BASIC-program into ole                      p.547

TROFF                             Trace mode ooe                                                   p.625

TRON                               Trace mode on (for debugging)                           p.626

VERSION                          shows X11-Basic version number and date        p.650

XLOAD                             select and load a program                                  p.666

XRUN                               select, load and run a program                           p.669



5.7       Flow Control Commands



AFTER  n,procedure           execute procedure after n seconds                     p.135

BREAK                                  same as EXIT IF TRUE                                      p.167

CASE  const                        SELECT * CASE * DEFAULT * ENDSELECT      p.181

CHAIN  bas$                        executes another basic program                         p.184

CONTINUE                            SELECT * CASE * CONTINUE * ENDSELECT   p.206

DEFAULT                              SELECT * CASE * DEFAULT * ENDSELECT      p.225

DEFFN                                  deone function macro.                                        p.227

DO  *  LOOP                          (endless) loop without condition                         p.241

DOWNTO                                FOR ... DOWNTO                                              p.242

ELSE                                    see IF * ELSE * ENDIF                                      p.251

ELSE  IF                              see IF * ELSE * ENDIF                                      p.251

END                                      program end, enter interactive mode                  p.255

ENDFUNCTION                      FUNCTION * ENDFUNCTION                            p.256

ENDIF                                  IF * ELSE * ENDIF                                             p.257

ENDSELECT                          SELECT * CASE * DEFAULT * ENDSELECT      p.259

EVERY  n,procedure           invokes procedure every n seconds                    p.273

EXIT  IF  a                          exit loop if condition a is TRUE                           p.280

FOR  *  NEXT                        For Next loop                                                     p.299

FUNCTION  *  ENDFUNC         deone function                                                   p.314

GOSUB  proc(...)               call subroutine                                                   p.328

GOTO  label                        goto label                                                           p.329

IF  *  ELSE  *  ENDIF           conditional blocks                                              p.352

LOOP                                    DO * LOOP                                                        p.398

NEXT                                    FOR * NEXT                                                      p.438

ON  BREAK  GOSUB  proc       deone procedure on break                                 p.454



                                                            103




5.8. _CONSOLE_INPUT/OUTPUT_COMMANDS__________________________________________CHAPTER_5.__QUICK_REFERENCE___________________________*
 *___



ON  ERROR  GOSUB  proc       deone procedure on error                                   p.454

ON  *  GOSUB  proc1,...     excecute subroutine depending on value            p.453

ON  *  GOTO  label1,...     branch to dioeerent labels depending on value     p.453

REPEAT                                REPEAT * UNTIL                                               p.523

RESUME                                resume program after error                                p.526

RETURN                                deone the end of a PROCEDURE                      p.528

SELECT  expr                      SELECT * CASE * DEFAULT * ENDSELECT      p.555

UNTIL  exp                          REPEAT * UNTIL                                               p.638

SPAWN  procedure               Spawn new thread                                             p.591



5.8       Console Input/Output Commands



BEEP                                    Beep (on TTY/console)                                      p.159

BELL                                    same as BEEP                                                  p.159

CLS                                      clear (text)screen                                               p.198

FLUSH                                  AEush output                                                        p.298

HOME                                    textcursor home                                                 p.349

INPUT  "text";varlist     read values for variables                                    p.362

LINEINPUT  t$                    read entire line from channel/ole/console            p.385

LOCATE  row,column           Place cursor on column and row                         p.393

PRINT  a;b$                        console output                                                   p.489

PRINT  AT(x,y);                locate textcursor at row y and column x              p.490

PRINT  COLOR(x,y);           change text color                                               p.491

PRINT  TAB(x);                  locate textcursor at column x                              p.??

PRINT  SPC(x);                  move textcursor x columns                                 p.??

PRINT  a  USING  f$             print number with formatter                                p.493

PUTBACK  a                          put back a char to console                                 p.501



5.9       File Input/Output Commands



BGET  #f,a,n                      read n bytes from ole #f to address a                  p.160

BLOAD  f$,a[,l]                reads entire ole (given by name) to address a     p.162



                                                            104




CHAPTER_5.__QUICK_REFERENCE__________________________________5.10.__VARIABLE_MANIPULATION_COMMANDS__________________________



BPUT  #f,a,n                      writes n bytes from address a to ole/channel f     p.166

BSAVE  f$,a,l                    saves l bytes in memory at address a to ole f$    p.169

CHDIR  path$                      change current working directory                        p.185

CHMOD  file$,m                  change ole permissions                                      p.186

CLOSE  [[#]n]                    close ole, I/O channel or link                               p.195

FLUSH  [#n]                        AEush output                                                        p.298

KILL  file$                        delete a ole                                                        p.376

MAP                                      maps a ole into memory                                     p.??

UNMAP                                  unmaps memory                                                p.637

MKDIR  path$                      create a directory                                               p.419

OPEN  m$,#n,file$             open a ole or socket for input and/or output        p.456

OUT  #n,a                            out byte a to channel n                                       p.462

PRINT  #n;                          output to channel/ole                                          p.489

PUTBACK  [#n,]a                put back a char to channel/ole/console               p.501

RELSEEK  #n,d                    Place olepointer on new relative position            p.520

RENAME  file$,dst$           rename and move a ole                                      p.522

RMDIR  path$                      remove an empty directory                                 p.535

SEEK  #n,d                          place olepointer to absolute position                   p.554

TOUCH  #n                            update timestamps of ole                                   p.622

WATCH  file$                      monitor ole changes                                           p.655



5.10         Variable Manipulation Commands



ABSOLUTE  x,adr%               Assigns the address to the variable x.                 p.129

ARRAYCOPY  dst(),src()   copies array including dimensioning                   p.146

ARRAYFILL  a(),b               olls array with value                                            p.146

CLR  a,b,c(),f$                clear variables; same as a=0;b=0;c()=[];f$=""p.197

DEC  var                              decrement variable; same as var=var-1              p.222

DIM                                      declare and create array                                    p.237

ERASE  a()[,...]               erase arrays                                                       p.263

INC  a                                  increments variable a                                         p.355

LET  a=b                              enforces assignment                                          p.382

LOCAL  var[,...]               declare local variables in a procedure or functionp.392

SORT  a(),n[,b()]             Sort array                                                          p.585



                                                            105




5.11.__MEMORY_MANIPULATION_COMMANDS__________________________________________CHAPTER_5.__QUICK_REFERENCE___________________________*
 *___



SWAP  a,b                            Swap variables                                                  p.607

VAR  vars                            declare arguments to be passed "by reference"  p.646



5.11         Memory Manipulation Commands



ABSOLUTE  x,adr%               Assigns the address to the variable x.                 p.129

BMOVE  q,z,n                      copies a block of n bytes from address q to z      p.163

DPOKE  adr,word                write short int word to adr                                   p.243

FREE  adr%                          Frees a previously allocated memory block.        p.307

LPOKE  adr,long                writes long int value to pointer adr                      p.401

MFREE  adr%                        Frees a previously allocated memory block.        p.416

MSYNC  adr%,l                    AEushes changes map memory back to disk         p.431

POKE  adr,byte                  write byte to pointer adr                                      p.480

SHM.DETACH  adr%               detaches the shared memory segment               p.571

SHM.FREE  adr%                  frees the shared memory segment                     p.572



5.12         Math commands



ADD  a,b                              same as a=a+b but faster                                   p.133

DEC  var                              same as var=var-1 but faster                              p.222

DIV  a,b                              same as a=a/b but faster                                    p.240

FFT  a(),i                          fast fourier transformation on 1D array.               p.288

FIT  x(),y()[,yerr()],n,func(x,a,b,c,...)

                                            ots function to data                                             p.293

FIT.LINEAR  x(),y()[,[xerr(),]yerr()],n,a,b[,siga,sigb,chi2,q]

                                            linear regression with errors                               p.294

FIT.POLY  x(),y(),dy(),n%,a(),m%

                                            ot a polynom to datapoints                                 p.295

INC  var                              same as var=var+1 but faster                             p.355

MUL  a,b                              same as a=a*b but faster                                   p.434

SORT  a(),n[,b()]             sorts n values of a() to incrementing order          p.585

SUB  a,b                              same as a=a-b but faster                                    p.602



                                                            106




CHAPTER_5.__QUICK_REFERENCE____________________________________________________________5.13.__OTHER_COMMANDS________________



5.13         Other Commands



CALL  adr[,par,...]         see EXEC                                                          p.177

CONNECT  #n,t$[,i%]         connect a channel                                              p.205

DATA  1,"Hallo",...         deone constants                                                p.220

DELAY  sec                          same as PAUSE                                                p.234

ERROR  n                              execute error number n                                      p.266

EVAL  t$                              execute X11-Basic command contained in t$      p.267

EXEC  adr[,var,...]         call a C subroutine at pointer adr.                       p.276

GET.LOCATION  ,,,,,,,     returns the position of the device                        p.323

GPS  ON/OFF                        turns GPS device on/ooe                                     p.336

LINK  #n,t$                        load shared object ole t$                                    p.387

UNLINK  #n                          unload shared object ole                                    p.636

MERGE  f$                            Merges bas-ole to actual program code              p.414

NOP                                      no operation do nothing                                     p.441

NOOP                                    no operation do nothing                                     p.441

PAUSE  sec                          pauses sec seconds                                          p.465

PIPE  #l,#k                        links two ole channels                                        p.472

PLAYSOUND  c,s$                plays a WAV sample                                          p.473

PLAYSOUNDFILE  file$       plays a sound ole                                               p.474

PROCEDURE  proc(p1,...) PROCEDURE * RETURN                                  p.494

RANDOMIZE  [seed]             Sets seed for random generator                         p.512

READ  var                            reads constant from DATA statement                  p.514

RECEIVE  #n,t$                  receive a message from a socket                       p.517

RESTORE  [label]               (re)sets pointer for READ-statement to label       p.525

RETURN  expr                      return value from FUNCTION                             p.528

RSRC.LOAD  file$               loads GEM rsc-File (ATARI ST)                          p.544

RSRC.FREE                          frees GEM rsc-File                                             p.543

SEND  #n,t$                        send a message to a socket                               p.557

SENSOR  ON/OFF                  turns SENSORs on/ooe                                       p.561

SETENV  t$=a$                    Sets environmentvar t$ using value a$               p.562

SOUND  freq                        Sound the internal speaker                                p.587

SPLIT  t$,d$,mode,a$,b$ splits t$ by deliminator d$ into a$ and b$            p.594



                                                            107




5.14.__GRAPHIC_COMMANDS______________________________________________________CHAPTER_5.__QUICK_REFERENCE___________________________*
 *___



SHELL  t$                            execute ole as shell                                            p.568

SPEAK  t$                            Text to speach                                                   p.592

SYSTEM  t$                          execute shell with command t$                           p.610

UNLINK  #n                          un-links shared object #n                                   p.636

VOID  a                                calculates expression a and discard result          p.651

WAVE  c,f,                          control the sound synthesizer                             p.656

WORT.SEP                            same as SPLIT                                                  p.664



5.14         Graphic commands



5.14.1          Drawing and painting



BOUNDARY  f                        switch borders on or ooe                                      p.164

BOX  x1,y1,x2,y2               draw a frame                                                      p.165

CIRCLE  x,y,r,,                draw a circle                                                      p.191

CLIP  ,,,,,                        clipping function                                                 p.194

COLOR  f[,b]                      Set foreground color (and background color)      p.199

COPYAREA  ,,,,,                copy a rectangular screen section                      p.207

CURVE  ,,,,,,,                  cubic Bezier-curve                                             p.214

DEFFILL  c,a,b                  set oll style and pattern                                      p.226

DEFLINE  a,b                      set line width and type                                       p.228

DEFMARK  c,a,g                  set color, size, type (POLYMARK)                       p.230

DEFMOUSE  i                        set mouse cursor type                                        p.231

DEFTEXT  c,s,r,g               set text properties for ltext                                  p.232

DRAW  [[x1,y1]  TO]  x2,y2draw line                                                            p.245

ELLIPSE  x,y,a,b[,a1,a2]draw an ellipse                                                   p.250

FILL  x,y                            AEood oll                                                              p.292

GET  x,y,w,h,g$                store a portion of the screen bitmap in g$           p.320

GPRINT                                like PRINT, but the output goes to the graphicpwindow.330

GRAPHMODE  mode                set graphic-mode                                               p.340

LINE  x1,y1,x2,y2             draw a line                                                         p.384

LTEXT  x,y,t$                    Linegraphic-Text                                                p.402

PBOX    x1,y1,x2,y2           draw olled box                                                    p.466

PCIRCLE  x,y,r[,a1,a2]   draw olled circle                                                 p.468

PELLIPSE  x,y,a,b[,a1,a2]draw olled ellipse                                               p.470



                                                            108




CHAPTER_5.__QUICK_REFERENCE_________________________________________________________5.14.__GRAPHIC_COMMANDS_________________



PLOT  x,y                            draw point                                                          p.476

POLYLINE  n,x(),y()         draw polygon in (x(),y())                                     p.482

POLYFILL  n,x(),y()         draw olled polygon                                             p.481

POLYMARK  n,x(),y()         draw polygon points                                           p.483

PRBOX  x1,y1,x2,y2           draw olled rounded box                                      p.485

PUT  x,y,g$                        map graphic at position                                      p.499

PUT.BITMAP  t$,i,i,i,i   map bitmap                                                        p.502

RBOX  x1,y1,x2,y2             draws a rounded box                                          p.513

SCOPE  a(),typ,ys,yo       fast plot of data a()                                             p.550

SCOPE  y(),x(),typ,ys,yo,xs,xofast 2D plot of data                                             p.550

SETFONT  f$                        set bitmap font                                                   p.563

SETMOUSE  x,y                    set mouse cursor                                               p.565

SGET  screen$                    capture graphic and store it in screen$               p.566

SPUT  screen$                    maps graphic to window/screen                          p.595

TEXT  x,y,t$                      draw text (bitmap font)                                        p.617



5.14.2          Screen/Window commands



CLEARW  [#n]                      clear graphic window                                          p.193

CLOSEW  [#n]                      close graphic window                                         p.196

FULLW  n                              make window fullscreen                                     p.313

GET.GEOMETRY  ,,,,           returns the size of the window or screen             p.322

GET.SCREENSIZE  ,,,,       returns the size of the screen                             p.325

INFOW  n,t$                        set window information                                       p.356

MOVEW  n,x,y                      move window                                                     p.429

OPENW  n                              open window                                                     p.459

ROOTWINDOW                        draw on screen background                               p.538

NOROOTWINDOW                    switch back to normal output                              p.443

SAVESCREEN  file$             save screen bitmap into a ole                             p.548

SAVEWINDOW  file$             save window bitmap into a ole                            p.549

SCREEN  n                            select Screen mode                                           p.552

SHOWPAGE                            perform pending graphic operations                   p.576

SIZEW  n,w,h                      size window                                                       p.582

TITLEW  n,t$                      set window title                                                  p.620

TOPW  n                                move window to front                                         p.621



                                                            109




5.15.__FILE_INPUT/OUTPUT_FUNCTIONS___________________________________________CHAPTER_5.__QUICK_REFERENCE___________________________*
 *___



USEWINDOW  #n                    direct graphics output to window n                      p.640

VSYNC                                  same as SHOWPAGE                                        p.653



5.14.3          GUI/User input commands



ALERT  a,b$,c,d$,var[,ret$]Show Alert/Infobox and wait for user input          p.137

EVENT  ,,,,,,,,                Waits until an event occurs                                 p.270

FILESELECT  tit$,path$,dflt$,f$display a oleselector-box                                    p.291

HIDEK                                  hide the virtual keyboard                                    p.347

HIDEM                                  hide the mouse cursor                                       p.348

KEYEVENT  a,b                    Waits until key is pressed                                   p.375

LISTSELECT  tit$,list$()display a selector-box                                        p.389

MENUDEF  m$(),proc           read menu titles and items from m$()                 p.411

MENUKILL                            deletes menu                                                     p.412

MENUSET  n,x                      change menu-point #n with value x                     p.413

MENU  STOP                          switch ooe the menu                                            p.??

ONMENU                                execute the menu and                                        p.??

MENU                                    wait for menu-events                                          p.410

MOUSE  x,y,k                      gets position and state of mouse                        p.425

MOUSEEVENT  ,,,                wait for mouse event                                          p.426

MOTIONEVENT  ,,,               wait for mouse movement                                  p.424

OBJC.ADD  t%,o%,c%           add object to tree                                               p.446

OBJC.DELETE  t%,o%           delete object from tree                                       p.446

RSRC.LOAD  file$               loads a GEM resource ole                                  p.544

RSRC.FREE                          unloads a GEM resource                                   p.543

SHOWK                                  show the virtual keyboard                                   p.574

SHOWM                                  show the mouse cursor                                      p.575



5.15         File Input/Output functions



d%=DEVICE(file$)             returns the device id of a ole                               p.236

b=EOF(#n)                          TRUE if ole pointer reached end of ole                p.261



                                                            110




CHAPTER_5.__QUICK_REFERENCE______________________5.16.__VARIABLE/STRING_MANIPULATION_FUNCTIONS______________________________



b=EXIST(fname$)               TRUE if ole fname$ exist                                    p.278

a=FREEFILE()                    Returns orst free olenumber or -1                       p.308

a$=FSFIRST$(path$,,)     searches for the orst ole in a olesystem              p.309

a$=FSNEXT$()                    searches for the next ole                                    p.312

c=INP(#n)                          reads a byte from channel/ole.                            p.360

c=INP?(#n)                        number of bytes which can be read                    p.361

a=INP&(#n)                        reads a word (2 Bytes) from channel/ole.            p.360

i=INP%(#n)                        reads a long (4 Bytes) from channel/ole.             p.360

t$=INPUT$(#n,num)           reads num bytes from ole/channel n                   p.363

ret=IOCTL(#n,d%,)           performs settings on channel/ole.                       p.368

t$=LINEINPUT$(#n)           reads a line from ole/channel n                           p.385

p=LOC(#n)                          Returns value of ole position indicator                p.391

l=LOF(#n)                          length of ole                                                       p.394

l%=SIZE(file$)                returns the size of a ole                                      p.581

t$=TERMINALNAME$(#n)     returns device name of terminal connected to #np.616



5.16         Variable/String Manipulation functions



adr%=ARRPTR(b())             pointer to array descriptors                                 p.148

a=ASC(t$)                          ASCII code of orst letter of string                        p.149

b$=BIN$(a[,n])                convert to binary number                                   p.161

t$=CHR$(a)                        convert ASCII code to string                               p.188

a$=DECLOSE$(t$)               removes enclosing characters from string           p.223

a=DIM?(a())                      returns number of elements of array a()              p.238

a$=ENCLOSE$(t$[,p$])     encloses a string                                                p.252

f=GLOB(a$,b$[,flags])   TRUE if a$ matches pattern b$                          p.326

t$=HEX$(a[,n])                a as hexadecimal number                                  p.346

t$=INLINE$(a$)                6-bit ASCII to 8-bit binary conversion                  p.358

a=INSTR(s1$,s2$[,n])     tests if s2$ is contained in s1$                            p.364

a=TALLY(t$,s$)                returns the number of occurrences of s$ in t$     p.613

b%=INT(a)                          convert to integer                                               p.365

t$=LEFT$(a$[,n])             extracts n bytes from string a$ from the left         p.379

t$=LEFTOF$(a$,b$)           returns left part of a$ split at b$                          p.380

l=LEN(t$)                          length of string                                                   p.381



                                                            111




5.17.__DATA_COMPRESSION_AND_CODING_FUNCTIONS_________________________________CHAPTER_5.__QUICK_REFERENCE___________________________*
 *___



u$=LOWER$(t$)                  converts t$ to lower case                                    p.399

l=LTEXTLEN(t$)                size of text                                                         p.403

m$=MID$(t$,s[,l])           extracts l bytes from string t$ from position s       p.417

t$=MKA$(a())                    convert a whole array into a string                      p.420

t$=MKI$(i)                        convert integer to 2-byte string                           p.420

t$=MKL$(i)                        convert integer to 4-byte string                           p.420

t$=MKF$(a)                        convert AEoat to 4 byte string                               p.420

t$=MKD$(a)                        convert AEoat to 8 byte string                               p.420

o$=OCT$(d,n)                    convert integer d to string with octal number       p.451

t$=REPLACE$(a$,s$,r$)   replace s$ by r$ in a$                                         p.524

t$=REVERSE$(a$)               Return the reverses of a string                           p.529

t$=RIGHT$(a$[,n])           returns right n characters of a$                           p.530

t$=RIGHTOF$(a$,b$)         returns right part of a$ split at b$                        p.531

a=RINSTR(s1$,s2$[,n])   tests from right if s2$ is contained in s1$            p.532

t$=SPACE$(i)                    returns string consisting of i spaces                    p.590

t$=STR$(a[,b,c])             convert number to string                                    p.600

t$=STRING$(i,w$)             returns string consisting of i copies of w$            p.601

u$=TRIM$(t$)                    trim t$                                                                p.624

u$=XTRIM$(t$)                  trim t$                                                                p.670

u$=UCASE$(t$)                  converts t$ to upper case                                   p.632

u$=UPPER$(t$)                  converts t$ to upper case                                   p.639

u$=USING$(a,f$)               formats a number                                               p.641

a=VAL(t$)                          converts String/ASCII to number                        p.644

i=VAL?(t$)                        returns number of chars which are part of a numberp.644

adr%=VARPTR(v)                returns pointer to variable                                   p.649

u$=WORD$(b$,n)                returns n th word of b$                                       p.662

e=WORT.SEP(t$,d$,m,a$,b$)splits t$ into parts                                               p.??



5.17         Data compression and coding functions



b$=ARID$(a$)                    order-0 adaptive arithmetic decoding                  p.144

b$=ARIE$(a$)                    order-0 adaptive arithmetic encoding                  p.145

b$=BWTD$(a$)                    inverse Burrows-Wheeler transform                    p.172

b$=BWTE$(a$)                    Burrows-Wheeler transform                                p.173



                                                            112




CHAPTER_5.__QUICK_REFERENCE___________________________________5.18.__MEMORY_MANIPULATION_FUNCTIONS__________________________



c$=COMPRESS$(a$)             lossless compression on the string                     p.203

c$=UNCOMPRESS$(a$)         lossless uncompression on the string                 p.633

c%=CRC(t$[,oc])               32 bit checksum                                                 p.210

e$=ENCRYPT$(t$,key$)     encrypts a message                                           p.253

t$=DECRYPT$(e$,key$)     decrypts a message                                           p.224

b$=MTFD$(a$)                    Move To Front decoding                                     p.432

b$=MTFE$(a$)                    Move To Front encoding                                     p.433

b()=CVA(a$)                      returns array reconstructed from the string         p.215

b%=CVI(a$)                        convert 2-byte string to integer                           p.217

b%=CVL(a$)                        convert 4-byte string to integer                           p.217

b=CVS(a$)                          convert 4-byte string to AEoat                               p.218

b=CVF(a$)                          convert 4-byte string to AEoat                               p.216

b=CVD(a$)                          convert 8-byte string to double                           p.216

t$=INLINE$(a$)                6-bit ASCII to 8-bit binary conversion                  p.358

t$=REVERSE$(a$)               return the reverses of a string                             p.529

b$=RLD$(a$)                      run length decoding                                           p.533

b$=RLE$(a$)                      run length encoding                                           p.534



5.18         Memory Manipulation functions



adr%=ARRPTR(b())             pointer to array descriptors                                 p.148

i%=DPEEK(adr%)                read word from pointer adr                                 p.243

b%=LPEEK(adr%)                reads long (4 Bytes) from address                      p.400

adr%=MALLOC(n%)               allocates size bytes of memory                           p.406

adr%=MSHRINK(adr%,n%)   reduces the size of a storage area                      p.430

d%=PEEK(a%)                      reads Byte from address a                                 p.469

adr%=REALLOC(oadr%,n%) changes the size of a storage area                     p.516

adr%=SHM.ATTACH(id)       attaches the shared memory segment                p.570

id=SHM.MALLOC(size,key)returns the identioer of the shared memory segmentp.573

adr%=SYM.ADR(#n,s$)       return pointer to symbol from shared object ole   p.609

adr%=VARPTR(v)                returns pointer to variable                                   p.649



                                                            113




5.19.__LOGIC_FUNCTIONS_______________________________________________________CHAPTER_5.__QUICK_REFERENCE___________________________*
 *___



5.19         Logic functions



c%=AND(a%,b%)                  same as c=(a AND b)                                         p.140

c%=OR(a%,b%)                    same as c=(a OR b)                                           p.461

c%=XOR(a%,b%)                  same as c=(a XOR b)                                        p.668

c%=EQV(a%,b%)                  same as c=(a EQV b)                                         p.262

c%=IMP(a%,b%)                  same as c=(a IMP b)                                          p.354

b%=BCHG(x%,bit%)             changes the bit of x from 0 to 1 or from 1 to 0     p.157

b%=BCLR(x%,bit%)             sets the bit of x to zero.                                      p.157

b%=BSET(x%,bit%)             sets the bit of x to 1.                                           p.170

b%=BTST(x%,bit%)             returns -1 if the bit of x is 1.                                p.171

b%=BYTE(x%)                      same as b=x AND 255                                       p.174

b%=CARD(x%)                      same as b=x AND 0xoeoe                                     p.180

b%=WORD(x%)                      same as b=x AND 0xoeoe                                     p.661

b%=EVEN(d)                        TRUE if d is an even number                              p.269

b%=ODD(d)                          TRUE if d is an odd number                               p.452

b%=GRAY(a)                        Gray code. if a!0: inverse Gray code                  p.341

b%=SHL(a)                          Shift bits to left                                                   p.569

b%=SHR(a)                          Shift bits to right                                                 p.577

b%=SWAP(a)                        Swaps High and Low words of a                         p.607



5.20         Math functions



The math function library contains a comprehensive set of mathematics functions,

including:



     #  trigonometric

     #  arc-trigonometric

     #  hyperbolic

     #  arc-hyperbolic

     #  logarithmic ( base e and base 10 )

     #  exponential ( base e and base 10 )

     #  miscellaneous ( square root, power, etc. )



Some math functions are deoned on Vectors and Matrices.



                                                            114




CHAPTER_5.__QUICK_REFERENCE_______________________________________________________________5.20.__MATH_FUNCTIONS_____________



b=ABS(a)                            absolute value b = jaj                                        p.128

c=ADD(a,b)                        add c = a + b  p  __                                              p.133

b=CBRT(a)                          cube root b =  3 a                                               p.182

a=CEIL(b)                          truncate number                                                p.183

a=CINT(b)                          truncate number (note: dioeers from INT() !)         p.190

z=COMBIN(n,k)                  number of combinations z = _____n!_____(n#k)!#k!         p.202

c=DIV(a,b)                        divide c = a=b                                                   p.240

b()=FFT(a()[,f%])           discrete Fourier Transformation of a real array    p.288

a=FIX(b)                            round number to integer                                     p.296

a=FLOOR(b)                        round number down to integer                            p.297

b=FRAC(a)                          fractional (non-integer) part of a                         p.306

y=GAMMA(x)                        gamma function y = # (x)                                   p.317

y=LGAMMA(x)                      logarithm of#gamma_function_y = jln  # (x)j          p.383

a=HYPOT(x,y)                    returns a =     x2 + y2                                            p.350

b=INT(a)                            convert to integer                                               p.365

b()=INV(a())                    calculate inverse of a square matrix                    p.366

i=SGN(a)                            sign of a (-1,0,1)p__                                             p.567

b=SQR(a)                            square root b =p  _a_                                           p.596

b=SQRT(a)                          square root b =    a                                            p.596

b=TRUNC(a)                        truncate number                                                p.628

b=LN(a)                              base e logarithm (natural log)                             p.395

b=LOG(a)                            base e logarithm (natural log)                             p.395

b=LOG10(a)                        base 10 logarithm                                              p.395

b=LOGB(x)                          base 2 logarithm                                                p.396

b=LOG1P(x)                        b = log  (1 + x) accurate near zero                      p.397

c=MOD(a,b)                        same as c=(a MOD b)                                        p.421

c=MUL(a,b)                        multiply c = a # b                                                 p.434

b=EXP(a)                            exponential function b = ex  (e to the x)               p.281

b=EXPM1(a)                        exponential function minus 1 b = ex # 1              p.282

b=FACT(a)                          factorial b = a!                                                   p.284

a=PRED(x)                          returns the preceding integer of x                       p.486

a=SUCC(x)                          returns the next higher integer                            p.606

b()=SOLVE(a(),x())         solve linear equation system                              p.583

z=VARIAT(n,k)                  number of permutations of n elements                p.647



                                                            115




5.20.__MATH_FUNCTIONS________________________________________________________CHAPTER_5.__QUICK_REFERENCE___________________________*
 *___



5.20.1          Angles


Angles are always radians, for both, arguments and return values.



b=RAD(a)                            convert degrees to radians                                 p.506

b=DEG(a)                            convert radians to degrees                                 p.233



5.20.2          Trigonometric functions



b=SIN(a)                            sine                                                                   p.579

b=COS(a)                            cosine                                                                p.208

b=TAN(a)                            tangent                                                              p.614

b=ASIN(a)                          arc-sine                                                             p.150

b=ACOS(a)                          arc-cosine                                                          p.131

b=ATAN(a)                          arc-tangent                                                        p.153

b=ATN(a)                            arc-tangent                                                        p.153

b=ATAN2(a,c)                    extended arc-tangent                                         p.153

b=SINH(a)                          hyperbolic sine                                                   p.580

b=COSH(a)                          hyperbolic cosine                                               p.208

b=TANH(a)                          hyperbolic tangent                                              p.615

b=ASINH(a)                        hyperbolic arc-sine                                             p.150

b=ACOSH(a)                        hyperbolic arc-cosine                                         p.131

b=ATANH(a)                        hyperbolic arc-tangent                                        p.154



5.20.3          Random numbers



a=GASDEV(dummy)               random number Gauss distribution                     p.318

a=RAND(dummy)                  random integer number                                      p.508

a=RANDOM(n)                      random integer number between 0 and n            p.510

a=RND(dummy)                    random number between 0 and 1                       p.536

a=SRAND(seed)                  same as RANDOMIZE                                       p.597



                                                            116




CHAPTER_5.__QUICK_REFERENCE___________________________________________________________5.21.__SYSTEM_FUNCTIONS_______________



5.21         System functions



ret%=CALL(adr%[,par])   Calls a machine code or C subroutine                p.177

t$=ENV$(n$)                      read value of environment variable n$                p.260

t$=ERR$(i)                        error message                                                   p.265

ret=EXEC(adr[,var])       see command EXEC, returns int                        p.276

i%=FORK()                          creates a child process                                      p.300

d$=JULDATE$(a)                date$ by Julian day a                                         p.372

a=JULIAN(date$)               Julian day                                                          p.373

a$=PARAM$(i)                    i'th word from the commandline                          p.464

t$=PRG$(i)                        program line                                                      p.488

a=SENSOR(i)                      get the value from the i th sensor                        p.561

t$=SYSTEM$(n$)                execute shell with command n$                          p.610

t$=UNIXTIME$(i)               give time$ from TIMER value                             p.635

d$=UNIXDATE$(i)               give date$ from TIMER value                             p.635



5.22         Graphic functions



c=COLOR.RGB(r,g,b[,a]) allocate color by rgb(a) value                              p.200

a=EVENT?(mask%)               returns TRUE if a graphics event is pending       p.272

a=FORM.ALERT(n,t$)         message box with default button n                      p.301

~FORM.CENTER(adr%,x,y,w,h)centers the object tree on screen                       p.302

a=FORM.DIAL(,,,,,,,,)   complex function for screen preparation             p.303

a=FORM.DO(i)                    do dialog                                                            p.305

c=GET.COLOR(r,g,b)         allocate color by rgb value                                  p.321

d=OBJC.DRAW(,,,,)           draw object tree                                                 p.448

ob=OBJC.FIND(tree,x,y) return object number by coordinates                   p.449

a=OBJC.OFFSET(t%,o,x,y)calculate absolute object coordinates                 p.450

c=POINT(x,y)                    returns color of pixel of graphic in window           p.479

c=PTST(x,y)                      returns color of pixel of graphic in window           p.497

a=RSRC.GADDR(typ,nr)     get pointer to object tree                                    p.??



                                                            117




5.23.__OTHER_FUNCTIONS_______________________________________________________CHAPTER_5.__QUICK_REFERENCE___________________________*
 *___



5.23         Other functions



a=EVAL(t$)                        evaluate expression contained in t$                    p.267

m=MAX(a,b,c,...)             returns biggest value                                          p.409

m=MAX(f())                        not implemented yet

m=MIN(a,b,c,...)             returns smallest value                                        p.418

m=MIN(array())                not implemented yet

m=MIN(function())           not implemented yet



5.24         Subroutines and Functions



Subroutines   are blocks of code that can be called from elsewhere in the program.

Subroutines can take arguments but return no results.  They can access all vari-

ables  available  but  also  may  have  local  variables  (~?  LOCAL).  Subroutines  are

deoned with



              PROCEDURE  name(argumentlist)

                  ...    many  commands

              RETURN



Functions   are blocks of code that can be called from elsewhere within an expres-

sion (e.g a=3*@myfunction(b)).  Functions can take arguments and must return

a result.  Variables are global unless declared local.  For local variables changes

outside a function have no eoeect within the function except as explicitly specioed

within the function. Functions arguments can be variables and arrays of any types.

Functions can return variables of any type.  By default, arguments are passed by

value. Functions can be executed recursively. A function will be deoned by:



              FUNCTION  name(argumentlist)

                  ..  many  more  calculations

                  RETURN  returnvalue

              ENDFUNCTION



                                                            118




CHAPTER_5.__QUICK_REFERENCE_____________________________________________________________5.25.__ERROR_MESSAGES_______________



5.25        Error Messages



X11-Basic  can  produce  a  number  of  internal  errors,  which  are  referred  to  by  a

number (ERR) (see also ERROR).

     The meaning of this errors and their text expression is as follows:



0        Divide by zero

1        OverAEow

2        Value not integer -2147483648 .. 2147483647

3        Value not byte 0 .. 255

4        Value not short -32768 .. 32767

5        Square root: only positive numbers

6        Logarithm only for positive numbers

7        Unknown Error

8        Out of Memory

9        Function or command is not implemented in this version of X11-Basic

10       String too long

11       Argument needs to be positive

12       Program too long, buoeer size exceeded ~? NEW

13       Type mismatch in expression

14       Array () is already dimensioned

15       Array not dimensioned: ()

16       Field index too large

17       Dim too large

18       Wrong number of indexes

19       Procedure not found

20       Label not found

21       Open only "I"nput "O"utput "A"ppend "U"pdate

22       File already opened

23       Wrong ole #

24       File not opened

25       Wrong input, no number

26       EOF - reached end of ole

27       Too many points for Polyline/Polyoll

28       Array must be one dimensional

29       Illegal address!



                                                            119




5.25.__ERROR_MESSAGES________________________________________________________CHAPTER_5.__QUICK_REFERENCE___________________________*
 *___



30       Merge - no ASCII ole

31       Merge - line too long - CANCEL

32       ==? Syntax error

33       Label not deoned

34       Not enough data

35       data must be numeric

36       Error in program structure

37       Disk full

38       Command not allowed in interactive mode

39       Program Error GOSUB impossible

40       CLEAR not allowed within For-Next-loops or procedures

41       CONT not possible

42       Not enough parameters

43       Expression too complex

44       Function not deoned

45       Too many parameters

46       Incorrect parameter, must be number

47       Incorrect parameter, must be string

48       Open "R" - incorrect Field length

49       Too many "R"-oles (max. 31)

50       No "R"-ole

51       Parser: Syntax Error !?

52       Fields larger than oeld length

53       Wrong graphic format

54       GET/PUT wrong Field-String length

55       GET/PUT wrong number

56       Wrong number of parameters

57       Variable is not yet initialized

58       Variable has incorrect type

59       Graphic has wrong color depth

60       Sprite-String length wrong

61       Error with RESERVE

62       Menu wrong

63       Reserve wrong

64       Pointer wrong

65       Field size ! 256

66       No VAR-Array



                                                            120




CHAPTER_5.__QUICK_REFERENCE_____________________________________________________________5.25.__ERROR_MESSAGES_______________



67       ASIN/ACOS wrong

68       Wrong VAR-Type

69       ENDFUNC without RETURN

70       too many variables

71       Index too large

72       Error in RSRC.LOAD

73       Error in RSRC.FREE

74       Array dimensioning mismatch

75       Stack overAEow!

76       Illegal variable name . can not create.

77       Function not deoned for complex numbers.

78       Incorrect parameter, must be array

79       Incorrect regular expression: , cannot match

80       Matrix operations only allowed for one or two dimensional arrays

81       Matrices do not have the same order

82       Vector product not deoned

83       Matrix product not deoned

84       Scalar product not deoned

85       Transposition only for two dimensional matrices

86       Matrix must be square

87       Transposition not deoned

88       FACT/COMBIN/VARIAT/ROOT not deoned

89       Array must be two dimensional

90       Error in Local

91       Error in For

92       Resume (next) not possible: Fatal, For or Local

93       Stack Error

94       Parameter must be AEoat ARRAY

95       Parameter must be ARRAY

96       ARRAY has the wrong type. Can not convert.

97       This operation is not allowed for root window

98       Illegal Window number (0-16)

99       Window does not exist

100     X11-BASIC Version 1.27 Copyright (c) 1997-2020 Markus Hooemann

101     ** 1 - Segmentation fault

102     ** 2 - Bus Error: peek/poke ?

103     ** 3 - Address error: Dpoke/Dpeek, Lpoke/Lpeek?



                                                            121




5.25.__ERROR_MESSAGES________________________________________________________CHAPTER_5.__QUICK_REFERENCE___________________________*
 *___



104     ** 4 - Illegal Instruction

105     ** 5 - Divide by Zero

106     ** 6 - CHK exception

107     ** 7 - TRAPV exception

108     ** 8 - Privilege Violation

109     ** 9 - Trace exception

110     ** 10 - Broken pipe

131     * Number of hash collisions exceeds maximum generation counter value.

132     * Wrong medium type

133     * No medium found

134     * Quota exceeded

135     * Remote I/O error

136     * Is a named type ole

137     * No XENIX semaphores available

138     * Not a XENIX named type ole

139     * Structure needs cleaning

140     * Stale NFS ole handle

141     * Operation now in progress

142     * Operation already in progress

143     * No route to host

144     * Host is down

145     * Connection refused

146     * Connection timed out

147     * Too many references: can not splice

148     * Can not send after transport endpoint shutdown

149     * Transport endpoint is not connected

150     * Transport endpoint is already connected

151     * No buoeer space available

152     * Connection reset by peer

153     * Software caused connection abort

154     * Network dropped connection because of reset

155     * Network is unreachable

156     * Network is down

157     * Can not assign requested address

158     * Address already in use

159     * Address family not supported by protocol

160     * Protocol family not supported



                                                            122




CHAPTER_5.__QUICK_REFERENCE_____________________________________________________________5.25.__ERROR_MESSAGES_______________



161     * Operation not supported on transport endpoint

162     * Socket type not supported

163     * Protocol not supported

164     * Protocol not available

165     * Protocol wrong type for socket

166     * Message too long

167     * Destination address required

168     * Socket operation on non-socket

169     * Too many users

170     * Streams pipe error

171     * Interrupted system call should be restarted

172     * Illegal byte sequence

173     * Can not exec a shared library directly

174     * Attempting to link in too many shared libraries

175     * .lib section in a.out corrupted

176     * Accessing a corrupted shared library

177     * Can not access a needed shared library

178     * Remote address changed

179     * File descriptor in bad state

180     * Name not unique on network

181     * Value too large for deoned data type

182     * Not a data message

183     * RFS specioc error

184     * Try again

185     * Too many symbolic links encountered

186     * File name too long

187     * Resource deadlock would occur

188     * Advertise error

189     * memory page error

190     * no executable

191     * Link has been severed

192     * Object is remote

193     * Math result not representable

194     * Math arg out of domain of func

195     * Cross-device link

196     * Device not a stream

197     * Mount device busy



                                                            123




5.25.__ERROR_MESSAGES________________________________________________________CHAPTER_5.__QUICK_REFERENCE___________________________*
 *___



198     * Block device required

199     * Bad address

200     * No more processes

201     * No children

202     * Exchange full

203     * Interrupted system call

204     * Invalid exchange

205     * Permission denied, you must be super-user

206     * Operation in this channel not possible (any more)

207     * no more oles

208     * Link number out of range

209     * Level 3 reset

210     * Illegal Drive identioer

211     * Level 2 not synchronized

212     * Channel number out of range

213     * Identioer removed

214     * No message of desired type

215     * Operation would block

216     * illegal page address

217     * Directory not empty

218     * Function not implemented

219     * Illegal Handle

220     * Access not possible

221     * Too many open oles

222     * Path not found

223     * File not found

224     * Broken pipe

225     * Too many links

226     * Read-Only File-System

227     * Illegal seek

228     * No space left on device

229     * File too large

230     * Text ole busy

231     * Not a typewriter

232     * Too many open oles

233     * File table overAEow

234     * Invalid argument



                                                            124




CHAPTER_5.__QUICK_REFERENCE_____________________________________________________________5.25.__ERROR_MESSAGES_______________



235     * Is a directory

236     * Not a directory

237     * No such device

238     * Cross-device link

239     * File exists

240     * Bad sector (verify)

241     * unknown device

242     * Disk was changed

243     * Permission denied

244     * Not enough core memory

245     * read error

246     * write error

247     * No paper

248     * Sector not found

249     * Arg list too long

250     * Seek Error

251     * Bad Request

252     * CRC Error wrong check sum

253     * No such process

254     * Timeout

255     * IO-Error



                                                            125




This chapter is a command reference for quick lookup of short explanations of all

bult-in X11-Basic operators, variables, commands, and functions.


X11-Basic6  Command  Reference

6.1       Syntax templates



This manual describes the syntax of BASIC commands and BASIC functions in a

generalized form. Here is an example:



PRINT  [#!device-number?,]  !expression?  [!,?---!;?  [...]]



     Those parts of the command that must appear literally in the source code (like

PRINT  in  the  example  above)  are  all  uppercase.  Descriptions  in  angle  brackets

("!?") are not meant to appear literally in the source code but are descriptive ref-

erences  to  the  element  that  is  supposed  to  be  used  in  the  source  code  at  this

place,  like a variable,  a numeric expression etc.  Optional elements are listed in-

side square brackets ("[]"). They may be omitted from the command line. Mutually

exclusive alternatives are separated by the "---" character.  Exactly one of these al-

ternatives must appear in the command line.  Finally, repetitive syntax is indicated

by three dots "...". Here are some BASIC command lines that all match the syntax

template above:



PRINT  x

PRINT  #1,2*y

PRINT  "result  =  ";result



                                                            126




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



6.2       A



                                                            127




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           ABS()



Syntax:                a=ABS(b)

                              a%=ABS(b%)

                              a=ABS(b#)

                              a&=ABS(b&)



DESCRIPTION:



     Returns the absolute value of an expression.  The absolute value is the value

without regard to the sign (negative, zero or positive). The result of ABS will always

be a positive number or zero.  The absolute value of a complex number is a real

positive number.



EXAMPLE:



PRINT  ABS(-34.5),ABS(34)    !      Result:  34.5       34
PRINT  ABS(4+3i)                 !      Result:  5



SEE ALSO:           SGN()



                                                            128




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



Command:        ABSOLUTE



Syntax:                ABSOLUTE  var,adr%



DESCRIPTION:



     ABSOLUTE assigns the address adr% to the variable var.  This way you can

make the internal reference memory pointer of a X11-Basic variable use a dioeerent

memory location, for example the one of another variable.

     You could use this to pass a variable by reference to a PROCEDURE or FUNC-

TION (instead of the standard behaviour, which always passes variable by value to

functions and procedures by default).



EXAMPLE:


          a=3
          b=4
          ABSOLUTE  a,VARPTR(b)
          PRINT  a      !  Result:  4   Variables  a  and  b  are  now  identical.
          b=55
          PRINT  a      !  changing  b  now  also  affects  a  (and  vice  versa)



EXAMPLE:


          '  pass  a  variables  "by  reference"  to  a  X11-Basic  PROCEDURE
          a=12
          @fillwith4711(VARPTR(a))
          PRINT  a



                                                            129




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



          PROCEDURE  fillwith4711(adr%)
             LOCAL  b
             ABSOLUTE  b,adr%
             b=4711
          RETURN



SEE ALSO:           VAR, VARPTR()



                                                            130




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



Function:           ACOS()



Syntax:                a=ACOS(b)



DESCRIPTION:



     The ACOS() is the arc cosine function, i.e.  the inverse of the COS() function.

It returns the angle (in radian),  which,  fed to the cosine function will produce the

argument passed to the ACOS() function.



EXAMPLE:



PRINT  ACOS(0.5),ACOS(COS(PI))      !  Result:  1.047197551197   3.14159265359



SEE ALSO:           COS(), ASIN()



                             _________________________________*________________________________



Function:           ACOSH()



                                                            131




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Syntax:                a=ACOSH(b)



DESCRIPTION:



     The ACOSH() is the inverse hyperbolic cosine function, i.e.  the inverse of the

COSH() function. It returns the angle (in radian), which, fed to the hyperbolic cosine

function will produce the argument passed to the ACOSH() function.



EXAMPLE:



   PRINT  ACOSH(2),ACOSH(COSH(0))   !  Result:  1.316957896925  0



SEE ALSO:           COSH(), ASINH()



                                                            132




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



Command:        ADD



Syntax:                ADD  a,!num-expression?

                              ADD  a%,!num-expression?

                              ADD  a#,!num-expression?

                              ADD  a&,!num-expression?



DESCRIPTION:



     Increase the value of variable a by the result of !num-expression?.



EXAMPLE:


a=0.5
ADD  a,5
PRINT  a       !    Result:  5.5



SEE ALSO:           SUB, MUL, DIV, ADD()



                             _________________________________*________________________________



Function:           ADD()



                                                            133




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Syntax:                c=ADD(a,b)

                              c&=ADD(a&,b&)

                              c#=ADD(a#,b#)

                              c%=ADD(a%,b%)



DESCRIPTION:



     The function ADD() returns the sum of its arguments.



EXAMPLE:


a=0.5
b=ADD(a,5)
PRINT  b          !   Result:  5.5



SEE ALSO:           SUB(), MUL(), DIV(), ADD



                                                            134




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



Command:        AFTER



Syntax:                AFTER  !seconds?,  !procedure-name?



DESCRIPTION:



     AFTER allows a PROCEDURE to be called after the expiry of a given time. The

time must be specioed in seconds.



     Comment:



     The  current  implementation  uses  the  alarm  mechanism  of  the  kernel  of  the

operating system.  This means,  only one procedure can be scheduled for trigger

at  the  same  time.   Once  scheduled,  AFTER  cannot  be  canceled  anymore.   But

you can overwrite it with following AFTER commands.  If you use another AFTER

command  before  the  previous  one  has  triggered  the  procedure  the  previous  will

not be triggered anymore.

     The  procedure  is  excecuted  exactly  after  the  given  time,  interrupting  the  cur-

rently running process, even in the middle of a command. This can lead to a mess

in program stack, unpredictible crashes may be caused.  Using AFTER (and EV-

ERY) is not safe!  Keep the actions inside the intterupt PROCEDURE simple.  The

interrupt procedure should not do complicated things, it should not use interactive

commands and should not wait for user input.  Maybe just assign a constant to a

variable.

     Maybe also good to know: A PAUSE command will be immediately ended, when

the AFTER procedure is triggered, and The procedure will still be triggered, even

when the main program has already ended.



                                                            135




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



EXAMPLE:



         PRINT  "You  have  10  seconds  to  enter  your  name:  "
         AFTER  10,alarm
         INPUT  name$
         END
         PROCEDURE  alarm
           PRINT  "Time  out  !"
           QUIT
         RETURN



SEE ALSO:           EVERY



                                                            136




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



Command:        ALERT



Syntax:                ALERT  type%,message$,defaultbutton%,button$,click%[,text$]



DESCRIPTION:



     Creates  and  displays  an  alert  box  (with  a  message)  and  asks  for  user  input.

The message box can have one ore more buttons which can be clicked by the user

to exit the message box.  Also the user can enter text in several text input oelds if

they have been specioed.  The number of the button clocked is returned in click%

and the entered text in text$.

     type% chooses type of alert symbol, 0=none, 1="!", 2="?", 3="stop" message$

Contains  main  text.   Lines  are  separated  by  the  '---'  symbol.   Editable  oelds  are

started with a CHR$(27) followed by the default text to be edited (until "---"). button$

Contains text for the buttons (separated by '---').  defaultbutton% is the button to be

highlighted  (0=none,1,2,...)   to  be  selected  by  just  pressing  return.   click%  This

variable is set to the number of the button selected.  text$ This is a string variable

which  holds  any  text-input  the  user  made.   It  holds  the  contents  of  the  editable

oelds separated by a CHR$(13).



     Comment:



     The length of the text input oelds is given by the length of the default text. If you

want the user to be able to enter longer texts than the default, the default can be

extended by zero bytes (CHR$(0)) which are invisible to the user.



EXAMPLES:



ALERT  1,"Pick  a---button",1,"Left---Right",a



                                                            137




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



ALERT  0,"You  pressed---Button"+STR$(a),0,"OK",a

'  Example  of  editable  fields
i=1
name$="TEST01"+STRING$(4,CHR$(0))    !  maximum  length  6+4=10
posx$="N54#50'32.3"
t$="Edit  waypoint:------Name:    "+chr$(27)+name$+"---"
t$=t$+"Position:  "+chr$(27)+posx$+"---"
ALERT  0,t$,1,"OK---UPDATE---DELETE---CANCEL",a,f$
WHILE  LEN(f$)
   WORT.SEP  f$,CHR$(13),0,a$,f$
   PRINT  "Field";i;":  ",a$
   INC  i
WEND



SEE ALSO:           FORM.ALERT(), WORT.SEP, CHR$()



                                                            138




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



Operator:           AND



Syntax:                !num-expression1?  AND  !num-expression2?



DESCRIPTION:



     AND calculates the bit-wise logical and-opearation on the values on both sides.

It can be used to determine if BOTH conditions are true.  If both expression1 AND

expression2 are true, the result is true; otherwise 0 is returned for false.

     Also used to compare bits in binary number operations. 1 AND 1 return a 1, all

other combinations of 0's and 1's produce 0.



EXAMPLES:



Print  3=3  AND  4?2           Result:   -1  (true)
Print  3?3  AND  5?3           Result:    0  (false)

PRINT  (30?20  AND  20!30)   Result:   -1  (true)
PRINT  (4  AND  255)           Result:    4



SEE ALSO:           NAND, OR, NOT, XOR, IF



                             _________________________________*________________________________



                                                            139




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           AND()



Syntax:                !num-result?=AND(!num-expression?,!num-expression2?)



DESCRIPTION:



     This  function  returns  the  result  of  a  bitwise  AND  operation.   Returns  !num-

expression? AND !num-expression2?



EXAMPLE:



PRINT  AND(TIMER,0xff)   !  Result:  67



SEE ALSO:           OR(), AND



                                                            140




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



Variable:            ANDROID?



Syntax:                ANDROID?



DESCRIPTION:



     This  variable  gives  -1  (=TRUE)  if  the  operating  system  is  Android;  else  the

variable has a value of 0.  With testing this variable the program can ond out if it is

running on an Android device.



EXAMPLE:



IF  NOT  ANDROID?
   MOUSEEVENT
   QUIT
ELSE
   END
ENDIF



SEE ALSO:           TRUE, FALSE, UNIX?, WIN32?



                                                            141




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            ANS



Syntax:                ANS



DESCRIPTION:



     This variable stores the most recent result of a calculation which has not been

assigned to any variable. If you enter X11-Basic code that returns a number result

without  specifying  a  variable  which  the  result  should  be  assigned  to,  X11-Basic

creates the ANS variable and stores the result there.



EXAMPLE:


'  perform  a  simple  calculation  in  direct  mode
'  without  assigning  the  result  to  a  variable:
1+2      !  Result:  3
4+ANS   !  Result:  7
'  perform  a  simple  calculation  in  direct  mode
'  and  assign  the  result  to  the  variable  result,
'  ANS  will  not  be  created:
result=1+2
PRINT  result  !  Result:  3



Comment:



     The  variable  ANS  can  be  used  like  a  normal  variable  as  well.   It  will  only  be

changed  if  a  short  calculation  is  used  (normally  in  the  direct/interactive  mode).

This is useful if the X11-Basic interpreter is used like a pocket calculator.



SEE ALSO:           TRUE, FALSE, PI



                                                            142




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



Function:           ARG()



Syntax:                a=ARG(z#)



DESCRIPTION:



     Returns the argument of a complex value z#.  Any complex number a# can be

expressed as: a#=ABS(a#)*EXP(1i*ARG(a#))

     The argument is the phase angle of the complex number. The return value is a

real value in the range of (-PI,PI].



EXAMPLE:



PRINT  DEG(ARG(4+4i))    !      Result:  45



SEE ALSO:           IMAG(), REAL(), ABS(), ATAN2(), DEG()



                                                            143




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           ARID$()



Syntax:                b$=ARID$(a$)



DESCRIPTION:



     The arid$()-takes a string argument and returns the order-0 adaptive arithmetic

decoding of that string.

     Arithmetic coding is a form of entropy encoding used in lossless data compres-

sion.



EXAMPLE:


         t$="Hello,  this  is  a  test!!!!  This  shows  arithmetric  coding  and  decoding"
         t$=t$+"  with  X11-Basic."
         b$=ARIE$(t$)   !  encode  it
         PRINT  "The  string  was  compressed  to  ";ROUND(LEN(b$)/LEN(t$)*1000)/10;"%"
         c$=ARID$(b$)   !  decode  it
         PRINT  c$
      Result:
         The  string  was  compressed  to  88.1%
         Hello,  this  is  a  test!!!!  This  shows  arithmetric  coding  and  decodin....



SEE ALSO:           ARIE$()



                                                            144




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



Function:           ARIE$()



Syntax:                !string-result?=ARIE$(!string-expression?)



DESCRIPTION:



     The  ARIE$()  takes  a  string  argument  and  returns  the  order-0  adaptive  arith-

metic encoding of that string.

     Frequently used characters will be stored with fewer bits and not-so-frequently

occurring characters will be stored with more bits,  resulting in fewer bits used in

total.



EXAMPLE:


         t$="Hello,  this  is  a  test!!!!  This  shows  arithmetric  coding  and  "
         t$=t$+"decoding  with  X11-Basic."
         b$=ARIE$(t$)   !  encode  it
         print  "The  string  was  compressed  to  ";round(len(b$)/len(t$)*1000)/10;"%"
         c$=arid$(b$)   !  decode  it
         print  c$
      Result:
         The  string  was  compressed  to  88.1%
         Hello,  this  is  a  test!!!!  This  shows  arithmetric  coding  and  deco....



SEE ALSO:           ARID$()



                                                            145




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        ARRAYCOPY



Syntax:                ARRAYCOPY  d(),s()



DESCRIPTION:



     Copies the contents of array s() to d() (including dimensions). This is the same

as the statement: d()=s().



SEE ALSO:           DIM



                             _________________________________*________________________________



Command:        ARRAYFILL



Syntax:                ARRAYFILL  x(),n

                              ARRAYFILL  x$(),t$



DESCRIPTION:



     Assigns the value to all elements of an array or matrix.  It can be used to give

all array elements a deoned value, e.g. just after dimensioning the array where the

contents are yet undeoned.



                                                            146




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



EXAMPLE:


DIM  a(100)
ARRAYFILL  a(),13
PRINT  a(22)          Result:  13



SEE ALSO:           DIM



                                                            147




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           ARRPTR()



Syntax:                adr%=ARRPTR(a())



DESCRIPTION:



     Finds the address of the descriptor of an array.



EXAMPLE:



DIM  a(100,4)
adr%=ARRPTR(a())
PRINT  "Array  has  dimension:  ";LPEEK(adr%)
PRINT  "Array  index  list:  ";
FOR  i%=0  TO  LPEEK(adr%)
   PRINT  LPEEK(LPEEK(adr%+4)+4*i%);
   IF  i%!LPEEK(adr%)
      PRINT  ",";
   ENDIF
NEXT  i%
PRINT



SEE ALSO:           VARPTR(), UBOUND(), DIM?



                                                            148




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



Function:           ASC()



Syntax:                !num-result?=ASC(!string-expression?)



DESCRIPTION:



     Returns the ASCII code value (a number between 0 and 255) of the orst char-

acter in a string.  ASCII stands for American Standard Code for Information Inter-

change. ASC returns 0 if the length of string is zero or the ASCII code of the string

is zero.



EXAMPLE:



PRINT  ASC("A"),  ASC("T")   !  Result:  65,  84
PRINT  ASC("TEST")             !  Result:  84



SEE ALSO:           CHR$(), CVI(), CVL(), CVS()



                                                            149




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           ASIN()



Syntax:                !num-result?=ASIN(!num-expression?)



DESCRIPTION:



     The ASIN() is the arc sine function,  i.e.  the inverse of the SIN() function.  Or,

more elaborate:  It Returns the angle (in radian, not degrees !), which, fed to the

sine function will produce the argument passed to the ASIN() function.



EXAMPLE:



PRINT  6*ASIN(0.5)       !  Result:  3.14159265359



SEE ALSO:           ACOS(), SIN()



                             _________________________________*________________________________



Function:           ASINH()



                                                            150




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



Syntax:                !num-result?=ASINH(!num-expression?)



DESCRIPTION:



     The ASINH() function calculates the inverse hyperbolic sine of x, i.e. the inverse

of the SINH() function.  It returns the angle (in radian), which, fed to the hyperbolic

sine function will produce the argument passed to the ASINH() function.



SEE ALSO:           ACOSH(), SINH()



                                                            151




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Keyword:           AT()



Syntax:                PRINT  AT(y,x);[...]



DESCRIPTION:



     The AT statement takes two numeric arguments (e.g. AT(2,3)) and can be used

in combination with the PRINT or GPRINT command.

     The two numeric arguments of the AT function may range from 1 to the width

of your terminal minus 1, and from 0 to the height of your terminal minus 1; if any

argument  exceeds  these  values,  it  will  be  truncated  accordingly.  However,  X11-

Basic has no inAEuence on the size of your terminal (80x25 is a common, but not

mandatory), the size of your terminal and the maximum values acceptable within

the AT statement may vary. To get the size of your terminal you may use the COLS

and ROWS variables. To get the actual position of the text cursor you may use the

CRSCOL and CRSLIN variables.



EXAMPLE:


   PRINT  AT(3,1);"    This  is  a  Title    "
   GPRINT  AT(4,7);"Test"



SEE ALSO:           PRINT, GPRINT, TAB(), SPC(), COLS, ROWS, CRSLIN, CRSCOL, LOCATE



                                                            152




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



Function:           ATN(),    ATAN()



Syntax:                !num-result?=ATN(!num-expression?)

                              !num-result?=ATAN(!num-expression?)



DESCRIPTION:



     ATN() and ATAN() both return the angle in radians, for the inverse tangent of the

expression.



EXAMPLE:


PRINT  4*ATAN(1)       !  Result:  3.14159265359



SEE ALSO:           ACOS(), ASIN(), ATAN2()



                             _________________________________*________________________________



Function:           ATAN2()



                                                            153




6.2. _A________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Syntax:                c=ATAN2(a,b)



DESCRIPTION:



     The ATAN() function has a second form which accepts two arguments: ATAN2(a,b)

which is (mostly) equivalently to ATAN(a/b) except for the fact, that ATAN2 returns

an angle in the range (-PI to PI], whereas ATAN returns an angle in the range -PI/2

to PI/2.



EXAMPLE:


  PRINT  DEG(ATAN2(0,-1))      !  Result:  180



SEE ALSO:           ATAN()



                             _________________________________*________________________________



Function:           ATANH()



Syntax:                !num-result?=ATANH(!num-expression?)



                                                            154




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.2.__A__



DESCRIPTION:



     The ATANH() function calculates the inverse hyperbolic tangent of x; that is the

value whose hyperbolic tangent is x.  If the absolute value of x is greater than 1.0,

ATANH() returns not-a-number (NaN).



EXAMPLE:


  PRINT  DEG(ATANH(-0.5))       !  Result:  -31.47292373095



SEE ALSO:           ATAN()



                                                            155




6.3. _B________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



6.3       B



                                                            156




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.3.__B__



Function:           BCHG()



Syntax:                b%=BCHG(x%,bit%)



DESCRIPTION:



     Changes the bit% bit of x% from 0 to 1 or from 1 to 0.



EXAMPLE:



   PRINT  BCHG(1,2)       !  result:  5
   PRINT  BCHG(5,2)       !  result:  1



SEE ALSO:           BSET(), BCLR()



                             _________________________________*________________________________



Function:           BCLR()



Syntax:                b%=BCLR(x%,bit%)



                                                            157




6.3. _B________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



DESCRIPTION:



     BCLR sets the bit%-th bit of x% to zero.



EXAMPLE:



   PRINT  BCLR(7,1)       !  result:  5



SEE ALSO:           BSET(), BCHG()



                                                            158




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.3.__B__



Command:        BEEP,    BELL



Syntax:                BEEP

                              BELL



DESCRIPTION:



     Sounds the speaker of your terminal.  This command is not a sound interface,

so  you  can  neither  vary  the  length  or  the  height  of  the  sound  (technically,  it  just

prints CHR$(7)). BELL is exactly the same as BEEP.



SEE ALSO:           SOUND



                                                            159




6.3. _B________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        BGET



Syntax:                BGET  #n,adr%,len%



DESCRIPTION:



     Reads len% bytes from a data channel into an area of memory starting at ad-

dress adr%.

     Unlike with BLOAD, several dioeerent areas of memory can be read from a ole.



EXAMPLE:



   OPEN  "I",#1,"test.rsc"
   header$=SPACE$(32)
   BGET  #1,VARPTR(header$),32
   CLOSE  #1



SEE ALSO:           BLOAD, BPUT



                                                            160




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.3.__B__



Function:           BIN$()



Syntax:                a$=BIN$(!num-expression?[,len%])



DESCRIPTION:



     The bin$()-takes a numeric argument and converts it into a string of binary digits

(i.e. '0' and '1'). The minimal length of the output, the minimal number of digits, can

be specioed by the optional second argument. If the specioed length is bigger than

needed, the string is olled with leading zeros.  If you need binary representations

with sign, use RADIX$() instead.



EXAMPLE:


           PRINT  BIN$(64,8),BIN$(-2000)
Result:  01000000         11111111111111111111100000110000



SEE ALSO:           HEX$(), OCT$(), RADIX$()



                                                            161




6.3. _B________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        BLOAD



Syntax:                BLOAD  filename$,adr%



DESCRIPTION:



     BLOAD  reads  the  specioed  ole  into  memory  at  address  adr%.   The  memory

adr% is pointing to should be allocated before.  You should check if the ole exists

prior to using this function.  This command is meant to be used for loading binary

data.  To load a text ole, use OPEN and INPUT # to remain compatible with other

BASIC implementations.



EXAMPLE:


   IF  EXIST("test.dat")
      adr%=MALLOC(SIZE("test.dat"))
      BLOAD  "test.dat",adr%
   ENDIF



SEE ALSO:           MALLOC(), BGET, INPUT, INPUT$(), BSAVE



                                                            162




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.3.__B__



Command:        BMOVE



Syntax:                BMOVE  scr%,dst%,len%



DESCRIPTION:



     Fast movement of memory blocks.

     scr% is the address at which the block to be moved begins. dst% is the address

to which the block is to moved. len% is the length of the block in bytes.



EXAMPLE:


   a=1
   b=2
   BMOVE  VARPTR(a),VARPTR(b),8   !  same  as  b=a



SEE ALSO:           PEEK(), POKE, BLOAD, BSAVE



                                                            163




6.3. _B________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        BOUNDARY



Syntax:                BOUNDARY  flag%



DESCRIPTION:



     Switch ooe (or on) borders on olled shapes (PBOX, PCIRCLE ..). If AEag% is zero

- no border will be drawn (which is the default).



     Comment:



     Currently this command has no eoeect.



EXAMPLE:


   BOUNDARY  FALSE



SEE ALSO:           PBOX, PCIRCLE



                                                            164




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.3.__B__



Command:        BOX



Syntax:                BOX  x,y,x2,y2



DESCRIPTION:



     Draws  a  rectangle  with  corners  at  (x,y)  and  (x2,y2).  The  screen  coordinates

start in the upper left corner.  X increases to the right and y down to the bottom of

the screen or window.



EXAMPLE:


   COLOR  COLOR.RGB(1,1,0)
   BOX  20,20,620,380



SEE ALSO:           PBOX, GET.GEOMETRY



                                                            165




6.3. _B________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        BPUT



Syntax:                BPUT  #n,adr%,len%



DESCRIPTION:



     Writes len% bytes from an area of memory starting at adr% out to a data chan-

nel #n.



EXAMPLE:


   OPEN  "O",#1,"test.dat"
   BPUT  #1,VARPTR(t$),LEN(t$)
   CLOSE  #1



SEE ALSO:           BGET



                                                            166




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.3.__B__



Command:        BREAK



Syntax:                BREAK



DESCRIPTION:



     BREAK transfers control immediately outside the enclosing loop or select state-

ment. This is the preferred way of leaving such a statement (rather than goto).



     Comment:



     BREAK cannot be used in direct mode. Use EXIT instead.



EXAMPLE:


   DO
      INC  i
      IF  i?5
         PRINT  "i  is  big  enough."
         BREAK
      ENDIF
   LOOP



SEE ALSO:           EXIT  IF



                                                            167




6.3. _B________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        BROKER



Syntax:                BROKER  url$[,user$,passwd$,pesistence]



DESCRIPTION:



     Deone  a  (mqtt)  broker  and  connect  to  it.  You  can  specify  a  username  and  a

password if needed. You can specify if the session should be persistent or not.

     The url$ takes the form "protocol://host:port". Currently, protocol must be tcp or

ssl. For host, you can specify either an IP address or a host name.



     Comment:



     Only available, if MQTT support is compiled in.



EXAMPLE:


BROKER  "tcp://localhost:1883"



SEE ALSO:           PUBLISH, SUBSCRIBE



                                                            168




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.3.__B__



Command:        BSAVE



Syntax:                BSAVE  filename$,adr%,len%



DESCRIPTION:



     Save len% bytes in memory from address adr% to a ole named olename$.  If

olename does not exist,  it will be created.  If it does exist,  the old content will be

overwritten.  This command is meant be be used for saving binary data obtained

via BLOAD. To save text oles, use OPEN and PRINT # to remain compatible with

other BASIC implementations.



EXAMPLE:


   BSAVE  "content-t.dat",VARPTR(t$),LEN(t$)



SEE ALSO:           BLOAD, BPUT



                                                            169




6.3. _B________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           BSET()



Syntax:                b%=BSET(x%,bit%)



DESCRIPTION:



     BSET sets the bit%-th bit of x% to 1.



EXAMPLE:


   PRINT  BSET(0,2)      !  result:  4



SEE ALSO:           BCHG(), BCLR(), BTST()



                                                            170




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.3.__B__



Function:           BTST()



Syntax:                !bool-result?=BTST(x%,bit%)



DESCRIPTION:



     BTST results in -1 (TRUE) if bit bit% of x% is set.



EXAMPLE:


   PRINT  BTST(4,2)      !  result:  -1



SEE ALSO:           BCHG(), BCLR(), BSET()



                                                            171




6.3. _B________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           BWTD$()



Syntax:                b$=BWTD$(a$)



DESCRIPTION:



     BWTD$() performs the inverse Burrows-Wheeler transform on the string a$.

     The Burrows-Wheeler transform (BWT) is an algorithm used in data compres-

sion techniques. It was invented by Michael Burrows and David Wheeler.

     BWTD$() can restore the original content of a string which has been coded with

BWTE$() before.



EXAMPLE:


           t$="Hello,  this  is  the  Burrows  Wheeler  transformation!"
           b$=bwte$(t$)   !  encode  it
           print  b$
           c$=bwtd$(b$)   !  decode  it
           print  c$

Result:
esss,rno  !  rmhheHlstWtth  eelroalifretoruwiin   a  Bo
Hello,  this  is  the  Burrows  Wheeler  transformation!



SEE ALSO:           BWTE$()



                                                            172




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.3.__B__



Function:           BWTE$()



Syntax:                b$=BWTE$(a$)



DESCRIPTION:



     BWTE$() performs a Burrows-Wheeler transform on the string a$.

     The Burrows-Wheeler transform (BWT) is an algorithm used in data compres-

sion  techniques  such  as  bzip2.   It  was  invented  by  Michael  Burrows  and  David

Wheeler.

     When  a  character  string  is  transformed  by  the  BWT,  none  of  its  characters

change.  It  just  rearranges  the  order  of  the  characters.  If  the  original  string  had

several substrings that occurred often,  then the transformed string will have sev-

eral places where a single character is repeated multiple times in a row.  This is

useful for compression, since it tends to be easy to compress a string that has runs

of repeated characters by techniques such as run-length encoding.



EXAMPLE:



           t$="Hello,  this  is  the  Burrows  Wheeler  transformation!"
           b$=bwte$(t$)   !  encode  it
           print  b$
           c$=bwtd$(b$)   !  decode  it
           print  c$

Result:
esss,rno  !  rmhheHlstWtth  eelroalifretoruwiin   a  Bo
Hello,  this  is  the  Burrows  Wheeler  transformation!



SEE ALSO:           BWTD$()



                                                            173




6.3. _B________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           BYTE()



Syntax:                !num?=BYTE(!num-expression?)



DESCRIPTION:



     Returns lower 8 bits of argument. (same as a=b AND 255)



EXAMPLE:


   PRINT  BYTE(-200)      !  Result:  56



SEE ALSO:           CARD(), WORD(), SWAP()



                                                            174




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



6.4       C



                                                            175




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        CALL



Syntax:                CALL  adr%[,!parameter-list?]



DESCRIPTION:



     Calls a machine code or C subroutine at address !adr? without return value.

Optional parameters are passed on the stack.  (like in C). The default parameter-

type is (4-Byte) integer. If you want to specify other types, please use preoxes:


D:  --  double      (8  bytes)

F:  --  float        (4  bytes)

L:  --  integer    (4  bytes)

R:  --  long  integer    (8  bytes)

W:  --  short  integer  (2  bytes)

B:  --  byte          (1  byte)

P:  --  pointer    (4  bytes  or  8  bytes,  depending  on  the  OS)



     Comment:



     The  Option  P:  behaves  the  same  as  L:  on  32bit  operating  systems.  But  you

should use P: for pointers (VARPTR() etc...)  into memory so that it can be trans-

lated  from  X11-Basic  internal  32bit  representation  to  the  64bit  adresses  on  64it

operating systems. The B: and W: options behave the same as the L: option.



EXAMPLE:


DIM  result(100)
LINK  #1,"simlib.so"
adr%=SYM.ADR(#1,"CalcBeta")



                                                            176




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



CALL  adr%,D:1.2,L:0,P:VARPTR(result(0))
UNLINK  #1



SEE ALSO:           CALL(), EXEC



                             _________________________________*________________________________



Function:           CALL()



Syntax:                ret%=CALL(adr%[,!parameter-list?])



DESCRIPTION:



     Calls a machine code or C subroutine at address !adr%? and returns an integer

value ret%.  Optional parameters are passed on the stack.  (like in C). The default

parameter-type is (4-Byte) integer.  If you want to specify other types, please use

preoxes:



D:  --  double      (8  bytes)

F:  --  float        (4  bytes)

L:  --  integer    (4  bytes)

R:  --  long  integer    (8  bytes)

W:  --  short  integer  (2  bytes)

B:  --  byte          (1  byte)

P:  --  pointer    (4  bytes  or  8  bytes,  depending  on  the  OS)



     Comment:



                                                            177




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



      The  Option  P:  behaves  the  same  as  L:  on  32bit  operating  systems.  But  you

should use P: for pointers (VARPTR() etc...)  into memory so that it can be trans-

lated  from  X11-Basic  internal  32bit  representation  to  the  64bit  adresses  on  64it

operating systems. The B: and W: options behave the same as the L: option.



EXAMPLE:


DIM  result(100)
LINK  #1,"simlib.so"
adr%=SYM.ADR(#1,"CalcZeta")
ret%=CALL(adr%,D:1.2,L:0,P:VARPTR(result(0)))
UNLINK  #1



SEE ALSO:           CALL, EXEC



                             _________________________________*________________________________



Function:           CALLD()



Syntax:                ret=CALLD(adr%[,!parameter-list?])



DESCRIPTION:



     Calls a machine code or C subroutine at address !adr%? and returns a AEoting-

point value. Same as CALL() but returns a AEoating point value.



                                                            178




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



EXAMPLE:


LINK  #1,"libm.so"
adr%=SYM.ADR(#1,"cos")
ret=CALL(adr%,D:1)
UNLINK  #1



SEE ALSO:           CALL()



                             _________________________________*________________________________



Function:           CALL$()



Syntax:                ret$=CALL$(adr%[,!parameter-list?])



DESCRIPTION:



     Calls a machine code or C subroutine at address !adr%? and returns data as

a string.  Same as CALL() but returns arbitrary data, e.g.  from a C-function which

returns a struct.



     Comment:



     There is no way to determine,  how much data the function will return,  so the

returned string has a oxed size of 256 bytes.  If this is not enough, X11-Basic will

crash. This function is rarely used. Try to avoid it.



SEE ALSO:           CALL()



                                                            179




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           CARD()



Syntax:                a%=CARD(b%)



DESCRIPTION:



     Returns lower 16 bits of b%. (same as a%=b% AND (2^16-1))



EXAMPLE:


   PRINT  CARD(-200)       !  Result:  65336



SEE ALSO:           BYTE(), WORD(), SWAP()



                                                            180




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Keyword:           CASE



Syntax:                CASE  !num-expression?[,!num-expression?,...]



DESCRIPTION:



     CASE  takes  a  list  of  expressions  to  be  compared  with  the  expression  of  the

corresponding SELECT statement.



EXAMPLE:



      i=5
      SELECT  i
         CASE  1
       PRINT  1
         CASE  2,3,4
       PRINT  "its  2,3,  or  4"
         CASE  5
       PRINT  5
         DEFAULT
       PRINT  "default"
      ENDSELECT



SEE ALSO:           SELECT, DEFAULT, ENDSELECT



                                                            181




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           CBRT()



Syntax:                a=CBRT(x)



DESCRIPTION:



     The CBRT() function returns the cube root of x. This function cannot fail; every

representable real value has a representable real cube root.



EXAMPLE:


   PRINT  CBRT(8)       !  Result:  2



SEE ALSO:           SQRT()



                                                            182




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Function:           CEIL()



Syntax:                !num-result?=CEIL(!num-expression?)



DESCRIPTION:



     Ceiling function: return smallest integral value not less than argument.



EXAMPLE:



   PRINT  CEIL(-1.5),  CEIL(0.5)    !  result:  -1   1



SEE ALSO:           INT()



                                                            183




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        CHAIN



Syntax:                CHAIN  !file-name?



DESCRIPTION:



     CHAIN loads and runs another BASIC program.  Global variables will be avail-

able with their current value to the new program, all other variables are erased.  If

you want to append another program to the current program (as opposed to eras-

ing the current program and loading a new program), use the MERGE command

instead.



SEE ALSO:           LOAD, MERGE, RUN



                                                            184




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Command:        CHDIR



Syntax:                CHDIR  !path-name?



DESCRIPTION:



     CHDIR changes the current working directory to the directory specioed in path-

name.



EXAMPLE:


CHDIR  "/tmp"



SEE ALSO:           MKDIR, RMDIR, DIR$()



                                                            185




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        CHMOD



Syntax:                CHMOD  !file-name?,  !mode?



DESCRIPTION:



     CHMOD changes the permissions of a ole. The new ole permissions are spec-

ioed in mode, which is a bit mask created by ORing (or adding) together zero or

more of the following:


        1  execute/search  by  others  ("search"  applies  for  directories,

            and  means  that  entries  within  the  directory  can  be  accessed)

        2  write  by  others

        4  read  by  others

        8  execute/search  by  group

0x010  write  by  group

0x020  read  by  group

0x040  execute/search  by  owner

0x080  write  by  owner

0x100  read  by  owner

0x200  sticky  bit

0x400  set-group-ID

0x800  set-user-ID


     On most operating systems, the permissions are grouped into three levels: The

ole  owner,  the  owners  group,  or  all  others.  So  you  can  specify  that  this  ole  can

only  be  written  to  by  the  owner,  it  can  be  read  but  not  written  to  by  the  owners

group, and all other woll have no permission to either read or write to or from the

ole. mode=0x20+0x100+0x80

     You can also change the owner of that ole (mode=0x800+userid) or the group

it  belongs  to  (mode=0x400+groupid).   userid  and  groupid  my  be  between  0  and

1023.



                                                            186




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



EXAMPLE:


CHMOD  "/tmp/file",0x1e8



SEE ALSO:           OPEN



                                                            187




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           CHR$()



Syntax:                !string-result?  =  CHR$(!num-expression?)



DESCRIPTION:



     CHR$() returns the character associated with a given ASCII code.  If the argu-

ment is in the range of 0-255 it produces exactly one byte.

     Character table



          032            048    0        064    @      080    P        096    `      112    p

          033    !      049    1        065    A      081    Q        097    a      113    q

          034    "      050    2        066    B      082    R        098    b      114    r

          035    #      051    3        067    C      083    S        099    c      115    s

          036    $      052    4        068    D      084    T        100    d      116    t

          037    %      053    5        069    E      085    U        101    e      117    u

          038    &      054    6        070    F      086    V        102    f      118    v

          039    '      055    7        071    G      087    W        103    g      119    w

          040    (      056    8        072    H      088    X        104    h      120    x

          041    )      057    9        073    I      089    Y        105    i      121    y

          042    *      058    :        074    J      090    Z        106    j      122    z

          043    +      059    ;        075    K      091    [        107    k      123    --

          044    ,      060    !        076    L      092    "        108    l      124    ---

          045    -      061    =        077    M      093    ]        109    m      125    "

          046    .      062    ?        078    N      094    ^        110    n      126    ~

          047    /      063    ?        079    O      095    .        111    o      127



     Control codes



          00  NUL              08  BS      --  Backspace      16  DLE

          01  SOH              09  HT      --  horizontal  TAB      17  DC1    --  XON

          02  STX              10  LF      --  Newline      18  DC2



                                                            188




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



          03  ETX              11  VT      19  DC3    --  XOFF

          04  EOT              12  FF      --  Form  feed      20  DC4

          05  ENQ              13  CR      --  Carriage  Return    21  NAK

          06  ACK              14  SO      22  SYN

          07  BEL    --  Bell    15  SI      23  ETB



          24  CAN              32  SP    --  Space

          25  EM            127  DEL  --  Delete

          26  SUB

          27  ESC28  FS

          29  GS

          30  RT

          31  US



     Comment:



     You should avoid to pass an argument outside of the range 0-255 for compati-

bility reasons.  Currently only the lowest 8 bits are taken, but in future the function

could be extended to also produce unicode charackters (up to three bytes) taking

the unicode values (0-0xoeoe).



EXAMPLE:


          PRINT  CHR$(34);"Hello  World  !";CHR$(34)
          Result:  "Hello  World  !"



SEE ALSO:           ASC()



                                                            189




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           CINT()



Syntax:                !num-result?=CINT(!num-expression?)



DESCRIPTION:



     CINT() returns the rounded absolute value of its argument preoxed with the sign

of its argument.



EXAMPLE:


PRINT  CINT(1.4),  CINT(-1.7)
           Result:  2,  -2



SEE ALSO:           INT(), FRAC(), TRUNC(), ROUND()



                                                            190




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Command:        CIRCLE



Syntax:                CIRCLE  !x?,!y?,!r?[,!w1?,!w2?]



DESCRIPTION:



     Draw  a  circle  with  actual  color  (and  ollpattern).   The  x-  and  y-coordinates  of

the center and the radius of the circle are given in screen coordinates and pixels.

Optionally a starting angle !w1? and stop angle !w2? can be passed to draw a

circular arc.



EXAMPLE:


           CIRCLE  100,100,50



SEE ALSO:           ELLIPSE, COLOR, DEFFILL, PCIRCLE



                                                            191




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        CLEAR



Syntax:                CLEAR



DESCRIPTION:



     Clear all variables and arrays as if they were never used before.



SEE ALSO:           NEW



                                                            192




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Command:        CLEARW



Syntax:                CLEARW  [!num?]



DESCRIPTION:



     Clear graphic window. If a number is given, clear window with the number given.

The Window is olled with the background color, which can be specioed by COLOR.



EXAMPLE:


   foreground=COLOR.RGB(1,1,1)  !  white
   background=COLOR.RGB(0,0,1)  !  blue
   COLOR  foreground,background
   CLEARW
   SHOWPAGE



SEE ALSO:           CLOSEW, COLOR



                                                            193




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        CLIP



Syntax:                CLIP  x,y,w,h[,ox,oy]



DESCRIPTION:



     This command provide the 'Clipping' function, ie.  the limiting of graphic display

within a specioed rectangular screen area. The command CLIP deones the clipping

rectangle starting at the upper left coordinates x,y and extends w pixels wide and

h  high.   The  optional  additional  command  parameters  ox,oy  make  it  possible  to

redeone the origin of the graphic display.



     Comment:



     This command is still buggy. Do not use it.



EXAMPLE:


   CLIP  0,0,100,100,50,50
   CIRCLE  0,0,55
   SHOWPAGE



SEE ALSO:



                                                            194




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Command:        CLOSE



Syntax:                CLOSE  [[#]n[,[#]!num-expression?,...]]



DESCRIPTION:



     This statement is used to CLOSE one or more OPEN oles or other devices. The

parameter expression indicates a device number or ole number. If no ole or device

numbers are declared all OPEN devices will be closed.



     Comment:



     All oles should be closed before leaving a program to insure that data will not be

lost or destroyed. If a program exit is through END or QUIT, all oles will be closed.

If a program is stopped with the STOP command, all open oles remain open.



EXAMPLE:


           CLOSE  #1,#2
           CLOSE



SEE ALSO:           OPEN, LINK



                                                            195




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        CLOSEW



Syntax:                CLOSEW  [!num?]



DESCRIPTION:



     Close graphic window (make it disappear from the screen). If a number is given,

closes window with the number given.  The Window will again be opened,  when

the next graphic command is executed. This command has no eoeect on Android.



SEE ALSO:           CLEARW



                                                            196




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Command:        CLR



Syntax:                CLR  !var?[,!var?,...]



DESCRIPTION:



     Clear the variables given in the list. Sets specioed variables or arrays to 0 or "".



EXAMPLE:


   CLR  a,t$,i%,b()



SEE ALSO:           ARRAYFILL



                                                            197




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        CLS



Syntax:                CLS



DESCRIPTION:



     Clear text screen and move cursor home (upper left corner).



EXAMPLE:


   CLS
   PRINT  "This  is  now  a  title  line  on  an  empty  text  screen."



SEE ALSO:           PRINT



                                                            198




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Command:        COLOR



Syntax:                COLOR  !foreground-color?[,!background-color?]



DESCRIPTION:



     COLOR  sets  the  foreground  color  (and  optionally  the  background  color)  for

graphic  output  into  the  graphic  window.   The  color  values  are  dependent  of  the

color depth of the Screen. Usually the COLOR statement is used together with the

COLOR.RGB() function, so arbitrary colors may be used.



EXAMPLE:


yellow=COLOR.RGB(1,1,0)
blue=COLOR.RGB(0,0,1)
COLOR  yellow,blue



SEE ALSO:           COLOR.RGB(), LINE



                                                            199




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           COLOR.RGB()



Syntax:                c%=COLOR.RGB(r,g,b[,a])



DESCRIPTION:



     COLOR.GRB() returns a color number for the specioed color.  The rgb-values

range from 0 (dark) to 1.0 (bright).  The returned number depends on the screen

depth of the bitmap used. For 8 bit a color cell is allocated or if there is no free cell,

a color is chosen which is most similar to the specioed.

     The  optional  parameter  a  is  the  alpha  value  (0...1),  which  will  be  used  if  it  is

supported by the graphics system.

     The color numbers may be passed to the COLOR command.



EXAMPLE:


yellow=COLOR.RGB(1,1,0)
COLOR  yellow



SEE ALSO:           COLOR



                                                            200




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Variable:            COLS



Syntax:                n%=COLS



DESCRIPTION:



     Returns the number of colums of the text terminal (console).



EXAMPLE:


   PRINT  COLS,  ROWS       !  Result:  80         24



SEE ALSO:           ROWS, PRINT  AT(), CRSCOL, CRSLIN



                                                            201




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           COMBIN()



Syntax:                !num-result?=COMBIN(!n?,!k?)



DESCRIPTION:



     Calculates the number of combinations of !n? elements to the !k?th class with-

out repetitions. Deoned as z=n!/((n-k)!*k!).



EXAMPLE:


   PRINT  COMBIN(49,6)      !  result:   13983816



SEE ALSO:           FACT(), VARIAT()



                                                            202




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Function:           COMPRESS$()



Syntax:                c$=COMPRESS$(a$)



DESCRIPTION:



     Performs  a  lossless  compression  on  the  string  a$.   The  algorithm  uses  run

length encoding in combination with the Burrows-Wheeler transform. The result is

a better compression than p.ex.  the algorithm used by gzip.  At the moment the

COMPRESS$() function is identical to following combination:


      b$=ARIE$(RLE$(MTFE$(BWTE$(RLE$(a$)))))



SEE ALSO:           UNCOMPRESS$(), BWTE$(), RLE$(), MTFE$()



                                                            203




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           CONJ()



Syntax:                x#=CONJ(z#)



DESCRIPTION:



     Returns  the  complex  conjugate  value  of  z#.   That  is  the  value  obtained  by

changing the sign of the imaginary part.



EXAMPLE:


PRINT  CONJ(1-2i)       Result:  (1+2i)



SEE ALSO:           IMAG(), REAL()



                                                            204




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Command:        CONNECT



Syntax:                CONNECT  #n,server$,port%



DESCRIPTION:



     Initiate a connection on a socket.

     The ole number #n must refer to a socket,  which must have been created by

OPEN. If the socket is of type "U" or "V" then the server$ address is the address

to which packets are sent by default, and the only address from which packets are

received.  If the socket is of type "S","A","C","B" or "Z", this call attempts to make

a connection to another socket.  The other socket is specioed by server$, which is

an address in the communications space of the socket (usually an IP address or a

Bluetooth device address).

     Generally,  connection-based  protocol  sockets  may  successfully  connect  only

once; connectionless protocol sockets may use connect multiple times to change

their association.



     Comment:



     This function does work with internet connections, however it is not fully docu-

mented and the implementation for Bluetooth and USB devices is not yet onished.

Please refer to the example programs.



SEE ALSO:           OPEN, CLOSE, SEND, RECEIVE



                                                            205




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        CONTINUE



Syntax:                CONT

                              CONTINUE



DESCRIPTION:



     This command has two dioeerent use cases. If used in direct mode, it continues

the execution of a program after interruption (e.g. with STOP).

     If used inside a SELECT/ENDSELECT block,  it branches to the line following

the next CASE or DEFAULT directive. If no CASE or DEFAULT statement is found,

it branches to ENDSELECT.



EXAMPLE:


INPUT  a
SELECT  a
CASE  1
   PRINT  1
   CONTINUE
CASE  2
   PRINT  "1  or  2"
CASE  3
   PRINT  3
DEFAULT
   PRINT  "default"
ENDSELECT



SEE ALSO:           STOP, SELECT, CASE, DEFAULT, BREAK



                                                            206




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Command:        COPYAREA



Syntax:                COPYAREA  x,y,w,h,xd,yd



DESCRIPTION:



     Copies a rectangular screen sections given by x,y,w,h to a destination at xd,yd.


                      x,y            top  left  corner  of  source  rectangle

                      w,h            width  &  height    "      "                "

                      xd,yd        destination  x  and  y  coordinates


This command is very fast compared to the GET and PUT commands because the

whole data transfer takes place on the X-client (this means on the screen directly

without datatransfer to the program).



SEE ALSO:           GET, PUT, GRAPHMODE



                                                            207




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           COS()



Syntax:                b=COS(x)

                              z#=COS(x#)



DESCRIPTION:



     Returns  the  Cosine  of  the  expression  in  radians.   Also  returns  the  complex

cosine of a complex expression. The complex cosine function is deoned as:

     cos(z#) := (exp(1i*z#)+exp(-1i*z#))/2



EXAMPLE:


PRINT  COS(0)           !  Result:  1
PRINT  COS(0+1i)       !  Result:  1.543080634815+0i



SEE ALSO:           SIN(), ASIN()



                             _________________________________*________________________________



Function:           COSH()



                                                            208




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Syntax:                b=COSH(x)

                              z#=COSH(x#)



DESCRIPTION:



     The cosh() function returns the hyperbolic cosine of x, which is deoned math-

ematically  as  (exp(x)+exp(-x))/2  Also  returns  the  complex  hyperbolic  cosine  of  a

complex number or expression.



SEE ALSO:           COS(), ACOSH(), EXP()



                                                            209




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           CRC()



Syntax:                !num-result?=CRC(t$[,oc])



DESCRIPTION:



     Calculates a 32 bit checksum on the given string. Optionally another checksum

can be passed as oc. If oc is passed, the checksum will be updated with the given

string.



SEE ALSO:           LEN(), HASH$()



                                                            210




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Function:           CRC16()



Syntax:                !num-result?=CRC(t$)



DESCRIPTION:



     Calculates a 16 bit checksum with CRC-CCITT on the given string.



SEE ALSO:           CRC(), HASH$()



                                                            211




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            CRSCOL,    CRSLIN



Syntax:                CRSCOL

                              CRSLIN



DESCRIPTION:



     Returns current cursor line and column.



SEE ALSO:           PRINT  AT()



                                                            212




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Variable:            CTIMER



Syntax:                CTIMER



DESCRIPTION:



     Returns  CPU-Clock  in  seconds.   This  timer  returns  the  amount  of  time  this

application  was  running.   It  is  most  useful  for  benchmark  applications  on  multi-

tasking environments.



     Comment:



     The UNIX standard allows for arbitrary values at the start of the program; sub-

tract the value returned from a CTIMER at the start of the program to get maximum

portability. It is also not guaranteed, that the values will not repeat itself. On a 32-bit

system this function will return the same value approximately every 72 minutes.



EXAMPLE:


    t=CTIMER
    FOR  i=0  TO  100000
       NOOP
    NEXT  i
    ref=(CTIMER-t)/100000
    print  "Ref=",str$(ref*1000,5,5);"  ms"



SEE ALSO:           TIMER, STIMER



                                                            213




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        CURVE



Syntax:                CURVE  x0,y0,x1,y1,x2,y2,x3,y3



DESCRIPTION:



     The CURVE command draws a cubic Bezier-curve.  The Bezier-curve starts at

x0,y0 and ends at x3,y3.  The curve at x0,y0 is at a tangent with a line from x0,y0

to x1,y1; and at x3,y3 is at a tangent with a line between x3,y3 and x2,y2.



SEE ALSO:           LINE, POLYLINE



                                                            214




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



Function:           CVA()



Syntax:                !array-result?=CVA(!string-expression?)



DESCRIPTION:



     Returns array reconstructed from the string. This function is the complement of

MKA$().



EXAMPLE:


a()=CVA(t$)



SEE ALSO:           ASC(), CVF(), CVL(), MKA$()



                                                            215




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           CVD()



Syntax:                !num-result?=CVD(!string-expression?)



DESCRIPTION:



     Returns the binary double value of the orst 8 characters of string. This function

is the complement of MKD$().



SEE ALSO:           ASC(), CVF(), CVL(), MKD$()



                             _________________________________*________________________________



Function:           CVF()



Syntax:                !num-result?=CVF(!string-expression?)



DESCRIPTION:



     Returns the binary AEoat value of the orst 4 characters of a string.  This function

is the complement of MKF$().



SEE ALSO:           ASC(), CVD(), CVL(), MKF$()



                                                            216




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.4.__C__



                             _________________________________*________________________________



Function:           CVI()



Syntax:                !num-result?=CVI(!string-expression?)



DESCRIPTION:



     Returns the binary integer value of the orst 2 characters of a string.  This func-

tion is the complement of MKI$().  Null string returns 0, For strings with only one

byte length the ASCII value of that charackter will be returned.



SEE ALSO:           ASC(), CVF(), CVL(), MKI$()



                             _________________________________*________________________________



Function:           CVL()



Syntax:                !num-result?=CVL(!string-expression?)



DESCRIPTION:



     Returns the binary long integer value of the orst 4 characters of a string.  This

function is the complement of MKL$(). Null string returns 0.



                                                            217




6.4. _C________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



SEE ALSO:           ASC(), CVF(), CVI(), MKL$()



                              _________________________________*________________________________



Function:           CVS()



Syntax:                !num-result?=CVS(!string-expression?)



DESCRIPTION:



     Returns the binary AEoat value of the orst 4 characters of a string.  This function

is the complement of MKS$().



SEE ALSO:           CVF(), MKS$()



                                                            218




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



6.5       D



                                                            219




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        DATA



Syntax:                DATA  [!const?[,!const?,  ...]]



DESCRIPTION:



     The DATA statement is used to hold information that may be read into variables

using the READ statement.  DATA items are a list of string or numeric constants

separated  by  commas  and  may  appear  anywhere  in  a  program.   No  comment

statement  may  follow  the  DATA  statement  on  the  same  line.   Items  are  read  in

the  order  they  appear  in  a  program.   RESTORE  will  set  the  pointer  back  to  the

beginning of the orst DATA statement.

     Alphanumeric string information in a DATA statement need not be enclosed in

quotes  if  the  orst  character  is  not  a  number,  math  sign  or  decimal  point.   Lead-

ing spaces will be ignored (unless in quotes).  DATA statements can be included

anywhere within a program and will be read in order.  Strings not in quotes will be

capitalzed.



SEE ALSO:           READ, RESTORE



                                                            220




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



Variable:            DATE$



Syntax:                d$=DATE$



DESCRIPTION:



     Returns the system date. The format is DD.MM.YYYY.



EXAMPLE:



PRINT  TIME$,DATE$    !  14:49:44           11.03.2014



SEE ALSO:           TIME$



                                                            221




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        DEC



Syntax:                DEC  !num-variable?



DESCRIPTION:



     Decrement Variable a. The result is a=a-1.



SEE ALSO:           INC



                                                            222




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



Function:           DECLOSE$()



Syntax:                a$=DECLOSE$(t$)



DESCRIPTION:



     Removes  enclosing  characters  from  string  t$.   De-closing  a  string,  following

pairs are recognized:


""  ,  ''  ,  !?  ,  ()  ,  --"  ,  [],  #`


If the string was not enclosed with one of these pairs of characters, the string will

be returned unmodioed.



EXAMPLE:


PRINT  DECLOSE$("[Hello]")
Result:  Hello



SEE ALSO:           ENCLOSE$()



                                                            223




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           DECRYPT$()



Syntax:                t$=DECRYPT$(message$,key$[,typ%])



DESCRIPTION:



     Decrypts a message, which has been encrypted with ENCRYPT$() before.



     Comment:



     This function is only available if libgcrypt was compiled in.



SEE ALSO:           ENCRYPT$()



                                                            224




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



Keyword:           DEFAULT



Syntax:                SELECT  ...  DEFAULT  ...  ENDSELECT



DESCRIPTION:



     DEFAULT is a label within the SELECT...ENDSELECT construction.

     See SELECT.



SEE ALSO:           SELECT



                                                            225




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        DEFFILL



Syntax:                DEFFILL  !col?,!style?,!pattern?



DESCRIPTION:



     Sets the oll color and oll pattern for solid graphics elements like PBOX, PCIR-

CLE etc...


        !col?          -  not  used  at  the  moment

        !style?      -  0=empty,  1=filled,  2=dots,  3=lines,  4=user  (not  used)

        !pattern?  -  24  dotted  and  12  lined  patterns  can  by  chosen.



SEE ALSO:           DEFLINE, DEFTEXT, PBOX



                                                            226




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



Command:        DEFFN



Syntax:                DEFFN  !func-name?[$][(!var  list?)]=!expression?



DESCRIPTION:



     This  statement  allows  the  user  to  deone  a  single  line  inline  function  that  can

thereafter be called by @name.  This is a handy way of adding functions not pro-

vided in the language. The expression may be a numeric or string expression and

must match the type the function name would assume if it was a variable name.

The name must adhere to variable name syntax.



EXAMPLES:


DEFFN  av(x,y)=SQR(x^2+y^2)
a=@av(b,c)    !  call  av
DEFFN  add$(a$,b$)=a$+b$



SEE ALSO:           FUNCTION, GOSUB



                                                            227




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        DEFLINE



Syntax:                DEFLINE  !style?,!thickness?[,!begin.s?,!end.s?]



DESCRIPTION:



     Sets line style, width and type of line start and end.


!style?          --  determines  the  style  of  line:

        1  Solid  line

        2  Long  dashed  line

        3  Dotted

        4  Dot-dashed

        5  Dashed

        6  Dash  dot  dot  ..

        7  Long  Dash  dot  dot  ..

  0x11-0xffffffff  User  defined  (not  used)



!thickness?  --  sets  line  width  in  pixels.  A  thickness  greater  than  or  equal  to

                             1  is  considered  a  wide  line,  and  the  value  0  is  a  special  case,

              considered  a  thin  line.  Wide  and  thin  lines  use  different  drawing

              algorithms.  Styles  and  different  start  and  end  symbols  are  only

              possible  for  wide  lines.  Also  it  is  possible  that  the  last  point

              of  the  line  is  treated  differently,  meaning,  sometimes  it  is  not

              drawn  with  wide  lines.



!begin.s?,!end.s?    --  The    start    and    end    symbols    are    defined

                           by    the      last  parameter,  and  can  be:

                    0  Square

    1  Arrow

    2  Round


The userdeoned style of the line deones a dash-pattern in the nibbles:



                                                            228




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



    0x11  means:  1  pixel  dash,  followed  by  1  pixel  gap.

    0x61  means:  1  pixel  dash,  followed  by  6  pixel  gap.

0x6133  means:  3  pixel  dash,  followed  by  3  pixel  gap,  followed  by  a

            1  pixel  dash,  followed  by  6  pixel  gap.



     Comment:



     Start and end symbols are not implemented in the framebuoeer (Android) ver-

sions (yet).



SEE ALSO:           LINE, DEFFILL



                                                            229




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        DEFMARK



Syntax:                DEFMARK  !color?,!style?,!size?



DESCRIPTION:



     Sets color, type and size of the corner points to be marked using the command

POLYMARK. The color value will be ignored.  The color of the points can be set

with the COLOR command.

     The following types are possible:


              0=point

              1=dot  (circle)

              2=plus  sign

              3=asterisk

              4=square

              5=cross

              6=hash

              8=filled  circle

              9=filled  square



SEE ALSO:           POLYMARK, DEFLINE, COLOR



                                                            230




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



Command:        DEFMOUSE



Syntax:                DEFMOUSE  !style?



DESCRIPTION:



     Chooses a pre-deoned mouse form. The following mouse forms are available :


        0=arrow  1=expanded  (rounded)  X

        2=busy  bee      3=hand,  pointing  finger

        4=open  hand    5=thin  crosswire

        6=thick  crosswire  7=bordered  crosswire


and about 100 other X-Window or operating system specioc symbols.



SEE ALSO:           HIDEM, SHOWM



                                                            231




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        DEFTEXT



Syntax:                DEFTEXT  flag%,width,height,angle



DESCRIPTION:



     Deones the style, rotation and size of the line font used by the LTEXT command.

COLOR and linestyles (e.g. thickness) can be set with COLOR and DEFLINE.


    flag%  :  text  style  -  0=monospace,  1=normal

    angle  :  rotation  in  degrees

    width  and  height  :  size  of  text  in  %

            (100%  corresponds  to  100  Pixel  font)



EXAMPLE:


DEFTEXT  0,0.05,0.1,0         !  Size  of  the  charackters  is  approx  10x5  pixels
LTEXT  100,100,"Hello"



SEE ALSO:           LTEXT, TEXT, COLOR, DEFLINE



                                                            232




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



Function:           DEG()



Syntax:                d=DEG(x)



DESCRIPTION:



     Converts x from radians to degrees.



EXAMPLE:


   PRINT  DEG(PI)           !  Result:  180



SEE ALSO:           RAD()



                                                            233




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        DELAY



Syntax:                DELAY  !num-of-seconds?



DESCRIPTION:



     Same as PAUSE. Delays program execution by !num-of-seconds? seconds.



SEE ALSO:           PAUSE



                                                            234




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



Function:           DET()



Syntax:                d=DET(a())



DESCRIPTION:



     Calculates the determinant of a (square) (two-dimensional) matrix a().

     The determinant provides important information about a matrix of coeOEcients of

a system of linear equations.  The system has a unique solution exactly when the

determinant is nonzero. When the determinant is zero there are either no solutions

or many solutions.



EXAMPLE:



a()=[3,7,3,0;0,2,-1,1;5,4,3,2;6,6,4,-1]
PRINT  DET(a())         !  Result:  105



SEE ALSO:           SOLVE(), INV()



                                                            235




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           DEVICE()



Syntax:                d=DEVICE(filename$)



DESCRIPTION:



     Returns the device id corresponding to a ole.



                                                            236




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



Command:        DIM



Syntax:                DIM  !arrayname?(!indexes?)[,!arrayn?(!ind?),...]



DESCRIPTION:



     Sets the dimensions of an array.  An array variable can store many values ad-

dessed by an index or a tuple of indicies. Arrays can be re-dimensioned any time.



     Comment:



     The argument determines the number of entries in the array.  The index count

starts with 0.  So DIM a(10) will produce the elements a(0), a(1), ...  a(8), and a(9)

(10 elements). Note: a(10) does not exist here!



EXAMPLES:


DIM  a(10)
DIM  b(100,100)
DIM  c$(20,30,405,6)



SEE ALSO:           ERASE, DIM?()



                             _________________________________*________________________________



                                                            237




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           DIM?()



Syntax:                !num-result?=DIM?(!array-name?())



DESCRIPTION:



     Determines the number of elements in an array.



EXAMPLE:


DIM  a(10,10)
PRINT  DIM?(A())       Result:  100



SEE ALSO:           DIM



                                                            238




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



Function:           DIR$()



Syntax:                p$=DIR$(0)



DESCRIPTION:



     DIR$()  returns  the  path  of  the  current  directory.  The  optional  argument  is  ig-

nored.



SEE ALSO:           CHDIR, ENV$()



                                                            239




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        DIV



Syntax:                DIV  var,n



DESCRIPTION:



     Divides the value of var by n. Same as var=var/n but faster.



SEE ALSO:           ADD, MUL, SUB



                             _________________________________*________________________________



Function:           DIV()



Syntax:                c=DIV(a,b)



DESCRIPTION:



     The function DIV() divides the orst value by second and returns the result.



SEE ALSO:           ADD(), MUL(), SUB()



                                                            240




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



Command:        DO



Syntax:                DO  ...  LOOP



DESCRIPTION:



     DO implements an unconditional loop.  The lines between the DO line and the

LOOP line form the loop body.  The unconditional DO...LOOP block simply loops

and the only way out is by EXIT IF or BREAK (or GOTO).



EXAMPLE:


           DO
              INPUT  a$
              EXIT  IF  a$=""
           LOOP



SEE ALSO:           LOOP, EXIT  IF, BREAK, WHILE



                                                            241




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Keyword:           DOWNTO



Syntax:                FOR  ...  DOWNTO  ...



DESCRIPTION:



     Used within a FOR..NEXT loop. DOWNTO indicates that the loop should count

backwards. e.g.:


FOR  c=100  DOWNTO  1


is the same as


FOR  c=100  TO  1  STEP  -1



EXAMPLE:


   FOR  i=10  DOWNTO  0
      PRINT  i
   NEXT  i



SEE ALSO:           FOR, TO, NEXT, STEP



                                                            242




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



Function:           DPEEK()



Syntax:                value%=DPEEK(adr%)



DESCRIPTION:



     Reads 2 bytes from address adr% (a word).



EXAMPLE:


   t$=MKI$(4711)
   PRINT  DPEEK(VARPTR(t$))



SEE ALSO:           PEEK(), LPEEK(), DPOKE, MKI$()



                             _________________________________*________________________________



Command:        DPOKE



Syntax:                DPOKE  adr%,value%



                                                            243




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



DESCRIPTION:



     Writes value% as a 2 byte word to address adr%.



EXAMPLE:


   t$=SPACE$(2)
   DPOKE  VARPTR(t$),4711
   PRINT  CVI(t$)



SEE ALSO:           PEEK(), LPEEK(), POKE, DPEEK(), CVI()



                                                            244




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.5.__D__



Command:        DRAW



Syntax:                DRAW  [x1,y1][TO  x2,y2][TO  x3,y3][TO  ...]



DESCRIPTION:



     Draws points and connects two or more points with straight lines.  DRAW x,y is

the same as PLOT x,y.  DRAW TO x,y connects the point to the last set point (set

by PLOT, LINE or DRAW).



SEE ALSO:           LINE, PLOT



                                                            245




6.5. _D________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        DUMP



Syntax:                DUMP  [t$][,#n]



DESCRIPTION:



     Query Information about stored Variables, names:


        DUMP                          --  Lists  all  used  variable  names

        DUMP  "@"                  --  list  of  functions  and  procedures

        DUMP  ":"                  --  list  of  all  labels

        DUMP  "#"                  --  list  of  open  Files

        DUMP  "K"                  --  list  of  all  X11-Basic  commands

        DUMP  "F"                  --  list  of  all  X11-Basic  functions


If a open ole channel is giveb, DUMP outputs to that ole.



EXAMPLE:


OPEN  "O",#1,"debug.txt"
PRINT  #1,"Variables:"
DUMP  "",#1
PRINT  #1,"Labels:"
DUMP  ":",#1
CLOSE  #1



SEE ALSO:           LIST, PLIST, HELP



                                                            246




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



6.6       E



                                                            247




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        ECHO



Syntax:                ECHO  ON

                              ECHO  OFF



DESCRIPTION:



     Switches the trace function on or ooe.  This causes each command to be listed

on the stdout.



SEE ALSO:           TRON, TROFF



                                                            248




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Command:        EDIT



Syntax:                EDIT



DESCRIPTION:



     EDIT invokes the standard editor (given by the environment variable $(EDITOR)

to edit the BASIC program in memory.

     The command invokes the following actions:


SAVE  "name.~~~"  writes  the  BASIC-program  into  a  temporary  file,

calls  the  editor  '$EDITOR'

                               waits  until  editor  is  closed

NEW                          clears  internal  values

LOAD  "name.~~~"  reads  the  BASIC-program  from  the  temporary  file.


You may want to SAVE the ole before using the EDIT command if the ole has not

yet been saved in order to choose a name at that occasion.  The default name is

"name.    ".  This command requires that the editor installed on your system does

not detach itself from the calling process or EDIT will not recognize any changes

(in that case, use LOAD to load the modioed source code).



SEE ALSO:           LOAD, SAVE



                                                            249




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        ELLIPSE



Syntax:                ELLIPSE  !x?,!y?,!a?,!b?  [,!w0?,!w1?]



DESCRIPTION:



     Draws an ellipse at !x?,!y?, having !a? as horizontal radius and !b? vertical

radius The optional angles !w0? and !w1? give start and end angles in degrees,

to create an elliptical arc.



SEE ALSO:           PELLIPSE, CIRCLE



                                                            250




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Command:        ELSE,    ELSE    IF



Syntax:                ELSE

                              ELSE  IF  !expression?



DESCRIPTION:



     ELSE IF !expression? introduces another condition block and the unqualioed

ELSE introduces the default condition block in a multi-line IF statement.



EXAMPLE:


          IF  (N=0)
                PRINT  "0"
          ELSE  IF  (N=1)
                PRINT  "1"
          ELSE
                PRINT  "Out  of  range"
          ENDIF



SEE ALSO:           IF, ENDIF



                                                            251




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           ENCLOSE$()



Syntax:                e$=ENCLOSE$(t$[,c$])



DESCRIPTION:



     Encloses a string.  With a character or a pair of characters.  The default pair is

"".



EXAMPLE:


          PRINT  enclose$("abc","()")   !    Result:  (abc)
          PRINT  enclose$("Hello","-")  !    Result:  -Hello-



SEE ALSO:           DECLOSE$()



                                                            252




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Function:           ENCRYPT$()



Syntax:                e$=ENCRYPT$(t$,key$[,typ%])



DESCRIPTION:



     This  Function  will  encrypt  a  string  with  a  given  key.   Typ%  specioes,  which

algorithm is used. If typ% is not specioed, the blowosh algorithm is used.

     The encrypted message can be decrypted again using DECRYPT$() and the

same  key  (or,  in  case  it  was  encrypted  with  a  public  key,  it  must  be  decrypted

with the corresponding private key.) The encrypted message has always the same

length than the original message.

     Following algorithms can be used:


Typ%=

        1        !  IDEA

                        2        !  3DES

                        3        !  CAST5

                        4        !  BLOWFISH

                        5        !  SAFER.SK128

                        6        !  DES.SK

                        7        !  AES

                        8        !  AES192

                        9        !  AES256

                      10        !  TWOFISH

                    301        !  ARCFOUR  Fully  compatible  with  RSA's  RC4  (tm).

                    302        !  DES  this  is  single  key  56  bit  DES.

                    303        !  TWOFISH128

                    304        !  SERPENT128

                    305        !  SERPENT192

                    306        !  SERPENT256

                    307        !  RFC2268.40  Ron's  Cipher  2  (40  bit).



                                                            253




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



                    308        !  RFC2268.128  Ron's  Cipher  2  (128  bit).

                    309        !  SEED        128  bit  cipher  described  in  RFC4269.

                    310        !  CAMELLIA128

                    311        !  CAMELLIA192

                    312        !  CAMELLIA256



                    501        !  RSA

                    516        !  ELG.E

                    517        !  DSA

                    520        !  ELG

                    801        !  ECDSA

                    802        !  ECDH



      Comment:



      This function is only available if libgcrypt was compiled in.



SEE ALSO:           COMPRESS$(), DECRYPT$()



                                                            254




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Command:        END



Syntax:                END



DESCRIPTION:



     END  terminates  program  execution.   The  interpreter  switches  to  interactive

mode.



SEE ALSO:           STOP, QUIT



                                                            255




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        ENDFUNCTION



Syntax:                ENDFUNCTION



DESCRIPTION:



     Terminates a user deoned function block. The function itself must return a value

with a RETURN command.



SEE ALSO:           FUNCTION, RETURN



                                                            256




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Command:        ENDIF



Syntax:                ENDIF



DESCRIPTION:



     ENDIF terminates a multi-line IF block.



SEE ALSO:           IF, ELSE, ELSE  IF



                                                            257




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        ENDPROCEDURE



Syntax:                ENDPROCEDURE



DESCRIPTION:



     Terminates a user deoned procedure. It has the same eoeect as RETURN.



SEE ALSO:           RETURN, ENDFUNCTION



                                                            258




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Command:        ENDSELECT



Syntax:                ENDSELECT



DESCRIPTION:



     Terminates a SELECT block.



SEE ALSO:           SELECT, DEFAULT, CASE



                                                            259




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        ENV$()



Syntax:                a$=ENV$(name$)



DESCRIPTION:



     ENV$() returns the current value of the specioed "environment variable".  Envi-

ronment variables are string variables maintained by the operating system. These

variables  typically  are  used  to  save  conoguration  information.  Use  the  SETENV

command to set the values of environment variables.



     Comment:



     In Unix and Unix-like systems,  the names of environment variables are case-

sensitive.



EXAMPLE:


           PRINT  ENV$("USER")   !   Result:  hoffmann
           PRINT  ENV$("HOST")   !   may  return  the  name  of  the  computer
           PRINT  ENV$("PWD")    !   may  return  the  current  working  directory



SEE ALSO:           SETENV



                                                            260




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Function:           EOF()



Syntax:                a=EOF(#!dev-number?)



DESCRIPTION:



     EOF()  checks  the  end-of-ole  status  of  a  ole  previously  opened  for  reading  by

the  OPEN  command.   It  returns  -1  (TRUE)  if  the  end  of  ole  has  been  reached,

otherwise null (FALSE).



EXAMPLE:


           OPEN  "I",#1,"filename"
           WHILE  NOT  EOF(#1)
                 LINEINPUT  #1,a$
           WEND
           CLOSE  #1



SEE ALSO:           OPEN



                                                            261




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Operator:           EQV



Syntax:                a=!num-expression?  EQV  !num-expression?



DESCRIPTION:



     The operator EQV (equivalence) produces a TRUE result only if the arguments

of both are either TRUE or both FALSE. (same as NOT(x XOR y)) and ((A IMP B)

AND (B IMP A)).



table:          A    ---    B    ---    A  EQV  B

                  -----+-----+----------

                    -1    ---  -1    ---      -1

                    -1    ---    0    ---        0

                      0    ---  -1    ---        0

                      0    ---    0    ---      -1



EXAMPLE:


             PRINT  BIN$((15  EQV  6)  and  15,4)
             Result:   0110



SEE ALSO:           TRUE, FALSE, NOT, XOR, IMP



                                                            262




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Command:        ERASE



Syntax:                ERASE  !array?()[,!array?(),!variable?...]



DESCRIPTION:



     un-DIMs an array and removes it from the internal variables.  Or remove a vari-

able out of the memory.  (This command need never be used in X11-Basic.  Don't

use it. An array can easily re-dimensioned with another DIM statement.)



SEE ALSO:           DIM, CLR



                                                            263




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            ERR



Syntax:                ERR



DESCRIPTION:



     Returns the error code of latest occurred error.



SEE ALSO:           ERROR, ERR$()



                                                            264




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Function:           ERR$()



Syntax:                a$=ERR$(!error-nr?)



DESCRIPTION:



     Returns, as a string containing the X11-Basic error message which belongs to

the error number.



EXAMPLE:



PRINT  "X11-Basic  Error  messages:"
FOR  i=0  TO  255
   PRINT  i,ERR$(i)
NEXT  i



SEE ALSO:           ERR



                                                            265




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        ERROR



Syntax:                ERROR  !error-number?



DESCRIPTION:



     ERROR simulates an error, i.e., displays the message appropriate for a given

error code or calls the error handler if one was installed via the ON ERROR com-

mand.  This command is helpful in writing ON ERROR GOSUB routines that can

identify errors for special treatment and then ERROR ERR (i.e.  default handling)

for all others.



EXAMPLE:



?  ERROR  245
Line  -1:  *  Timeout



SEE ALSO:           ON  ERROR  GOSUB, ERR



                                                            266




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Command:        EVAL



Syntax:                EVAL  a$



DESCRIPTION:



     Evaluate or execute X11-Basic command, which is in a$.



EXAMPLE:



b$="a=5"
a$="print  a"
EVAL  a$
EVAL  b$
EVAL  a$
&a$         !  short  form



SEE ALSO:           EVAL()



                             _________________________________*________________________________



Function:           EVAL()



                                                            267




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Syntax:                a=EVAL(b$)



DESCRIPTION:



     Evaluate expression, which is in b$.



EXAMPLE:



b$="sin(0.5*exp(0.001))"
result=EVAL(b$)

result=&b$       !  short  form



SEE ALSO:           EVAL



                                                            268




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Function:           EVEN()



Syntax:                e%=EVEN(!num-expression?)



DESCRIPTION:



     Returns true (-1) if the number is even, else false (0).



SEE ALSO:           ODD()



                                                            269




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        EVENT



Syntax:                EVENT  typ,[x,y,xr,yr,s,k,ks,t$,timestamp]



DESCRIPTION:



     EVENT waits for an event of the graphics i/o system.  This very powerful com-

mand can wait for a big variaty of dioeerent user events which can occur.

     Following events can be watched for:


-  A  mouse  button  is  pressed  or  released,

-  A  key  on  the  keyboard  is  pressed  or  released,

-  The  mouse  pointer  has  moved  to  a  new  position.

-  The  graphics  window  was  clicked  to  be  opened,

                    closed  or  iconified.


typ determines which of the events have occured:


typ=2          ---  key  pressed

typ=3          ---  key  released

typ=4          ---  mouse  button  pressed

typ=5          ---  mouse  button  released

typ=6          ---  mouse  motion  event

typ=10        ---  Window  move  event

typ=13        ---  Window  resize  event



x,y              ---  Mouse  position  relative  to  window

xr,yr          ---  Mouse  position  relative  to  screen  or

                                           relative  movement

s                  ---  State  of  the  Alt,  Caps,  Shift  keys

k                  ---  state  of  the  mouse  buttons  or  keycode

ks                ---  scancode  of  key

t$                ---  Character  of  pressed  key

timestamp  ---  timestamp  of  the  time  the  event  occured  (in  ms)



                                                            270




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



SEE ALSO:           KEYEVENT, MOUSEEVENT, MOTIONEVENT, EVENT?()



                                                            271




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        EVENT?()



Syntax:                a=EVENT?(mask%)



DESCRIPTION:



     Returns TRUE if a graphics event is pending which matches the types given by

mask.


        mask=              1  ---  key  press  event

        mask=              2  ---  key  release  event

        mask=              4  ---  mouse  button  press  event

        mask=              8  ---  mouse  button  release  event

        mask=        0x10  ---  mouse  enters  window  event

        mask=        0x20  ---  mouse  leaves  window  event

        mask=        0x40  ---  mouse  motion  event

        mask=  0x40000  ---  window  resize  events

        mask=0x200000  ---  window  focus  change  events



SEE ALSO:           EVENT, KEYEVENT, MOUSEEVENT, MOTIONEVENT, INP?()



                                                            272




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Command:        EVERY



Syntax:                EVERY  !seconds?,  !procedure?

                              EVERY  CONT

                              EVERY  STOP



DESCRIPTION:



     The  command  EVERY  causes  the  procedure  to  be  called  every  !seconds?

seconds.  Using EVERY STOP, the calling of a procedure can be prevented.  With

EVERY CONT this is again allowed.



     Comment:



     EVERY CONT and EVERY STOP are currently not implemented.  Please also

read the comments about AFTER.



EXAMPLE:



EVERY  1,progress
q=10000000
FOR  p=0  TO  q
   a=(1+a)/2
NEXT  p
AFTER  1,progress   !  To  stop  the  progress
PAUSE  3                !  will  be  interrupted  after  1  second
PRINT  "done  --?";a
END
PROCEDURE  progress
   PRINT  p/q;"%  done."
RETURN



                                                            273




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



SEE ALSO:           AFTER



                                                            274




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Command:        EXEC



Syntax:                EXEC  name$[,commandline$[,environment$]]

                              EXEC  action$[,data$[,extra$]]



DESCRIPTION:



     Calls an operating system service by name.  The behavior is dioeerent on dioeer-

ent operating systems.

     The  orst  argument  for  EXEC  is  the  name  of  a  ole  or  a  service  that  is  to  be

executed.

     If name$ is not an android-intent, the system searches for an executable ole if

the specioed olename does not contain a slash (/) character.

     The ole is sought in the colon-separated list of directory pathnames specioed in

the PATH environment variable.  If this variable isn't deoned, the path list defaults

to the current directory followed by the list of directories "/bin:/usr/bin".

     If the specioed olename includes a slash character, then PATH is ignored, and

the ole at the specioed pathname is executed.

     The olename must be either a binary executable, or a script starting with a line

of the form:


                      #!  interpreter  [optional-arg]


     In  case,  name$  is  not  an  android  intent,  EXEC  replaces  the  current  process

image with a new process image and execute it.  So EXEC will not return to the

X11-Basic program.

     The following string argument describes a list of one or more arguments avail-

able  to  the  executed  program.  The  Arguments  must  be  separated  by  a  newline

character (CHR$(10)).

     The  second  string  argument  allows  the  caller  to  specify  the  environment  of

the  executed  program.   The  environment  consists  of  a  list  of  strings  of  format

VAR=CONTENT, separated by a newline character (CHR$(10)).



                                                            275




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



      If this argument is not present, EXEC takes the environment for the new process

image from the calling process.

      On Android:

      If  the  name  starts  with  "android.intent",  a  special  operating  system  service,

called INTENT is called. Following intents are currently available:



android.intent.action.EDIT      ---  call  a  text  editor

android.intent.action.SEND      ---  call  email  client

android.intent.action.VIEW      ---  call  browser

android.intent.action.DIAL      ---  call  phone



      Execution will continue in X11-Basic as soon as the intent has onished.  If you

need a return value to ond out if the intent was successful, use EXEC().



EXAMPLE:


EXEC  "env","-u"+chr$(10)+"A","HOME=/tmp"+chr$(10)+"A=0"
EXEC  "android.intent.action.VIEW","
         "text/html:http://x11basic.sourceforge.net/"
EXEC  "android.intent.action.EDIT","text/plain:new.bas"
EXEC  "android.intent.action.SEND","message/rfc822:",  "
"android.intent.extra.EMAIL=my@email.adr"+chr$(10)+"
"android.intent.extra.SUBJECT=Hello"



SEE ALSO:           SYSTEM, EXEC(), CALL, SHELL



                             _________________________________*________________________________



Function:           EXEC()



                                                            276




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Syntax:                a%=EXEC(name$[,commandline$[,environment$]])

                              r%=EXEC(action$[,data$[,extra$]])



DESCRIPTION:



     Does the same as the command EXEC, but returns a return value. This is either

the value passed to the system exit() function or the result of an intent.



EXAMPLE:


a=EXEC("android.intent.action.EDIT","text/plain:new.bas")
if  a=-1
   print  "OK."
else  if  a=0
   print  "CANCELED"
endif
           b=EXEC("/usr/bin/busybox","/usr/bin/busybox"+chr$(10)+"-c","HOME=/tmp")
if  b!?0
   print  "program  exited  with  return  code:  ";b
endif



SEE ALSO:           CALL(), EXEC, SYSTEM$()



                                                            277




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           EXIST()



Syntax:                a=EXIST(filename$)



DESCRIPTION:



     Returns TRUE (-1) if the ole exists on the ole system.



SEE ALSO:           OPEN



                                                            278




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Command:        EXIT



Syntax:                EXIT



DESCRIPTION:



     EXIT will either exit a loop,  return from a procedure or subroutine,  quit a SE-

LECT/ENDSELECT  structure,  or  quit  the  interpreter.   WHILE,  REPEAT,  DO  and

FOR loops can be aborted prematurely with the EXIT command.  Here it has the

same function as BREAK. EXIT leaves the current (innermost) loop immediately.

Outside a loop, but insidde a procedure or function, that procedure or function is

left, like with RETURN. Outside any procedure or function or loop, or invoked from

the direct mode EXIT has the same eoeect like QUIT.



SEE ALSO:           EXIT  IF, BREAK, RETURN, QUIT



                                                            279




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        EXIT    IF



Syntax:                EXIT  IF  !expression?



DESCRIPTION:



     The innermost loop will be left if the expression is true.  WHILE, REPEAT, DO

and FOR loops can be aborted prematurely with the EXIT IF statement.  EXIT IF

leaves the current (innermost) loop immediately, if the expression after EXIT IF is

not FALSE (not null).



     Comment:



     EXIT IF cannot be used in direct mode.



SEE ALSO:           DO, WHILE, FOR, REPEAT, BREAK, IF, EXIT



                                                            280




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.6.__E__



Function:           EXP()



Syntax:                a=EXP(b)

                              a#=EXP(b#)



DESCRIPTION:



     EXP() returns the exponential value of its argument (e to the specioed power).



EXAMPLE:


          PRINT  EXP(1)         !  Result:  2.718281828459
          PRINT  EXP(1+1i)    !  Result:  (1.468693939916+2.287355287179i)



SEE ALSO:           LOG(), LN(), LOGB()



                                                            281




6.6. _E________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           EXPM1()



Syntax:                a=EXPM1(x)



DESCRIPTION:



     Returns a value equivalent to `exp(x)-1'. It is computed in a way that is accurate

even if the value of x is near zero ~ a case where `exp(x)-1' would be inaccurate

due to subtraction of two numbers that are nearly equal.



EXAMPLE:


          PRINT  EXPM1(1)      !      Result:  1.718281828459



SEE ALSO:           LOG1P(), EXP()



                                                            282




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



6.7       F



                                                            283




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           FACT()



Syntax:                a&=FACT(n%)



DESCRIPTION:



     Calculates the factorial (n!).  The factorial of a non-negative integer n, denoted

by n!, is the product of all positive integers less than or equal to n.  The value of 0!

is 1, according to the convention.



EXAMPLE:


PRINT  FACT(5)    !  Result:  120
PRINT  FACT(10)   !  Same  as  10*9*8*...*2*1
Result:  3628800
PRINT  FACT(50)  !  Same  as  50*49*48*...*2*1
Result:  30414093201713378043612608166064768844377641568960512000000000000



SEE ALSO:           COMBIN(), VARIAT(), GAMMA()



                                                            284




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Variable:            FALSE



Syntax:                FALSE



DESCRIPTION:



     Constant 0.  This is simply another way of expressing the value of a condition

when it is false and is equal to zero.



SEE ALSO:           TRUE



                                                            285




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            FATAL



Syntax:                FATAL



DESCRIPTION:



     Returns the value 0 or -1 according to the type of error.  On normal errors the

function returns 0.  The value -1 is returned on all errors where the address of the

last executed command is no longer known. In this case a RESUME is not possible

anymore.



     Comment:



     This variable is currently not used in X11-Basic.



SEE ALSO:           RESUME



                                                            286




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Command:        FFT



Syntax:                FFT  a()[,flag%]



DESCRIPTION:



     FFT calculates the discrete Fourier Transformation of a real periodic sequence

stored in the AEoat array a().  If AEag% is !?0 the back transform is calculated.  The

result replaces the contents of a(). The method used is most eOEcient (=fast) when

DIM?(a()) is a product of small primes.

     This transform is un-normalized since a call of FFT followed by a call of FFT ,-1

will multiply the input sequence by DIM?(a()).

     The  output  consists  of  an  array  with  the  Fourier  coeOEcients  as  follows:  For

n=DIM?(a()) even and for i = 0,...,n-1 a(i) = a(0)+(-1)^(i)*a(n-1) plus the sum from

k=2 to k=n/2 of

     2*a(2*k-1)*cos((k-1)*i*2*pi/n) -2*a(2*k)*sin((k-1)*i*2*pi/n)

     for n odd and for i = 0,...,n-1

     a(i) = a(0) plus the sum from k=2 to k=(n+1)/2 of

     2*a(2*k-1)*cos((k-1)*i*2*pi/n) -2*a(2*k)*sin((k-1)*i*2*pi/n)



     Comment:



     Two succeeding FFT (or FFT ,-1) calculations are faster if they use the same

size of the array.



EXAMPLE:



   l=2^10    !  It  is  faster  to  use  a  power  of  two
   DIM  a(l)
   FOR  i=0  TO  l-1



                                                            287




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



      a(i)=200/100*@si(3*i/512*2*pi)+i/100*sin(20*i/512*2*pi)
   NEXT  i
   SCOPE  a(),1,-10,300   !  Draw  the  function
   FFT  a()                    !  Do  the  Fourier  transformation
   '  Normalize
   FOR  i=0  TO  l-1
      a(i)=a(i)/SQRT(l)
   NEXT  i
   '  Clear  some  of  the  frequencies
   FOR  i=4  TO  86
      a(i)=0
   NEXT  i
   FFT  a(),-1                !  Do  a  back  transformation
   SCOPE  a(),0,-10/SQRT(l),300   !  Draw  the  result  (scaling=normalization)

   DEFFN  si(x)=x  mod  pi



SEE ALSO:           FFT()



                             _________________________________*________________________________



Function:           FFT



Syntax:                b()=FFT(a()[,flag%])



DESCRIPTION:



     FFT calculates the discrete Fourier Transformation of a real periodic sequence

stored in the AEoat array a(). If AEag% is !?0 the back transform is calculated. Unlike

the command FFT, FFT() returns an array with the Fourier transform leaving the

original array untouched.



SEE ALSO:           FFT()



                                                            288




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Function:           FIB()



Syntax:                w&=FIB(i%)



DESCRIPTION:



     Returns the i'th Fibonacci number.



     Comment:



     This function works only in the interpreter and only when used in a direct as-

signment to a big integer variable.



EXAMPLES:


   w&=FIB(100)   --?  Result:  354224848179261915075



SEE ALSO:           LUCNUM()



                                                            289




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           FILEEVENT$



Syntax:                t$=FILEEVENT$



DESCRIPTION:



     Returns a string with event information on watched oles and directories.  If the

string is empty, no events are pending. The events consist of 3 characters followed

by a blank and optionally followed by a olename.  The orst three characters have

the following meaning:

        1st:  "d"  means:  the  file  is  a  directory

        2nd:  "X"  created,  "O"  OPENed,  "C"  closed,  "M"  moved,

                  "D"  deleted

        3rd:  "r"  read,  "w"  write,  "a"  attributes  were  changed

When monitoring a directory, the events above can occur for oles in the directory,

in which case the name oeld in the returned string identioes the name of the ole

within the directory.



EXAMPLE:


       WATCH  "/tmp"
       DO
          a$=FILEEVENT$
          IF  LEN(a$)
             PRINT  a$
          ENDIF
       LOOP



SEE ALSO:           WATCH



                                                            290




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Command:        FILESELECT



Syntax:                FILESELECT  title$,path$,default$,file$



DESCRIPTION:



     Opens  a  oleselect  box  and  lets  the  user  browse  through  the  ole  system  and

select one ole.

     title$  gives  a  short  title  to  be  placed  in  the  oleselect  box.   Such  as  "Select  a

.DOC ole to open...".

     path$ if none specioed then the default path is assumed. The pathname should

include a complete path speciocation including a drive letter (except for UNIX ole

system), colon, path, and olemask.  The olemask may (and usually does) include

wildcard characters.

     default$ contains the name of the ole to appear in the selection line.  ("" for no

default).

     FILESELECT returns the selected olename (including path) in ole$. If CANCEL

is selected an empty string is returned.



EXAMPLE:


       FILESELECT  "LOAD  File","./*.dat","input.dat",file$



SEE ALSO:           XLOAD, XRUN, FSEL.INPUT()



                                                            291




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        FILL



Syntax:                FILL  x,y[,bc]



DESCRIPTION:



     Fills  a  bordered  area  with  a  color  commencing  at  the  co-ordinates  'x,y'.   If  a

border  color  (bc)  is  specioed,  the  oll  stops  at  boundaries  with  this  color.   If  no

border color is given, the oll will stop at any other color than the one of the starting

coordinate. The oll color can be chosen with the command COLOR.



     Comment:



     The FILL command does not work when the linewidth is set to anything other

than 1 pixel. Please use DEFLINE to set the linewidth back to 1 before using FILL

in that case.



SEE ALSO:           COLOR, DEFLINE



                                                            292




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Command:        FIT



Syntax:                FIT  x(),y(),yerr?,??[,??,??,??,??,??,??]



DESCRIPTION:



     Fits a user deoned function to a set of data points, also using errorbars in y.



     Comment:



     TODO: The command needs to be described.



SEE ALSO:           FIT.LINEAR, FIT.POLY



                                                            293




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        FIT.LINEAR



Syntax:                FIT.LINEAR  x(),y(),n%,a,b[,da,db,chi2,dy(),dx(),q]



DESCRIPTION:



     FIT.LINEAR  calculates  a  linear  regression  to  ot  a  straight  line  f(x)=a+b*x  to

the data x(),y().  n%=number of points.  The otted values are stored in a and b.  If

specioed, the uncertainty of a and b are stored in da,db and chi2.  Optional errors

of the datapoints in x and y can be given by dy(),dx(). In this case q has a meaning.



EXAMPLE:


n=400
DIM  x(n),y(n)
FOR  i=0  TO  n-1
   x(i)=(i+RANDOM(10))/400
   y(i)=(1*i+GASDEV(1)*20+50-i/30*i/30+(400-MOUSEY))/400
NEXT  i
FIT.LINEAR  x(),y(),,a,b,da,db,chi
PRINT  "chi2=";chi
da=da*SQRT(chi/(DIM?(x())-2))
db=db*SQRT(chi/(DIM?(x())-2))
           PRINT  a;"+/-";da
           PRINT  b;"+/-";db



SEE ALSO:           FIT, FIT.POLY



                                                            294




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Command:        FIT.POLY



Syntax:                FIT.POLY  x(),y(),dy(),n%,a(),m%



DESCRIPTION:



     FIT.POLY ots a polynom of order m% to n% datapoints given by x() and y().  If

present, dy() specioes the errors in y.  The polynomial coeOEcients are returned in

a() such that


f(x)=a(0)+a(1)*x+a(2)*x^2+...



     Comment:



     For  higher  orders  m%?3  of  the  polynom,  the  range  of  x()  must  be  small  (in

the order of 1) otherwise the algorithm can become unstable because of the high

powers.

     No information about the quality of the ot is returned.



SEE ALSO:           FIT, FIT.LINEAR, SOLVE



                                                            295




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           FIX()



Syntax:                a=FIX(x)



DESCRIPTION:



     Returns the integer of x after it has been rounded. FIX is identical to the function

TRUNC and complements FRAC.



SEE ALSO:           INT(), TRUNC(), FRAC(), ROUND()



                                                            296




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Function:           FLOOR()



Syntax:                a=FLOOR(x)



DESCRIPTION:



     Round x down to the nearest integer.



SEE ALSO:           INT(), FIX()



                                                            297




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        FLUSH



Syntax:                FLUSH  [#!device-name?]



DESCRIPTION:



     Flushes  the  output  to  the  ole  or  console.   Usually  a  line  is  printed  when  the

newline character is encountered. To enforce output of everything which has been

printed so far use FLUSH.



SEE ALSO:           PRINT



                                                            298




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Command:        FOR



Syntax:                FOR  !var?=!sexpr?  TO  !texpr?  [STEP  !incr?]

                              FOR  !var?=!sexpr?  DOWNTO  !texpr?  [STEP  !incr?]



DESCRIPTION:



     FOR initiates a FOR...NEXT loop with the specioed variable !var? initially set to

!sexpr? and incrementing in !incr? steps (default is 1).  The statements between

FOR and NEXT are repeated until the variable value reaches or steps over !texpr?.



     Comment:



     The body of the FOR loop is excecuted always at least once.



EXAMPLE:


          FOR  n=2  TO  0  STEP  -1
             PRINT  n,
          NEXT  n
          RESULT:  2   1   0



SEE ALSO:           NEXT, DOWNTO, STEP



                                                            299




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           FORK()



Syntax:                a%=FORK()



DESCRIPTION:



     FORK() creates a child process of the running task (usually the X11-Basic in-

terpreter with the Basic program). After the fork, both tasks will be run in parallel.

     On success, the PID of the child process is returned in the parent's thread of

execution, and a 0 is returned in the child's thread of execution. On failure, a -1 will

be returned in the parent's context, no child process will be created.



EXAMPLE:


a=FORK()
IF  a=-1
   PRINT  "error"
   QUIT
ELSE  IF  a=0
   PRINT  "I  am  child"
ELSE
   PRINT  "I  am  parent.  My  child  is  PID=";a
ENDIF



SEE ALSO:           SPAWN



                                                            300




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Function:           FORM.ALERT()



Syntax:                ret=FORM.ALERT(button,string$)



DESCRIPTION:



     This function creates an alert box, and returns the number of the button pressed.

Unlike ALERT, it is not possible to use text inputs here.

     The parameters have the following meaning:


  button    =  number  of  the  default  button  (0=  none).

  string$  =  string  defining  the  message  in  the  alert.

                      It  needs  to  have  a  special  format:

                      "[i][Message][Buttons]"


Where i is the required alert symbol number.  Lines and buttons are separated by

the "---" character. ~? see ALERT.

     FORM.ALERT returns the number of the selected Button.



EXAMPLE:


~FORM.ALERT(1,"[0][This  is  my  message!][OK]")



SEE ALSO:           ALERT



                                                            301




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           FORM.CENTER()



Syntax:                ~FORM.CENTER(tree%,x,y,w,h)



DESCRIPTION:



     Centers the object tree and returns its coordinates.

     tree% is the address of the object tree.

     OUTPUTS: x,y coordinates of top left corner w,h form width and height.  The

returned value can safely be ignored.



EXAMPLE:



PROCEDURE  info
   LOCAL  adr%,x,y,w,h,ret%
   adr%=RSRC.GADDR(0,2)
   ~FORM.CENTER(adr%,x,y,w,h)
   ~FORM.DIAL(0,x,y,w,h,x,y,w,h)
   ~FORM.DIAL(1,x,y,w,h,x,y,w,h)
   ~OBJC.DRAW(adr%,0,-1,0,0)
   ret%=FORM.DO(adr%)
   ~FORM.DIAL(2,x,y,w,h,x,y,w,h)
   ~FORM.DIAL(3,x,y,w,h,x,y,w,h)
   IF  ret%=35
      DPOKE  adr%+ret%*24+10,0
   ENDIF
RETURN



SEE ALSO:           OBJC.DRAW()



                                                            302




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Function:           FORM.DIAL()



Syntax:                ret%=FORM.DIAL(flag,x1,y1,w1,h1,x2,y2,w2,h2)



DESCRIPTION:



     Release (or reserve) a rectangular screen area and draw an expanding/shrinking

rectangle. Returns 0 if an error occurred.


flag=          function

          0                  reserve  a  display  area.

          1                  draw  expanding  box.

          2                  draw  shrinking  box.

          3                  release  reserved  display  area.

x1,y1    top  left  corner  of  rectangle  at  min  size

w1,h1    width  &  height    "        "              "    "        "

x2,y2    top  left  corner  of  rectangle  at  max  size

w2,h2    width  &  height      "        "            "    "        "



EXAMPLE:


PROCEDURE  show.tabelle
   LOCAL  ox,oy
   ox=(bx+bw-532)/2
   oy=(by+bh-242)/2
   ~FORM.DIAL(0,260,20,30,20,ox,oy,532,242)
   ~FORM.DIAL(1,260,20,30,20,ox,oy,532,242)
   @tabelle(ox,oy,532,242)
   MOUSEEVENT
   ~FORM.DIAL(2,260,20,30,20,ox,oy,532,242)
   ~FORM.DIAL(3,260,20,30,20,ox,oy,532,242)



                                                            303




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



RETURN



SEE ALSO:           SGET, SPUT, GET, PUT, COPYAREA



                                                            304




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Function:           FORM.DO()



Syntax:                ret%=FORM.DO(tree%[,obj%])



DESCRIPTION:



     FORM.DO() manages an object tree given by the address tree% and interacts

with the user until an object with EXIT or TOUCHEXIT status is clicked on.

     FORM.DO returns the number of the object whose clicking or double clicking

caused the function to end. If it was a double click, bit 15 will be set.

     The optional parameter obj% specioes the number of the orst editable oeld ob-

ject (if there is one).



EXAMPLE:


PROCEDURE  info
   LOCAL  adr%,x,y,w,h,ret%
   adr%=RSRC.GADDR(0,2)
   ~FORM.CENTER(adr%,x,y,w,h)
   ~FORM.DIAL(0,x,y,w,h,x,y,w,h)
   ~FORM.DIAL(1,x,y,w,h,x,y,w,h)
   ~OBJC.DRAW(adr%,0,-1,0,0)
   ret%=FORM.DO(adr%)
   ~FORM.DIAL(2,x,y,w,h,x,y,w,h)
   ~FORM.DIAL(3,x,y,w,h,x,y,w,h)
   IF  ret%=35
      DPOKE  adr%+ret%*24+10,0
   ENDIF
RETURN



SEE ALSO:           OBJC.DRAW()



                                                            305




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           FRAC()



Syntax:                a=FRAC(b)



DESCRIPTION:



     FRAC() returns the fractional part of its argument.



EXAMPLE:



           PRINT  FRAC(-1.234)
           Result:  -0.234



SEE ALSO:           INT(), CINT(), TRUNC(), ROUND()



                                                            306




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Command:        FREE



Syntax:                FREE  adr%



DESCRIPTION:



     Frees a previously allocated memory block.



SEE ALSO:           MALLOC()



                                                            307




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           FREEFILE()



Syntax:                a%=FREEFILE()



DESCRIPTION:



     FREEFILE()  returns  the  orst  free  olenumber  available  or  -1  on  error.   the  ole

numbers can be used together with other ole functions like OPEN, LINK etc...



SEE ALSO:           OPEN



                                                            308




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Function:           FSFIRST$()



Syntax:                a$=FSFIRST$(path$[,pattern$,attr$])



DESCRIPTION:



     FSFIRST$()  searches  for  the  orst  ole  in  a  olesystem  of  a  given  path  path$,

given  match  pattern  pattern$  and  given  attributes.   pattern$  can  be  a  ole  name

mask; default is "*". attr$ can be:


      "d"  only  list  directories,

      "a"  also  list  hidden  files,

      "f"  list  regular  files,

      "u"  list  usb  devices,

      "b"  list  visible  bluetooth  devices  nearby.


     The attributes "d" and "f" can be combined ("df") so directories as well as normal

oles are listed. If no attributes are given, the default is "df".

     If found, the olename and attributes are returned in a$.  If no ole can be found,

an  empty  string  is  returned.   When  path$  is  empty,  an  empty  string  is  returned.

Otherwise the returned string consists of two words. E.g. "- olename.dat". The orst

word lists the attributes, the second word is the olename. Attributes can be "d" is a

directory, "s" symbolic link, "-" a regular ole.



EXAMPLE:


          '  list  files  and  directories  in  /tmp/
          a$=FSFIRST$("/tmp","*.dat")
          WHILE  LEN(a$)
             PRINT  WORD$(a$,2)
             IF  LEFT$(a$)="d"
                PRINT  "is  a  directory."
             ENDIF



                                                            309




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



             a$=FSNEXT$()
          WEND



Comment:



     FSFIRST$() can also be used to scan for BLUETOOTH or USB devices. When

scanning  USB  or  Bluetooth  devices  additional  information  is  returned.   The  at-

tributes "u" and "b" cannot be combined with other attributes.



EXAMPLE:


         '  Scan  for  USB  devies  around:
         a$=FSFIRST$("","*","u")
         WHILE  LEN(a$)
           PRINT  a$
           @decode(a$)
           a$=FSNEXT$()
         WEND
         QUIT
         PROCEDURE  decode(a$)
           PRINT  "  USB  bus/device:                ";WORD$(a$,1)
           PRINT  "  USB  vendor-ID/product-ID:  ";WORD$(a$,2)
           PRINT  "  Manufacturer:                  ";WORD$(a$,3)
           PRINT  "  Product:                         ";WORD$(a$,4)
           PRINT  "  Serial-Nr:                      ";WORD$(a$,5)
           PRINT  "  Number  of  configurations:  ";WORD$(a$,6)
         RETURN



EXAMPLE:


'  Scan  for  bluetooth  devies  around:
a$=FSFIRST$("","*","b")
WHILE  LEN(a$)
   PRINT  a$
   PRINT  "Adress:  ";WORD$(a$,1)
   PRINT  "Name:    ";WORD$(a$,1)
   a$=FSNEXT$()



                                                            310




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



WEND



SEE ALSO:           FSNEXT$()



                                                            311




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           FSNEXT$()



Syntax:                a$=FSNEXT$()



DESCRIPTION:



     FSNEXT$() searches for the next ole in the olesystem specioed by FSFIRST$().

     When no more oles can be found, an empty string is returned.  Otherwise the

returned string has the same meaning as the one returned by FSFIRST().



EXAMPLE:


          a$=FSFIRST$("/tmp","*.dat")
          WHILE  LEN(a$)
             PRINT  WORD$(a$,2)
             IF  LEFT$(a$)="d"
                PRINT  "is  a  directory."
             ENDIF
             a$=FSNEXT$()
          WEND



SEE ALSO:           FSFIRST$()



                                                            312




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



Command:        FULLW



Syntax:                FULLW  [[#]n]



DESCRIPTION:



     Enlarges the window with the number n to full screen size.



SEE ALSO:           OPENW, CLOSEW, MOVEW, SIZEW, TOPW, BOTTOMW



                                                            313




6.7. _F________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        FUNCTION



Syntax:                FUNCTION  !name?[$][(!expression?  [,  ...])]



DESCRIPTION:



     FUNCTION starts a user-deoned multi-line function that calculates and returns

a value from an optional list of parameters.  The FUNCTION is called by using the

function  name  preceded  by  a  @  in  an  expression.  The  function  return  type  can

either be a numerical value or a string.  In the latter case, the function name must

end with the "$" precision qualioer. (No Integer type functions with % are allowed.)

     A FUNCTION returns a result with the RETURN command inside the function.

In a function, RETURN can be used several times, with IF or the like.  A function

cannot be terminated without a RETURN command being before the ENDFUNC

command.  In a function name ending with the $ character the function returns a

string result.

     All variables declared inside the FUNCTION block are global variables unless

you declare them as local with the LOCAL command.  The FUNCTION name may

be followed by a list of parameter variables representing the values and variables in

the calling line. Variables in the calling line reach the FUNCTION "by-value" unless

the VAR keyword is used in the calling line.  In that case,  the variable is passed

"by-reference"  to  the  FUNCTION  so  that  the  FUNCTION  "gets"  the  variable  and

not only its value.  Variables passed "by-reference" can be changed by the FUNC-

TION. The FUNCTION block is terminated by an ENDFUNCTION statement which

resumes execution of the calling expression. Unlike a PROCEDURE subroutine, a

FUNCTION must return a value.



                                                            314




CHAPTER_6.__COMMAND_REFERENCE_______________________________________________________________________________________6.7.__F_



EXAMPLE:


FUNCTION  theta(x,a)
   IF  x?a
      RETURN  0
   ELSE
      RETURN  a
   ENDIF
ENDFUNCTION



SEE ALSO:           ENDFUNCTION, RETURN, DEFFN, LOCAL, PROCEDURE



                                                            315




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



6.8       G



                                                            316




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



Function:           GAMMA()



Syntax:                b=GAMMA(a)



DESCRIPTION:



     Returns a value given by the gamma function.  The Gamma function is deoned

by


    GAMMA(x)  =  integral  from  0  to  infinity  of  t^(x-1)  e^-t  dt


It  is  deoned  for  every  real  number  except  for  non-positive  integers.    For  non-

negative integral m one has


    GAMMA(m+1)  =  m!


and, more generally, for all x:


    GAMMA(x+1)  =  x  *  GAMMA(x)


Furthermore, the following is valid for all values of x outside the poles:


    GAMMA(x)*GAMMA(1-x)=PI/SIN(PI*x)



EXAMPLE:


      PRINT  GAMMA(4)      !  Result:  6
      PRINT  GAMMA(0)      !  Result:  inf



SEE ALSO:           SIN(), COS(), LGAMMA()



                                                            317




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           GASDEV()



Syntax:                b=GASDEV(seed)



DESCRIPTION:



     Returns a random number which is Gauss distributed. The numbers range from

minus inonity to inonity but values around 0 are much more likely. The argument is

taken as a seed for the random generator.



SEE ALSO:           RND()



                                                            318




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



Function:           GCD()



Syntax:                c&=GCD(a&,b&)



DESCRIPTION:



     Returns the greatest common divisor of a and b.  The result is always positive

even  if  one  or  both  input  operands  are  negative.  Except  if  both  inputs  are  zero;

then this function deones GCD(0,0)=0.



EXAMPLE:


PRINT  GCD(120,200000)    !  Result:  40



SEE ALSO:           LCM()



                                                            319




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        GET



Syntax:                GET  x,y,w,h,var$[,bcolor]



DESCRIPTION:



     GET puts a section of the graphic window or screen into a string variable (x,y,w,h

deone a rectangular portion of the screen).  The coordinates must not lay outside

of the screen.  If the parameter bcolor is given, this color will be used as a trans-

parency color to the bitmap.  If no bcolor is given, no transparency will be created.

The stored graphic can be put back on the screen with PUT.



     Comment:



     The content of the string is bitmapdata.  If saved into a ole, the File will be in a

common ole format (currently .BMP 32bit-RGBA).



EXAMPLE:


      GET  100,100,20,20,t$
      PUT  200,200,t$           !  Put  that  portion  at  a  different  position



SEE ALSO:           PUT, COPY.AREA, SGET



                                                            320




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



Function:           GET.COLOR()



Syntax:                col=GET.COLOR(r,g,b)



DESCRIPTION:



     GET.COLOR() returns a color number for the specioed color.  The rgb-values

range from 0 (dark) to 65535 (bright). The returned number depends on the screen

depth. For 8 bit palette systems a color cell is allocated or if there is no free cell, a

color is chosen which is most similar to the specioed one. The color numbers may

be passed to the COLOR command.



     Comment:



     GET.COLOR does not support the rgba formt. Instead COLOR.RGB() should

be used.



EXAMPLE:


yellow=GET.COLOR(65535,65535,0)
COLOR  yellow



Comment:

This function should not be used anymore. Use COLOR.RGB() instead.



SEE ALSO:           COLOR, COLOR.RGB()



                                                            321




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        GET.GEOMETRY



Syntax:                GET.GEOMETRY  n,x%,y%,w%,h%



DESCRIPTION:



     GET.GEOMETRY returns the size of the window or screen.  n is the number

of the window.  x%,y%,w%,h% take the return values.  Usually only w% (width in

pixels) and h% (height in pixels) are of interest. The window needed to be opened

before this command can be used. A SHOWPAGE will make sure, that the screen

or window is allocated.



     Comment:



     If this command is used on Android as one of the very orst commands, a PAUSE

0.04 before will make sure, that the screen of the app has settled before the dimen-

sions are taken.



EXAMPLE:


SHOWPAGE
GET.GEOMETRY  ,x,y,w,h



SEE ALSO:           SHOWPAGE



                                                            322




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



Command:        GET.LOCATION



Syntax:                GET.LOCATION  lat,lon,alt[,bea,acc,spd,tim[,p$]]



DESCRIPTION:



     GET.LOCATION  returns  various  data  from  the  location  device.  The  location

device  can  be  a  GPS  or  any  other  service  which  returns  geo-information.   The

GPS needs to be turned on with GPS ON before.

     Return values:


    lat  --  lattitude  in  degrees

    lon  --  longitude  in  degrees

    alt  --  altitude  in  meters

    bea  --  bearing

    acc  --  accuracy

    spd  --  speed

    tim  --  time

    p$    --  provider  name



     Comment:



     Works only on Android devices.



EXAMPLE:


GET.LOCATION  x,y,a



                                                            323




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



SEE ALSO:           GPS, GPS.LON, GPS.LAT, GPS.ALT



                                                            324




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



Command:        GET.SCREENSIZE



Syntax:                GET.SCREENSIZE  x%,y%,w%,h%



DESCRIPTION:



     GET.SCREENSIZE  returns  the  size  of  the  screen.  This  is  the  area  where  a

window can be placed.



EXAMPLE:


GET.SCREENSIZE  x,y,w,h



SEE ALSO:           GET.GEOMETRY, MOVEW



                                                            325




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           GLOB()



Syntax:                a=GLOB(name$,pattern$[,flags%])



DESCRIPTION:



     GLOB()  checks  if  name$  matches  the  wildcard  pattern  pattern$  and  gives  -1

(TRUE) in that case, else 0 (FALSE).

     A wildcard pattern typically contains one or more of the characters "?", "*" or "[".

     * A "?" (not between brackets) matches any single character.

     * A "*" (not between brackets) matches any string, including the empty string.

     * An expression "[...]" where the orst character after the leading "[" is not an "!"

matches a single character, namely any of the characters enclosed by the brackets.

The string enclosed by the brackets cannot be empty; therefore "]" can be allowed

between the brackets, provided that it is the orst character.  (Thus, "[][!]" matches

the three characters "[", "]" and "!".)

     There  is  one  special  convention:   two  characters  separated  by  "-"  denote  a

range.  (Thus, "[A-Fa-f0-9]" is equivalent to "[ABCDEFabcdef0123456789]".)  One

may include "-" in its literal meaning by making it the orst or last character between

the brackets.  (Thus,  "[]-]" matches just the two characters "]" and "-",  and "[~0]"

matches the three characters "-", ".", "0", since "/" cannot be matched.)

     An expression "[!...]" matches a single character, namely any character that is

not  matched  by  the  expression  obtained  by  removing  the  orst  "!"  from  it.  (Thus,

"[!]a-]" matches any single character except "]", "a" and "-".)

     One can remove the special meaning of "?", "*" and "[" by preceding them by

a backslash, or by enclosing them in quotes.  Between brackets these characters

stand for themselves. Thus,


                "[[?*"]"


matches the four characters "[", "?", "*" and backslash.

     The kind of check can be specioed with the AEags% parameter.  The AEags% pa-

rameter can be a combination (+ or OR) of following values with following meaning:



                                                            326




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



flags%

    0    --  default,  no  extras

    1    --  name$  is  treated  as  a  filename,  this  means  that  a  slash

                in  the  string  is  mathced  only  with  a  slash  in  the

                pattern  and  not  by  an  asterisk  or  a  questionmark.

    2    --  treat  backslashes  as  special  escape  characters

    4    --  special  treatment  of  '.',  this  means  a  leading  period  in

                the  string  has  to  be  matched  exactly  by  a  period  in  the

                pattern.

    8    --  just  check  path  of  file  name  name$,  this  means  the

                pattern  is  considered  to  be  matched  if  it  matches  an

                initial  segment  of  the  string  which  is  followed  by  a

                slash.

  16    --  The  pattern  is  matched  case-insensitively.


If the AEag%=1 is set, the pattern matching is applied on each of the components of

a pathname separately. In this case a '/' in a pathname cannot be matched by a '?'

or '*' wildcard, or by a range like "[.-0]".

     If  the  AEag%=1+4  is  set,  if  a  olename  starts  with  a  '.',  this  character  must  be

matched explicitly.



EXAMPLES:



GLOB("abcd","abc?")             Result:  -1
GLOB("abcd","*")                            -1
GLOB("abc","ab??")                           0
GLOB("SA33333","*a[0-9]*",16)       -1
GLOB("folder/testme.bas","*.bas",1)   0
GLOB(".testme.bas","*.bas",1)          -1
GLOB(".testme.bas","*.bas",1+4)         0
GLOB(".testme.bas",".*.bas",1+4)      -1



SEE ALSO:           INSTR(), RINSTR(), SPLIT, REGEXP(), MATCH()



                                                            327




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        GOSUB    ABBREV.    @



Syntax:                GOSUB  !procedure-name?[(!parameterlist?)]



DESCRIPTION:



     GOSUB  initiates  a  jump  to  the  procedure  specioed  after  GOSUB.  The  code

reached that way must end with a RETURN statement which returns control to the

calling line.

     !parameterlist? contains expressions which are passed by value to local vari-

ables to the procedure.  Variables can also be passed by reference (see the VAR

statement). It is possible to call further procedures whilst in a procedure. It is even

possible to call the procedure one is in at the time (recursive call).



EXAMPLES:


GOSUB  testproc
@calcvac(12,s,4,t$)



SEE ALSO:           PROCEDURE, RETURN, SPAWN, GOTO, EVERY, AFTER, VAR



                                                            328




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



Command:        GOTO



Syntax:                GOTO  !label-name?



DESCRIPTION:



     Allows an unconditional jump to a label.

     A label must be deoned at the beginning of a line and must end in a colon.



     Comment:



     You should not jump into a procedure or FOR-NEXT loop.  If you need to jump

out of a loop it is better to use BREAK or EXIT IF.



EXAMPLE:


GOTO  here
PRINT  "never"
here:
PRINT  "ever"



SEE ALSO:           GOSUB, BREAK, EXIT  IF



                                                            329




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        GPRINT



Syntax:                GPRINT  [[AT(),TAB(),SPC(),COLOR()]a$--;',"

                              GPRINT  [a$;b;const;USING;...--;',"]



DESCRIPTION:



     The GPRINT statement writes all its arguments to the graphic window.  It uses

the same syntax as PRINT. Unlike PRINT the output goes to the graphic window,

where a VT100-Terminal is emulated.



     Comment:



     On  Android  PRINT  and  GPRINT  share  the  same  output  screen,  but  use  dif-

ferent  terminals.   This  can  lead  to  a  mixture  of  characters  on  the  screen.   Here

do not use both, PRINT and GPRINT. The text size of the GPRINT output can be

inAEuenced by SETFONT.

     There  is  no  INPUT  for  GPRINT.  You  would  have  to  program  it  yourself  using

KEYEVENT.



EXAMPLE:



   GPRINT  CHR$(27);"[2J";    !  Clear  the  graphics  screen  (like  CLS  for  PRINT)
   GPRINT  AT(1,1);"This  is  a  demo:  ";1.23456  USING  "##.##"
   GPRINT  "some  more  ...";
   GPRINT  "  and  more...";
   GPRINT  COLOR(43,35);"  even  color  does  work!"
   SHOWPAGE



                                                            330




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



SEE ALSO:           PRINT, TEXT, SETFONT



                                                            331




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        GPIO



Syntax:                GPIO  n,v



DESCRIPTION:



     Sets the nth GPIO to output direction and value v.

     The pin numbers follow the wirig Pi pin numbering



      n=0  --?GPIO  17

      1                      18

      2                      27

      3                      22

      4                      23

      5                      24

      6                      25

      7                      4

      8                      2

      9                      3

      10                    8

      11                    7

      12                    10

      13                      9

      14                    11

      15                    14

      16                    15



      21                    5

      22                    6

      23                  13

      24                  19

      25                  26



                                                            332




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



      26                  12

      27                  16

      28                  20

      29                  21

      30                  0

      31                  1



SEE ALSO:           GPIO?, GPIO()



                                                            333




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            GPIO?



Syntax:                a=GPIO?



DESCRIPTION:



     This system variable GPIO? is 0 if no general purpose input/output (GPIO) in-

terface  is  a  available  on  this  hardware  platform,  otherwise  the  number  of  usable

GPIO  channels  is  returned.   This  variable  is  useful  to  detect,  if  the  program  is

running on a Raspberry Pi.



SEE ALSO:           GPS?, SENSOR?, GPIO.SET, GPIO()



                                                            334




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



Function:           GPIO()



Syntax:                a=GPIO(n)



DESCRIPTION:



     Readout  the  n-th  value  of  the  general  purpose  input/output  (GPIO)  channel.

Usually the return values are 0 or 1. The channel is set to input.



SEE ALSO:           GPS, SENSOR, SENSOR?, ANDROID?, GPIO



                                                            335




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        GPS



Syntax:                GPS  ON

                              GPS  OFF



DESCRIPTION:



     Switches the GPS (Global positioning System receiver) on or ooe.



     Comment:



     If switched on this usually drains more power from the battery.



SEE ALSO:           GPS?, GPS.ALT, GPS.LAT, GPS.LON, SENSOR



                                                            336




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



Variable:            GPS?



Syntax:                a=GPS?



DESCRIPTION:



     This system variable is 0 (FALSE) if no gps receiver is available on this hardware

platform.



SEE ALSO:           GPS, GPS.ALT, GPS.LAT, GPS.LON, SENSOR



                                                            337




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            GPS.ALT



Syntax:                a=GPS.ALT



DESCRIPTION:



     This system variable returns the measured altitude from the GPS in meters.



SEE ALSO:           GPS, GPS.LAT, GPS.LON



                             _________________________________*________________________________



Variable:            GPS.LAT



Syntax:                a=GPS.LAT



DESCRIPTION:



     This system variable returns the measured latitude from the GPS in degrees.



SEE ALSO:           GPS, GPS.ALT, GPS.LON



                             _________________________________*________________________________



                                                            338




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



Variable:            GPS.LON



Syntax:                a=GPS.LON



DESCRIPTION:



     This system variable returns the measured longitude from the GPS in degrees.



SEE ALSO:           GPS, GPS.ALT, GPS.LAT



                                                            339




6.8. _G________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        GRAPHMODE



Syntax:                GRAPHMODE  n



DESCRIPTION:



     Sets the graphic mode:


      n=0          default

      n=1          replace

      n=2          transparent

      n=3          xor

      n=4          reverse  transparent



     Comment:



     GRAPHMODE  does  not  yet  work  on  all  implmentations  of  X11-Basic.  And  it

has limited eoeects (usually only on TEXT and GPRINT).



SEE ALSO:           GOLOR.RGB(), TEXT, GPRINT



                                                            340




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.8.__G__



Function:           GRAY()



Syntax:                a%=GRAY(!num-expression?)



DESCRIPTION:



     This function calculates the Gray-code of a given positive integer number. If the

number is negative, the inverse Graycode is calculated.



EXAMPLE:


PRINT  GRAY(34)      !  Result:  51



                                                            341




6.9. _H________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



6.9       H



                                                            342




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.9.__H__



Function:           HASH$()



Syntax:                h$=HASH$(t$[,typ%])



DESCRIPTION:



     Executes a hash function on the data contained in t$.  Depending on typ% the

hash function used is:


  Typ%=1          !  MD5    (default)

            2          !  SHA1

            3          !  RMD160

            5          !  MD2

            6          !  TIGER/192

            7          !  HAVAL,  5  pass,  160  bit.

            8          !  SHA256

            9          !  SHA384

          10          !  SHA512

          11          !  SHA224

        301          !  MD4

        302          !  CRC32

        303          !  CRC32.RFC1510

        304          !  CRC24.RFC2440

        305          !  WHIRLPOOL

        306          !  TIGER  fixed.

        307          !  TIGER2  variant.


If typ% is not specioed, MD5 is used. HASH$() returns a string which contains the

hash value in binary form.



     Comment:



                                                            343




6.9. _H________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



      The default HASH$(),  which is MD5,  and HASH typ%=2,  which is SHA1,  are

always  available.   The  other  hash  algorithms  are  only  available  if  libgcrypt  was

compiled in.



EXAMPLE:


          h$=HASH$("Calculate  a  MD5  sum  from  this  text.",1)
          PRINT  LEN(h$)       !  Result:  16
          PRINT  "MD5=";
          FOR  i=1  TO  16
             PRINT  RIGHT$(HEX$(ASC(MID$(h$,i))),2);
          NEXT  i
          PRINT
          '  --?  Result:  754975185BF0D1B78141D36C2E60E7D1



SEE ALSO:           CRC()



                                                            344




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.9.__H__



Command:        HELP



Syntax:                HELP  !string-pattern?



DESCRIPTION:



     Gives information on the synopsis of built-in commands and functions. You can

either specify a complete name of a command or a wildcard-pattern. All commands

and functions matching the pattern will be listed.



EXAMPLE:


HELP  CL*

Result:

CLEAR  [...]
           CLEARW  [#n]
           CLIP  i%,i%,i%,i%[,i%,i%]
CLOSE  [...]
           CLOSEW  [#n]
           CLR  var[,...]
CLS



                                                            345




6.9. _H________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           HEX$()



Syntax:                h$=HEX$(d%[,n%])



DESCRIPTION:



     Converts an integer value d% into a string containing its hexadecimal number

representation. The optional parameter n% specioes the minimal length of the out-

put.  If it is larger than needed, the string will be olled with leading zeros.  Negative

numbers  are  converted  to  unsigned  int  before  processing.   If  you  need  a  binary

representations with sign, use RADIX$() instead.



EXAMPLES:


PRINT  HEX$(123)           Result:   7B
PRINT  HEX$(17,8)          Result:   00000011



SEE ALSO:           STR$(), BIN$(), OCT$(), RADIX$()



                                                            346




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.9.__H__



Command:        HIDEK



Syntax:                HIDEK



DESCRIPTION:



     Hide the virtual keyboard. (It will be invisible.)



     Comment:



     Works  only  on  Android.   On  other  platforms  this  command  has  currently  no

eoeect.



SEE ALSO:           SHOWK



                                                            347




6.9. _H________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        HIDEM



Syntax:                HIDEM



DESCRIPTION:



     Hide the mouse cursor. (It will be invisible.)



     Comment:



     Works  only  on  the  framebuoeer  (Android)  and  on  ATARI-MINT.  On  other  plat-

forms this command has no eoeect.



SEE ALSO:           SHOWM, DEFMOUSE



                                                            348




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.9.__H__



Command:        HOME



Syntax:                HOME



DESCRIPTION:



     HOME will move the text cursor home (upper left corner).



SEE ALSO:           PRINT  AT()



                                                            349




6.9. _H________________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           HYPOT()



Syntax:                a=HYPOT(x,y)



DESCRIPTION:



     The  HYPOT()  function  returns  the  SQRT(x*x+y*y).   This  is  the  length  of  the

hypotenuse of a right-angle triangle with sides of length x and y, or the distance of

the point (x,y) from the origin.



EXAMPLE:


PRINT  HYPOT(3,4)      !  Result:  5



SEE ALSO:           SQRT()



                                                            350




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.10.__I_



6.10         I



                                                            351




6.10.__I_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        IF



Syntax:                IF  !condition?  [...  ELSE  [IF  !e?]  ...  ENDIF



DESCRIPTION:



     Divides  a  program  up  into  dioeerent  blocks  depending  on  how  it  relates  to  the

'condition'.



EXAMPLE:


   IF  a=1
      PRINT  "I  found  a  one!"
   ELSE
      PRINT  "no  one  found!"
   ENDIF



SEE ALSO:           ELSE, ENDIF



                                                            352




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.10.__I_



Function:           IMAG()



Syntax:                x=IMAG(z#)



DESCRIPTION:



     Returns the imaginary part of the complex number z#.



EXAMPLE:


PRINT  IMAG(1-2i)       Result:  -2



SEE ALSO:           CONJ(), REAL()



                                                            353




6.10.__I_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Operator:           IMP



Syntax:                a%=!num-expression?  IMP  !num-expression?



DESCRIPTION:



     The operator IMP (implication) corresponds to a logical consequence.  The re-

sult  is  FALSE  if  a  FALSE  expression  follows  a  TRUE  one.  The  sequence  of  the

argument is important. The operator operates on every bit of the values.


  Table:                A    ---    B    ---    A  IMP  B

                          -----+-----+-----------

                           -1    ---  -1    ---      -1

                           -1    ---    0    ---        0

                             0    ---  -1    ---      -1

                             0    ---    0    ---      -1



EXAMPLE:


         PRINT  BIN$((13  IMP  14)  AND  15,4)
         Result:   1110



SEE ALSO:           TRUE, FALSE, NOT, XOR, EQV



                                                            354




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.10.__I_



Command:        INC



Syntax:                INC  !num-variable?



DESCRIPTION:



     INC increments a (numeric) variable. This command is considerably faster than

the equivalent statement "!variable? = !variable?+1".



SEE ALSO:           ADD, DEC



                                                            355




6.10.__I_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        INFOW



Syntax:                INFOW  [!window-nr?],!string-expression?



DESCRIPTION:



     Links the (new) information string to the window with the number. On UNIX this

Information will be displayed in ICONIFIED state of the window.



SEE ALSO:           TITLEW



                                                            356




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.10.__I_



Variable:            INKEY$



Syntax:                !string-result?=INKEY$



DESCRIPTION:



     Returns a string containing the ASCII characters of all keys which have been

pressed on the keyboard.



EXAMPLE:


REPEAT  !  Wait  until  a
UNTIL  LEN(INKEY$)  !  Key  was  pressed



SEE ALSO:           INP(), KEYEVENT



                                                            357




6.10.__I_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           INLINE$()



Syntax:                !string-result?=INLINE$(!string-expression?)



DESCRIPTION:



     6-bit ASCII to binary conversion.  This command basically does a RADIX con-

version (from 64 to 256) on the contents of the string.  This is intended to be used

to include binary data into the source code of a basic program.

     The inverse coding (from binary to 6-bit ASCII) is done by the program inline.bas

which comes with X11-Basic.



EXAMPLE:


           sym$=INLINE$("$$$$$$$$0$&Tc.?$QL&ZD3cccccK]UD!*%D$$$$$$$$$")  !  Train
PUT.BITMAP  sym$,92,92,16,16



SEE ALSO:           PUT.BITMAP



                                                            358




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.10.__I_



Function:           INODE()



Syntax:                a%=INODE(filename$)



DESCRIPTION:



     Returns the inode number associated with a ole or directory on disk. Each inode

stores the attributes and disk block location(s) of the olesystem object's data.



     Comment:



     Works only on Unix-Style ole systems.



SEE ALSO:           EXIST()



                                                            359




6.10.__I_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           INP(),    INP"%(),    INP"&()



Syntax:                a=INP(!channel-nr?)

                              a=INP"&(!channel-nr?)

                              a=INP"%(!channel-nr?)



DESCRIPTION:



     Reads  one  byte  from  a  ole  previously  opened  with  OPEN  (nr?0)  or  from  the

standard oles (-1=stderr, -2=stdin, -4=stdout).  INP&() reads a word (2 Bytes) and

INP%() reads a long word (4 bytes).



EXAMPLE:


~INP(-2)           !  Waits  for  a  key  being  pressed
PRINT  INP%(#1)   !  reads  a  long  from  a  previously  opened  file



SEE ALSO:           OUT, INPUT$()



                                                            360




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.10.__I_



Function:           INP?()



Syntax:                a=INP?(!channel-nr?)



DESCRIPTION:



     Determine the input status of the device.  The function return TRUE (-1) if the

device is ready (chars can be read) otherwise FALSE (0).



SEE ALSO:           INP()



                                                            361




6.10.__I_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        INPUT



Syntax:                INPUT  [#!device-number?,]  !variable?  [,  ...]

                              INPUT  !prompt-expression?,  !variable?  [,  ...]



DESCRIPTION:



     INPUT gets comma-delimited input from the standard input or from a previously

opened ole as specioed by !device-number? (use the LINEINPUT function to read

complete lines from a ole and BLOAD to load complete oles). Any input is assigned

to the variable(s) specioed.  If input is expected from a terminal screen or console

window,  then  !prompt-expression?  is  printed  to  the  console  window  to  request

input from the user.



EXAMPLE:


           INPUT  #1,a$
           INPUT  "Enter  your  name:",a$



SEE ALSO:           LINEINPUT, FORM  INPUT  AS, PRINT



                                                            362




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.10.__I_



Function:           INPUT$()



Syntax:                a$=INPUT$(#!nr?,!len?)

                              a$=INPUT$(!len?)



DESCRIPTION:



     Reads !len? characters from the keyboard and assigns them to a string.  Op-

tionally, if the device-number is specioed, the characters are read in from a previ-

ously OPENed channel !nr?.



SEE ALSO:           INPUT, INP(), OPEN



                                                            363




6.10.__I_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           INSTR()



Syntax:                a%=INSTR(!a$?,!b$?[,!n?])



DESCRIPTION:



     Searches to see if b$ is present in a$ and returns its position. !n? is a numeric

expression indicating the position in a$ at which the search is to begin (default=1).

If !n? is not given the search begins at the orst character of a$. If b$ is found in a$

the start position is returned, otherwise 0.



SEE ALSO:           RINSTR(), GLOB(), REGEXP(), MATCH()



                                                            364




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.10.__I_



Function:           INT()



Syntax:                a%=INT(b)



DESCRIPTION:



     INT() cuts ooe the fractional part of the number a. and returns an integer number.

The integer number has only 32bit, so a should be in the range of -2147483648 to

2147483647.



EXAMPLE:


PRINT  INT(1.4),  INT(-1.7)
           Result:  1,  -1



SEE ALSO:           CINT(), FRAC(), TRUNC(), ROUND(), FIX()



                                                            365




6.10.__I_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           INV()



Syntax:                b()=INV(a())



DESCRIPTION:



     Calculate the inverse of a square matrix a().  The calculation is done using the

singular value decomposition.  If the matrix is singular the algorithm tells you how

many singular values are zero or close to zero.



EXAMPLE:


           a()=[3,7,3,0;0,2,-1,1;5,4,3,2;6,6,4,-1]
b()=INV(a())
PRINT  DET(a())*DET(b())    !  Result:  1
PRINT  DET(a()*b())           !  Result:  1



SEE ALSO:           SOLVE(), DET()



                                                            366




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.10.__I_



Function:           INVERT()



Syntax:                c&=INVERT(a&,b&)



DESCRIPTION:



     Compute the inverse of a modulo b and return the result.  If the inverse exists,

the return value is non-zero and c& will satisfy 0 != c& ! b&.  If an inverse doesn't

exist the return value is zero.



EXAMPLE:


PRINT  INVERT(12,53)         !  result:  31



SEE ALSO:           DIV()



                                                            367




6.10.__I_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           IOCTL()



Syntax:                !num-result?  =  IOCTL(#n,d%[,adr%])



DESCRIPTION:



     IOCTL() manipulates the underlying device parameters of special oles.  In par-

ticular,  many  operating  characteristics  of  character  special  oles  (e.g.   terminals)

may be controlled with ioctl requests.  The argument #n must refer to an open ole,

socket or device.

     The second argument is a device-dependent request code. The third argument

is either another integer value or a pointer to memory.

     An ioctl request has encoded in it whether the argument is an in parameter or

out parameter, and the size of the argument adr% refers to in bytes.

     Usually,  on success zero is returned.  A few ioctls use the return value as an

output  parameter  and  return  a  non-negative  value  on  success.   On  error,  -1  is

returned.



     Comment:



     In case of open USB devices, following IOCTL requests are implemented:


    0  --  USB  Reset    e.g.  ret%=IOCTL(#1,0)

    1  --  get  descriptor  data  structure.  The  data  structure  has  a

              length  of  4148  bytes.

              t$=SPACE$(4148)

              ret%=IOCTL(#1,1,VARPTR(t$))

              Please  see  the  example  program  usb.bas  for  details  how

              to  decode  the  information  in  this  data  structure.

    2  --  Set  configuration,  e.g.  ret%=IOCTL(#1,2,confnr%)

    3  --  Claim  Interface,      e.g.  ret%=IOCTL(#1,3,intrfnr%)

    4  --  control.msg,



                                                            368




CHAPTER_6.__COMMAND_REFERENCE______________________________________________________________________________________6.10.__I_



              t$=MKL$(a%)+MKL$(b%)+MKL$(c%)+MKL$(d%)+MKL$(timeout%)

              t$=t$+MKL$(len(data$))+data$

              ret%=IOCTL(#1,4,VARPTR(t$))

    5  --  Set  default  blk.len,            e.g.  ~IOCTL(#1,5,blk.len%)

    6  --  Set  default  endpoint.in,    e.g.  ~IOCTL(#1,6,ep.in%)

    7  --  Set  default  endpoint.out,  e.g.  ~IOCTL(#1,7,ep.out%)

  12  --  get  filename+path

              t$=SPACE$(4100)

              l%=IOCTL(#1,12,VARPTR(t$))

              devicefilenr$=LEFT$(t$,l%)

  13  --  get  manufacturer

              t$=SPACE$(100)

              l%=IOCTL(#1,13,VARPTR(t$))

              manufacturer$=LEFT$(t$,l%)

  14  --  get  product  name

              t$=SPACE$(100)

              l%=IOCTL(#1,14,VARPTR(t$))

              product$=LEFT$(t$,l%)

  15  --  get  serial  number

              t$=SPACE$(100)

              l%=IOCTL(#1,15,VARPTR(t$))

              serialnr$=LEFT$(t$,l%)

  16  --  get  error  string

              t$=SPACE$(100)

              l%=IOCTL(#1,16,VARPTR(t$))

              error$=LEFT$(t$,l%)



Comment:



     The interface to Bluetooth devices is not yet deoned.



                                                            369




6.10.__I_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



EXAMPLE:


           OPEN  "U",#1,"/dev/console"
           frequency=300
           tone=1190000/frequency
           KIOCSOUND=19247
           PRINT  IOCTL(#1,KIOCSOUND,tone)   !  Sounds  the  speaker
           CLOSE  #1
           Result:  0



SEE ALSO:           OPEN, CLOSE



                                                            370




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.11.__J__



6.11         J



                                                            371




6.11.__J_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           JULDATE$()



Syntax:                d$=JULDATE$(a)



DESCRIPTION:



     Returns the date as string (see DATE$) given by the Julian day number a.



SEE ALSO:           JULIAN(), DATE$



                                                            372




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.11.__J__



Function:           JULIAN()



Syntax:                a=JULIAN(date$)



DESCRIPTION:



     Returns the Julian date corresponding to the date given as a string in standard

format. The number which is returned is an integer number and has the unit days.



EXAMPLE:



   PRINT  "Number  of  days  since  Sept.  11  2001:  ";
   PRINT  JULIAN(DATE$)-JULIAN("11.09.2001")



SEE ALSO:           JULDATE$(), DATE$



                                                            373




6.12.__K_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



6.12         K



                                                            374




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.12.__K__



Command:        KEYEVENT



Syntax:                KEYEVENT  kc,ks[,t$,k,x,y,xroot,yroot]



DESCRIPTION:



     Waits  until  a  key  is  pressed  (in  graphic  window).  After  the  key  event  has  oc-

curred, the variables have following content:



      kc        --  Key-code

      ks        --  state  of  Shift/Control/Alt  etc.

      t$        --  corresponding  character

      x          --  x  coordinate  of  mouse  pointer  relative  to  window

      y          --  y  coordinate

      xroot  --  x  coordinate  of  mouse  pointer  relative  to  screen

      yroot  --  y  coordinate

      k          --  mouse  button  state



SEE ALSO:           MOUSEEVENT, EVENT, EVENT?()



                                                            375




6.12.__K_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        KILL



Syntax:                KILL  !filename?



DESCRIPTION:



     KILL deletes a ole from the ole system.



EXAMPLE:


KILL  "delme"



SEE ALSO:           OPEN, RMDIR



                                                            376




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



6.13         L



                                                            377




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           LCM()



Syntax:                c&=LCM(a&,b&)



DESCRIPTION:



     Returns the least common multiple of a and b. c is always positive, irrespective

of the signs of a and b. c will be zero if either a or b is zero.



EXAMPLE:


          PRINT  LCM(12,18)       !  Result:  36



SEE ALSO:           GCD()



                                                            378




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Function:           LEFT$()



Syntax:                a$=LEFT$(!string-expression?  [,!numchars?])



DESCRIPTION:



     LEFT$() returns the specioed number of characters from its argument, begin-

ning at its left side. If the number of characters is not specioed then LEFT$() returns

only the leftmost character.



EXAMPLE:


          PRINT  LEFT$("Hello",1)       !  Result:  H



SEE ALSO:           RIGHT$(), MID$()



                                                            379




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           LEFTOF$()



Syntax:                a$=LEFTOF$(t$,s$)



DESCRIPTION:



     LEFTOF$() returns the left part of t$ at the position of the orst occurrence of s$

in t$. If s$ is not contained in t$, the whole string t$ is returned.



EXAMPLE:


          PRINT  LEFTOF$("Hello","ll")    !   Result:  He



SEE ALSO:           RIGHTOF$(), MID$()



                                                            380




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Function:           LEN()



Syntax:                l=LEN(t$)



DESCRIPTION:



     Returns the length of a string.



EXAMPLE:


          PRINT  LEN("Hello")   !  Result:  5



                                                            381




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        LET



Syntax:                LET  !variable?  =  !expression?



DESCRIPTION:



     LET assigns the value of !expression? to !variable?. The interpreter also sup-

ports  implicit  assignments,  ie.   the  LET  keyword  before  an  assignment  may  be

omitted.  This works because the orst equal sign is regarded as assignment oper-

ator.



EXAMPLE:


          LET  N=1



                                                            382




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Function:           LGAMMA()



Syntax:                b=LGAMMA(a)



DESCRIPTION:



     The LGAMMA() function returns the natural logarithm of the absolute value of

the Gamma function.


        LGAMMA(x)=ASB(LN(GAMMA(x)))


If x is a NaN, a NaN is returned.

     If x is 1 or 2, +0 is returned.

     If x is positive inonity or negative inonity, positive inonity is returned.

     If x is a non-positive integer, a pole error occurs, and the function returns inf.

     If the result overAEows, a range error occurs, and the function returns inf with the

correct mathematical sign.



SEE ALSO:           GAMMA(), SIN()



                                                            383




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        LINE



Syntax:                LINE  x1,y1,x2,y2



DESCRIPTION:



     Draws a straight line from (x1,y1) to (x2,y2). The line thickness as well as other

drawing parameters can be set with DEFLINE and GRAPHMODE.



SEE ALSO:           DRAW, PLOT, DEFLINE



                                                            384




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Command:        LINEINPUT



Syntax:                LINEINPUT  [[#]!device-number?,]  t$



DESCRIPTION:



     LINE  INPUT  reads  an  entire  line  from  a  standard  input  or  from  a  previously

opened ole as specioed by !device-number? (to load a complete ole, use BLOAD).

Unlike the regular INPUT command, LINEINPUT does not stop at delimiters (com-

mas).



SEE ALSO:           INPUT



                             _________________________________*________________________________



Function:           LINEINPUT$()



Syntax:                t$=LINEINPUT$([#1])



DESCRIPTION:



     LINEINPUT$() reads an entire line from a standard input or from a previously

opened ole as specioed by !device-number? (to load a complete ole, use BLOAD).

Unlike  the  regular  INPUT  command,  LINEINPUT$()  does  not  stop  at  delimiters

(commas).



                                                            385




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



SEE ALSO:           INPUT$(), LINEINPUT



                                                            386




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Command:        LINK



Syntax:                LINK  #!device-nr?,name$



DESCRIPTION:



     LINK links a shared object ole/library (*.so in /var/lib) dynamically.  It will from

now on be addressed via the device-nr.

     The addresses of he symbols of that library can be read with the SYM.ADR()

function.

     If  the  Library  is  not  used  any  more  it  can  be  unlinked  with  the  UNLINK  com-

mand.



SEE ALSO:           UNLINK, SYM.ADR(), CALL



                                                            387




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        LIST



Syntax:                LIST  [!line-number?[,!line-number?]



DESCRIPTION:



     LIST displays the source code or a code segment. Note that the line number of

the orst line in a ole is 0, that the second line is line 1 etc.



EXAMPLE:


          LIST
          LIST  1,10
          LIST  5



SEE ALSO:           PLIST, PRG$()



                                                            388




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Function:           LISTSELECT()



Syntax:                num%=LISTSELECT(title$,list$())



DESCRIPTION:



     listselect opens a graphical list-selector, which enables the user to select one

entry out of an array list$(). The index of the entry is returned or -1 in case no item

was selected.



SEE ALSO:           FILESELECT



                                                            389




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        LOAD



Syntax:                LOAD  name$



DESCRIPTION:



     Loads a program into memory.



EXAMPLE:


LOAD  "testme.bas"



SEE ALSO:           XLOAD, MERGE, CHAIN



                                                            390




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Function:           LOC()



Syntax:                p%=LOC(#!device-nre?)



DESCRIPTION:



     Returns the location of the ole pointer for the ole with the device number.  The

location is given in number of bytes from the start of the ole.



SEE ALSO:           LOF()



                                                            391




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        LOCAL



Syntax:                LOCAL  !var?[,!var?,...]



DESCRIPTION:



     Declares  several  variables  to  be  a  local  variable.   This  command  is  normally

used inside PROCEDUREs and FUNCTIONs.  LOCAL does not initialize the vari-

ables. If you need them to be initialized, use CLR after LOCAL.



EXAMPLE:


LOCAL  a,b$,s()



                                                            392




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Command:        LOCATE



Syntax:                LOCATE  row%,column%



DESCRIPTION:



     Positions  the  cursor  to  the  specioed  location.   The  upper  right  corner  of  the

screen is located at 0,0.



SEE ALSO:           PRINT  AT(), CRSLIN, CRSCOL



                                                            393




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           LOF()



Syntax:                l%=LOF(#n)



DESCRIPTION:



     Returns the length of the ole with device number n.



SEE ALSO:           LOC()



                                                            394




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Function:           LOG(),    LOG10(),    LN()



Syntax:                !num-result?=LOG(!num-expression?)

                              !num-result?=LOG10(!num-expression?)

                              !num-result?=LN(!num-expression?)



DESCRIPTION:



     Returns the natural logarithm (log, ln) or the logarithm base 10 (log10).



SEE ALSO:           EXP()



                                                            395




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           LOGB()



Syntax:                !int-result?=LOGB(!num-expression?)



DESCRIPTION:



     Returns the logarithm base 2 in integer values.



SEE ALSO:           LOG()



                                                            396




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Function:           LOG1P()



Syntax:                !num-result?=LOG1P(!num-expression?)



DESCRIPTION:



     Returns a value equivalent to log(1+x). It is computed in a way that is accurate

even if the value of x is near zero.



SEE ALSO:           LOG(), EXP(), LN()



                                                            397




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        LOOP



Syntax:                LOOP



DESCRIPTION:



     LOOP  terminates  a  DO  loop  and  can  be  used  as  unqualioed  loop  terminator

(such a loop can only be aborted with the EXIT command).  Execution continues

with the DO line.



EXAMPLE:


DO
   PRINT  TIME$
   PAUSE  1
LOOP



SEE ALSO:           DO, EXIT  IF, BREAK



                                                            398




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Function:           LOWER$()



Syntax:                !string-result?=LOWER$(!string-expression?)



DESCRIPTION:



     Transforms all upper case letters of a string to lower case.  Any non-letter char-

acters are left unchanged.



EXAMPLE:


PRINT  LOWER$("Oh  my  GOD!")    !  Result:  oh  my  god!



SEE ALSO:           UPPER$()



                                                            399




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           LPEEK()



Syntax:                !int-result?=LPEEK(!num-expression?)



DESCRIPTION:



     Reads a 4 byte integer from address.



SEE ALSO:           PEEK(), POKE



                                                            400




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Command:        LPOKE



Syntax:                LPOKE  !adr?,!num-expression?



DESCRIPTION:



     Writes a 4 byte integer to address !adr?.



SEE ALSO:           DPOKE, POKE, PEEK()



                                                            401




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        LTEXT



Syntax:                LTEXT  x,y,t$



DESCRIPTION:



     Draws a text at position x,y. The LTEXT command uses a linegraphic text, which

allows the user to draw very large fonts and be independent of the system fonts.

The font style can be inAEuenced with the DEFLINE and the DEFTEXT command.



SEE ALSO:           DEFTEXT, TEXT, DEFLINE, LTEXTLEN()



                                                            402




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.13.__L__



Function:           LTEXTLEN()



Syntax:                w=LTEXTLEN(t$)



DESCRIPTION:



     Returns the with of the text t$ in pixels.  The font style can be inAEuenced with

the DEFLINE and the DEFTEXT command.



SEE ALSO:           LTEXT



                                                            403




6.13.__L_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           LUCNUM()



Syntax:                w&=LUCNUM(i%)



DESCRIPTION:



     Returns the i'th Lucas number.



     Comment:



     This function works only in the interpreter and only when used in a direct as-

signment to a big integer variable.



EXAMPLES:


   w&=LUCNUM(100)   --?  Result:  792070839848372253127



SEE ALSO:           FIB(), PRIMORIAL()



                                                            404




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



6.14         M



                                                            405




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           MALLOC()



Syntax:                adr%=MALLOC(size%)



DESCRIPTION:



     Allocates size% bytes and returns a pointer to the allocated memory. The mem-

ory is not cleared.



SEE ALSO:           FREE(), MFREE(), REALLOC()



                                                            406




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



Function:           MATCH()



Syntax:                a%=MATCH(a$,r$)



DESCRIPTION:



     Searches to see if a substring matching the regular expression r$ is present in

a$ and returns its position.  If no matching substring is found in a$, 0 is returned.

In case of an ERROR in the regular expression, -1 is returned.



     Comment:



     Regular expressions are very powerful in pattern matching.  Compared to IN-

STR()  or  GLOB()  you  have  nearly  inonite  AEexibility.   If  you  do  not  know  what  a

regular expression is or what the syntax of it should be, please look elsewhere for

information.  An full explanation would be too much for this manual.  Unfortunately

there  are  many  dioeerent  standards  for  regular  expression.   The  Implementation

uses here is the so called "POSIX.2" type. Note: Zero-Bytes (CHR$(0)) cannot be

matched and will indicate the end of the content of a$.



     Comment:



     This command is currently no available in the WINDOWS version of X11-Basic.



EXAMPLES:


t$="This  1  is  nice  2  so  33  for  4254"
PRINT  MATCH(t$,"([[:digit:]]+)[^[:digit:]]+([[:digit:]]+)")



                                                            407




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Result:  6



SEE ALSO:           INSTR(), RINSTR(), GLOB(), REGEXP()



                                                            408




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



Function:           MAX()



Syntax:                m=MAX(a,b[,c,...])

                              m=MAX(f())



DESCRIPTION:



     Returns the largest value out of the list of arguments or the largest value of an

array.



SEE ALSO:           MIN()



                                                            409




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        MENU



Syntax:                MENU



DESCRIPTION:



     Performs menu check and action.

     This command handles EVENTs.  Prior to use,  the required action should be

specioed with a MENUDEF command.  For constant supervision of events, MENU

is usually found in a loop.



EXAMPLE:



MENUDEF  field$(),menuaction
DO
   pause  0.05
   MENU
LOOP
PROCEDURE  menuaction(k)
    ...
RETURN



SEE ALSO:           MENUDEF



                                                            410




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



Command:        MENUDEF



Syntax:                MENUDEF  array$(),!procname?



DESCRIPTION:



     This  command  reads  text  for  menu-header  from  array"$()  the  string-array

contains the text for menu-titles and menu-entries


        -  end  of  row:  empty  string  ""

        -  end  of  menu-text:  empty  string  ""


!procname? The procedure to which control will be passed on selection of a menu

entry.   It  must  be  a  procedure  with  one  parameter  which  is  the  number  of  the

selected item to call when item was selected.



EXAMPLE:



field$()=["INFO","   Menutest   ","","FILE","   new","   open  ...","   save",""
save  as  ...","--------------","   print","--------------","   Quit","",""]
MENUDEF  field$(),menuaction
DO
   pause  0.05
   MENU
LOOP
PROCEDURE  menuaction(k)
   PRINT  "MENU  selected  ";k;"  contents:  ";field$(k)
   IF  field$(k)="   Quit"
      QUIT
   ENDIF
RETURN



SEE ALSO:           MENU, MENUSET, MENUKILL



                                                            411




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



                              _________________________________*________________________________



Command:        MENUKILL



Syntax:                MENUKILL



DESCRIPTION:



     Erases the menu, which prior has been deoned with MENUDEF.



SEE ALSO:           MENUDEF



                                                            412




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



Command:        MENUSET



Syntax:                MENUSET  n,x



DESCRIPTION:



     Change appearance of menu-entry n with value x.


          x=0    '  '    normal,  reset  marker  '^'

          x=1    '^'    set  marker

          x=2    '='    set  menu-point  non  selectable

          x=3    '  '    set  menu-point  selectable

          x=4    check  the  menu  entry

                    '-'    permanent  non  selectable



SEE ALSO:           MENU



                                                            413




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        MERGE



Syntax:                MERGE  !filename?



DESCRIPTION:



     MERGE appends a BASIC program to the program currently in memory.  Pro-

gram execution is not interrupted. This command typically is used to append often-

used subroutines at run-time.



     Comment:



     MERGE always loads the ole at the end of the current program and not at the

place where the MERGE statement itself is located.

     MERGE  is  excecuted  on  runtime,  this  means  if  the  MERGE  command  is  not

reched by the program AEow, nothing will be merged.

     An  END  statement  is  implied  at  the  end  of  the  currently  loaded  ole.   If  you

want to excecute parts of the just merged code you must use labels and GOTO or

procedures or functions.

     MERGE is a command and not a compiler directive.  MERGE does something

only when it is reached in the program AEow.



SEE ALSO:           CHAIN, LOAD



EXAMPLE:


          MERGE  "examples/mylibrary.bas"



                                                            414




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



          a=@functionfromlibrary()



                                                            415




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        MFREE



Syntax:                MFREE  adr%



DESCRIPTION:



     Frees  a  memory  area  which  has  been  allocated  with  MALLOC()  before.  The

address must be the same as previously returned by MALLOC().



SEE ALSO:           MALLOC()



                                                            416




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



Function:           MID$()



Syntax:                m$=MID$(t$,x[,l])



DESCRIPTION:



     Returns l characters in a string from the position x of the string t$.  If x is larger

than  the  length  of  t$,  then  an  empty  string  is  returned.   If  l  is  omitted,  then  the

function returns only one character of the string from position x.



SEE ALSO:           LEFT$(), RIGHT$()



                                                            417




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           MIN()



Syntax:                m=MIN(a,b[,c,...])

                              m=MIN(f())



DESCRIPTION:



     Returns the smallest value out of the list of arguments or the smallest value of

an array.



SEE ALSO:           MAX()



                                                            418




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



Command:        MKDIR



Syntax:                MKDIR  !path-name?[,mode%]



DESCRIPTION:



     MKDIR attempts to create a directory named path-name.  The argument mode

specioes the permissions to use. It is modioed by the process's umask in the usual

way:  the permissions of the created directory are (mode% AND NOT umask AND

(7*64+7*8+7)).  Other mode bits of the created directory depend on the operating

system.



EXAMPLE:


MKDIR  "/tmp/myfolder"



SEE ALSO:           CHDIR, RMDIR



                                                            419




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           MKI$(),    MKL$(),    MKS$()



Function:           MKF$(),    MKD$(),    MKA$()



Syntax:                a$=MKI$(!num-expression?)

                              a$=MKL$(!num-expression?)

                              a$=MKS$(!num-expression?)

                              a$=MKF$(!num-expression?)

                              a$=MKD$(!num-expression?)

                              a$=MKA$(!array-expression?)



DESCRIPTION:



     These six functions transform a number into a character string.


          MKI$  a  16-bit  number  into  a  2-byte  string,

          MKL$  a  32-bit  number  into  a  4-byte  string,

          MKS$  a  number  into  a  4-byte  float  format,

          MKF$  same  as  MKS$().

          MKD$  a  number  into  a  8-byte  double  float  format,

          MKA$()  transforms  a  whole  Array  into  a  string.

                        It  can  be  reversed  with  CVA().



SEE ALSO:           CVI(), CVF(), CVL(), CVA(), CVS(), CVD()



                                                            420




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



Operator:           MOD



Syntax:                a=x  MOD  y



DESCRIPTION:



     Produces the remainder of the division of x by y.



SEE ALSO:           DIV, MOD()



                             _________________________________*________________________________



Function:           MOD()



Syntax:                a=MOD(x,y)



DESCRIPTION:



     Produces the remainder of the division of x by y.



SEE ALSO:           DIV, MOD



                                                            421




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           MODE()



Syntax:                m%=MODE(filename$)



DESCRIPTION:



     Return the ole permissions and the ole type of the ole or directory given.  With

these  values  one  can  ond  out  what  kind  the  ole  is  of.   The  bits  of  the  returned

integer have the following meaning:


    xxxx  xxxx  xxxx  xxxx

                    ---  ------------  ---rwx--  permission  for  others

                    ---  ------------  ---            (read,  write,  excecute)

                    ---  ------rw  x-----  permissions  for  group

                    r  wx---------  permissions  for  user

                  s-------------  sticky  bit

                g--------------  set  group  id  bit

              u---------------  set  user  id  bit

    ++++-----------------  file  type:

                                               0  --  regular  file

                                               1  --  fifo

                                               2  --  charackter  device

                                               4  --  directory

                                               6  --  block  device

                                               8  --  regular  file

                                             10  --  symbolic  link

                                             12  --  socket



Comment:



     May not work on WINDOWS systems.



                                                            422




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



EXAMPLES:


   PRINT  OCT$(MODE("."))  ---?  Result:  40750
   DEFFN  isdir(f$)=(MODE(f$)  AND  0x4000)?0



SEE ALSO:           INODE(), EXIST()



                                                            423




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        MOTIONEVENT



Syntax:                MOTIONEVENT  x,y,xroot,yroot,s



DESCRIPTION:



     Waits until the mouse has been moved. (graphic window). Returns new mouse

coordinate (x,y) relative to window, mouse coordinate (xroot,yroot) relative to screen

and state of the Alt/Shift/Caps keys (s).



SEE ALSO:           MOUSE, MOUSEX, MOUSEY, MOUSEK, MOUSEEVENT



                                                            424




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



Command:        MOUSE



Syntax:                MOUSE  x,y,k



DESCRIPTION:



     Determines the mouse position (x,y) relative to the origin of the graphics window

and the status of the mouse buttons (k) and the mouse wheel if present.


        k=0  no  buttons  pressed

        k=1  left  button

        k=2  middle  button

        k=4  right  button

        k=8  wheel  up

        k=16  wheel  down


or any combinations.



SEE ALSO:           MOUSEX, MOUSEY, MOUSEK



                                                            425




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        MOUSEEVENT



Syntax:                MOUSEEVENT  x,[y,k,xroot,yroot,s]



DESCRIPTION:



     Waits  until  a  mouse  button  is  pressed  (graphic  window).  Returns  the  mouse

coordinate (x,y) relative to the window, the mouse coordinate (xroot,yroot) relative

to the screen, the mouse button (k) and state of the Alt/Shift/Caps keys (s).


                    k=0  no  buttons  pressed

                    k=1  left  button

                    k=2  middle  button

                    k=3  right  button

                    k=4  wheel  up

                    k=5  wheel  down



                    s=0  normal

                    s=1  Shift

                    s=2  CapsLock

                    s=4  Ctrl

                    s=8  Alt

                    s=16  NumLock

                    s=64  Windows-Key

                    s=128  AltGr



SEE ALSO:           MOUSE, MOUSEX, MOUSEY, MOUSEK, KEYEVENT, EVENT, EVENT?()



                                                            426




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



Variable:            MOUSEX,    MOUSEY,    MOUSEK



Variable:            MOUSES



Syntax:                x%=MOUSEX

                              y%=MOUSEY

                              k%=MOUSEK

                              s%=MOUSES



DESCRIPTION:



     MOUSEX returns the current horizontal position of the mouse cursor, or of the

last position of a touch on a touch screen.

     MOUSEY holds the vertial position accordingly.

     MOUSEK returns the current status of the mouse buttons:


                    MOUSEK=0  no  buttons  pressed

                    MOUSEK=1  left  button

                    MOUSEK=2  middle  button

                    MOUSEK=4  right  button

                    MOUSEK=8  wheel  up

                    MOUSEK=16  wheel  down


or any combinations.

     MOUSES returns the current state (state when the touchscreen was last touched)

of the SHIFT/CAPSLOCK/CTRL keys.


              MOUSES=0    no  Keys

              MOUSES=1    Shift

              MOUSES=2    CapsLock



                                                            427




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



               MOUSES=4    Control

               MOUSES=8    Alt

               MOUSES=16  NumLock

               MOUSES=64  Windows-Key

               MOUSES=128  AltGr


or any combination.



SEE ALSO:           MOUSE, SETMOUSE, MOUSEEVENT



                                                            428




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



Command:        MOVEW



Syntax:                MOVEW  n,x,y



DESCRIPTION:



     Moves Window n to absolute screen position x,y



SEE ALSO:           OPENW, SIZEW, TITLEW



                                                            429




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           MSHRINK()



Syntax:                a=MSHRINK(adr%,size%)



DESCRIPTION:



     Reduces the size of a storage area previously allocated with MALLOC. adr%

specioes the address of the area, size% gives the required size.  Returns 0 if no

error.  This command does nothing (and always returns 0) on Linux and windows

operating systems.  It is implemented for compatibility reasons only.  If you really

need to resize a memory area, use REALLOC().



SEE ALSO:           MALLOC(), REALLOC()



                                                            430




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



Command:        MSYNC



Syntax:                MSYNC  adr,length



DESCRIPTION:



     MSYNC AEushes changes made to the in-core copy of a ole that was mapped

into memory using MAP back to disk. Without use of this call there is no guarantee

that changes are written back before UNMAP is called.  To be more precise,  the

part of the ole that corresponds to the memory area starting at addr and having

length length is updated.



SEE ALSO:           MAP, UNMAP



                                                            431




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           MTFD$()



Syntax:                b$=MTFD$(a$)



DESCRIPTION:



     This  function  performs  a  Move  To  Front  decoding  function  on  an  input  string.

The  MTF  decoder  keeps  an  array  of  256  characters  in  the  order  that  they  have

appeared.  Each time the encoder sends a number, the decoder uses it to look up

a character in the corresponding position of the array, and outputs it. That character

is then moved up to position 0 in the array, and all the in-between characters are

moved down a spot.



SEE ALSO:           MTFE$()



                                                            432




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.14.__M___



Function:           MTFE$()



Syntax:                b$=MTFE$(a$)



DESCRIPTION:



     This function performs a Move To Front encoding function on an input string. An

MTF encoder encodes each character using the count of distinct previous charac-

ters seen since the characters last appearance.  This is implemented by keeping

an array of characters.  Each new input character is encoded with its current posi-

tion in the array.  The character is then moved to position 0 in the array, and all the

higher order characters are moved down by one position to make room.



SEE ALSO:           MTFD$()



                                                            433




6.14.__M_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        MUL



Syntax:                MUL  var,n



DESCRIPTION:



     Same as var=var*n but faster.



SEE ALSO:           ADD, SUB, MUL(), DIV



                             _________________________________*________________________________



Function:           MUL()



Syntax:                a=MUL(b,c)



DESCRIPTION:



     Returns product of two numbers.



SEE ALSO:           ADD(), SUB(), MUL, DIV()



                                                            434




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.15.__N__



6.15         N



                                                            435




6.15.__N_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Operator:           NAND



Syntax:                a  NAND  b



DESCRIPTION:



     The result of the NAND operator is true, if not both operands are true, and false

otherwise. Is the same as NOT (a AND b).

     Returns -1 for true, 0 for false.

     Also  used  to  combine  bits  in  binary  number  operations.   E.g.   (1  NAND  -1)

returns -2.



EXAMPLES:



PRINT  3=3  NAND  4!2  !  Result:   -1  (true)
PRINT  3?2  NAND  5?3  !  Result:    0  (false)
PRINT  (1  NAND  -3)          !  Result:    -2



SEE ALSO:           NOR, AND, NOT



                                                            436




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.15.__N__



Command:        NEW



Syntax:                NEW



DESCRIPTION:



     NEW erases the program and all variables in memory (and stops execution of

program.)



SEE ALSO:           CLEAR



                                                            437




6.15.__N_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        NEXT



Syntax:                NEXT  [!variable?]



DESCRIPTION:



     NEXT terminates a FOR loop.  FOR loops must be nested correctly:  The vari-

able  name  after  NEXT  is  for  looks  only  and  can  not  be  used  to  select  a  FOR

statement.  Each NEXT jumps to the matching FOR statement regardless if and

what !variable? is specioed after NEXT.



SEE ALSO:           FOR



EXAMPLE:


           FOR  n=1  TO  2
              FOR  m=10  to  11
                 PRINT  "n=";n,"m=";m
              NEXT  m
           NEXT  n



                                                            438




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.15.__N__



Function:           NEXTPRIME()



Syntax:                p&=NEXTPRIME(x&)



DESCRIPTION:



     Returns the smallest prime number bigger than x.



EXAMPLE:


           PRINT  NEXTPRIME(200)         !  Result:  211
           PRINT  NEXTPRIME(200000000000000000000)  !  Result:  200000000000000000089



SEE ALSO:           GCD()



                                                            439




6.15.__N_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           NLINK()



Syntax:                m%=NLINK(filename$)



DESCRIPTION:



     Return the number of (hard) links to the ole or directory.



     Comment:



     May not work on WINDOWS systems.



EXAMPLES:


   PRINT  NLINK(".")  ---?  Result:  2



SEE ALSO:           INODE(), EXIST(), MODE()



                                                            440




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.15.__N__



Command:        NOP,    NOOP



Syntax:                NOP

                              NOOP



DESCRIPTION:



     No Operation: do nothing.



                                                            441




6.15.__N_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Operator:           NOR



Syntax:                a  NOR  b



DESCRIPTION:



     The  result  of  the  NOR  operator  is  true,  if  both  operands  are  zero,  and  false

otherwise.  Used to determine if both of the conditions are false.  Is the same as

NOT (a OR b).

     Returns -1 for true, 0 for false.

     Also used to combine bits in binary number operations. E.g. (1 NOR -8) returns

6.



EXAMPLES:



PRINT  3=3  NOR  4!2   Result:    0  (false)
PRINT  3?3  NOR  5!3   Result:   -1  (true)

PRINT  (4  NOR  -128)          Result:    123



SEE ALSO:           NAND, OR, NOT, XOR



                                                            442




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.15.__N__



Command:        NOROOTWINDOW



Syntax:                NOROOTWINDOW



DESCRIPTION:



     Switches  back  to  normal  graphic  output  (normally  into  a  window),  if  it  was

switched to ROOTWINDOW before.



SEE ALSO:           ROOTWINDOW



                                                            443




6.15.__N_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Operator:           NOT



Syntax:                NOT  !num-expression?



DESCRIPTION:



     The result of the NOT operator is true, if the following expression is false, and

false if the expression is true.  Used to produce the opposite/negation of a logical

expression.

     Returns -1 for true, 0 for false.

     Also used to invert bits in binary number operations. E.g. (NOT -8) returns 7.



SEE ALSO:           AND, OR, NAND, NOR



                                                            444




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.16.__O___



6.16         O



                                                            445




6.16.__O_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        OBJC.ADD



Syntax:                OBJC.ADD  tree,parent,child



DESCRIPTION:



     Adds an object to a given tree and pointers between the existing objects and

the new object are created.


        tree      =    address  of  the  object  tree

        parent  =    object  number  of  the  parent  object

        child    =    object  number  of  the  child  to  be  added.



SEE ALSO:           OBJC.DELETE



                             _________________________________*________________________________



Command:        OBJC.DELETE



Syntax:                OBJC.DELETE  tree,object



DESCRIPTION:



     An object is deleted from an object tree by removing the pointers. The object is

still there and can be restored by repairing the pointers.



                                                            446




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.16.__O___



                tree          address  of  the  object  tree

                object      Object  number  of  the  object  to  delete.



SEE ALSO:           OBJC.ADD



                                                            447




6.16.__O_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           OBJC.DRAW()



Syntax:                ret=objc.draw(tree,startob,depth,cx,cy,cw,ch)



DESCRIPTION:



     Draws any object or objects in an object tree.

     Each OBJC.DRAW call deones a new clip rectangle,  to which the drawing is

limited for that call.

     Returns 0 on error.


            tree          address  of  the  object  tree

            startob    number  of  the  first  object  to  be  drawn

            depth        Number  of  object  levels  to  be  drawn

            cx,cy        coordinates    of  top  left  corner  of  clipping

                             rectangle

            cw,ch        width  &  height  of  clipping  rectangle



SEE ALSO:           OBJC.FIND()



                                                            448




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.16.__O___



Function:           OBJC.FIND()



Syntax:                idx=objc.find(tree,startob,depth,x,y)



DESCRIPTION:



     Finds an object under a specioc screen coordinate.  (These may be the mouse

coordinates.)

     The application supplies a pointer to the object tree, the index to the start object

to  search  from,  the  x-  and  y-coordinates  of  the  mouse's  position,  as  well  as  a

parameter that tells OBJC.FIND how far downthe tree to search (depth).

     This function returns the index of the found Object or -1 in case no object could

be found.



SEE ALSO:           OBJC.DRAW()



                                                            449




6.16.__O_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           OBJC.OFFSET()



Syntax:                ret=objc.offset(tree,obj,x,y)



DESCRIPTION:



     Calculates the absolute screen coordinates of the specioed object in a specioed

tree.

     Returns 0 on error.


                tree          address  of  the  object  tree

                obj            object  number

                x,y            returns  the  x,y  coordinates  to  these

                                 variables.



SEE ALSO:           OBJC.FIND()



                                                            450




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.16.__O___



Function:           OCT$()



Syntax:                o$=OCT$(d%[,n%])



DESCRIPTION:



     Converts an integer value d% into a string containing its octal number represen-

tation.  The optional parameter n% specioes the minimal length of the output.  If it

is larger than needed, the string will be olled with leading zeros. Negative numbers

are converted to unsigned int before processing.  If you need binary representa-

tions with sign, use RADIX$() instead.



EXAMPLES:


PRINT  OCT$(123)           Result:   173
PRINT  OCT$(9,8)           Result:   00000011



SEE ALSO:           BIN$(), STR$(), HEX$(), RADIX$()



                                                            451




6.16.__O_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           ODD()



Syntax:                a=ODD(number)



DESCRIPTION:



     Returns true (-1) if the number is odd, else false (0).



SEE ALSO:           EVEN()



                                                            452




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.16.__O___



Command:        ON    *    GOSUB



Syntax:                ON  a  GOSUB  proc1[,proc2,...]



DESCRIPTION:



     Calls a procedure out of the given list of procedures depending on the value of

a. If a=1, the orst procedure is used, if a=2 the second, and so on.



SEE ALSO:           GOSUB



                             _________________________________*________________________________



Command:        ON    *    GOTO



Syntax:                ON  a  GOTO  label1[,label2,...]



DESCRIPTION:



     Branches to a label out of the given list depending on the value of a. If a=1, the

orst label is used, if a=2 the second, and so on.



SEE ALSO:           GOTO



                                                            453




6.16.__O_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        ON    BREAK



Syntax:                ON  BREAK  CONT

                              ON  BREAK  GOSUB  !procedure?

                              ON  BREAK  GOTO  !label?



DESCRIPTION:



     ON  BREAK  installs  a  subroutine  that  gets  called  when  the  BREAK  condition

(normally CTRL-c) occurs.  ON BREAK CONT causes the program to continue in

any case. ON BREAK GOTO jumps to a specioed label.



SEE ALSO:           GOTO, ON  ERROR



                             _________________________________*________________________________



Command:        ON    ERROR



Syntax:                ON  ERROR  CONT

                              ON  ERROR  GOSUB  !procedure?

                              ON  ERROR  GOTO  !label?



                                                            454




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.16.__O___



DESCRIPTION:



     ON ERROR installs an error handling subroutine that gets called when the next

error occurs.  Also one can branch to a label in case of an error.  Program excecu-

tion can only be continued when RESUME can be used, and when the error is not

FATAL.

     ON ERROR CONT will ignore any error and will not print error messages.



SEE ALSO:           GOSUB, ERROR, RESUME, FATAL



                                                            455




6.16.__O_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        OPEN



Syntax:                OPEN  mode$,#!device-number?,filename$[,port%]



DESCRIPTION:



     OPEN  opens  the  specioed  ole  for  reading  or  writing  or  both.   The  !device-

number?  is  the  number  you  want  to  assign  to  the  ole  (functions  that  read  from

oles or write to oles expect to be given this number).  The device number must be

between 0 and 99 in the current implementation of X11-Basic.  When you close a

ole,  the device number is released and can be used again in subsequent OPEN

statements.

     mode$ is a character string which indicates the way the ole should be opened.

     The orst character of that string may be "O", "I", "U" or "A".  These characters

correspond to the mode for which the ole is opened:  "I" ~ INPUT, "O" ~OUTPUT,

"A" ~ APPEND and "U" ~ UNSPECIFIED/UPDATE/ READandWRITE.

     Open a ole for INPUT if you want to read data from the ole.  If you open a ole

for  OUTPUT,  you  can  write  to  the  ole.   However,  all  data  that  was  stored  in  the

ole (if the ole already exists) is lost.  If you want to write new data to a ole while

keeping the existing content, open the ole for appending to it, using the APPEND

mode.  When you open a ole using the UPDATE ("U") keyword, you can both read

from the ole and write to the ole at arbitrary positions.  You can, for example, seek

a  position  in  the  middle  of  the  ole  and  start  appending  new  lines  of  text.  All  ole

modes but INPUT create the ole if it does not exist.  OPEN "I" fails if the ole does

not exist (use the EXIST() function before OPEN to be sure that the ole exists).

     The second character specioes the type of ole which should be opened or cre-

ated:


    ""      default,  opens  a  regular  file

    "U"    opens  a  datagram  socket  connection  (UDP)

    "C"    opens  a  stream  socket  as  client  with  connection  (TCP)

    "S"    opens  a  stream  socket  as  server



                                                            456




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.16.__O___



    "A"    Socket  accept  connection

    "X"    extra  settings  for  a  special  device  following:

              (e.g.  speed  and  parity  of  transmission  via  serial  ports)

              "UX:baud,parity,bits,stopbits,flow"

    "Y"    opens  an  USB  connection.  The  filename  specifies  the

              vendor-ID  and  product-ID  of  the  device  to  be  opened.

    "B"    opens  a  BLUETOOTH  stream  socket  as  client  with

              connection  (RFCOMM)

    "L"    opens  a  BLUETOOTH  datagram  socket  as  client  with

              connection  (L2CAP)

    "V"    opens  a  BLUETOOTH  datagram  socket  as  server  (L2CAP)

    "Z"    opens  a  BLUETOOTH  a  stream  socket  as  server  (RFCOMM)


!port-nr?  The  portnr  is  used  by  the  OPEN  "UC"  and  OPEN  "UU"  statement  to

specify the TCP/IP Port of connection (FTP, WWW, TELNET, MAIL etc.)  and also

by the "UB","UL","UV" and "UZ" connection types.



     Comment:



     Special settings of USB and BLUETOOTH devices can be acces by IOCTL().

They are not fully documented by now, and also the implementation is not yet oxed.

Please refer to the example programs.



EXAMPLES:


         OPEN  "I",#1,"data.dat"         ----  opens  file  "data.dat"  for  input
         OPEN  "UC",#1,"localhost",80  ----  opens  port  80  of  localhost  for  read  and#
                                                      write
         OPEN  "UX:9600,N,8,1,XON,CTS,DTR",#1,"/dev/ttyS1"
                     ----  open  COM2  for  input  and  output  with  9600:8:N:1  with
                            software  flow  control  and  hardware  flow  control  and  also
                            drop  DTR  line  and  raise  it  again.
         OPEN  "UY",#1,"0x1c1e:0x0101"  ---  opens  USB  device  VID=0x1c1e,  PID=0x101
                                                      for  read  and  write.



SEE ALSO:           CLOSE, EXIST(), INPUT, LINEINPUT, PRINT, SEEK, LOF(),



                                                            457




6.16.__O_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



EOF(), LOC(), BLOAD, LINK, FREEFILE(), CONNECT, IOCTL(), SEND, RECEIVE,

IOCTL()



                                                            458




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.16.__O___



Command:        OPENW



Syntax:                OPENW  n



DESCRIPTION:



     Opens  a  graphic  window.   There  can  be  up  to  16  graphic  windows  opened.

All graphic output goes to the window which was opened latest.  OPENW can be

used to switch between multiple windows.  Window 1 is opened automatically on

default when the orst graphic command is executed and no other window is already

opened.



SEE ALSO:           CLOSEW, MOVEW, SIZEW, TITLEW, ROOTWINDOW, USEWINDOW



                                                            459




6.16.__O_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Operator:           OR



Syntax:                !num-expression1?  OR  !num-expression2?



DESCRIPTION:



     Used to determine if at least ONE OF the conditions is true. If both expression1

AND expression2 are FALSE (zero), the result is FALSE. Returns -1 for true, 0 for

false.

     Also used to combine bits in binary number operations.  E.g.  (1 OR 8) returns

9.



EXAMPLES:



Print  3=3  OR  4!2           Result:   -1  (true)
Print  3?3  OR  5!3           Result:    0  (false)

PRINT  (30?20  OR  20!30)   Result:   -1  (true)
PRINT  (4  OR  128)           Result:    132



SEE ALSO:           NAND, AND, NOT, NOR, XOR



                             _________________________________*________________________________



                                                            460




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.16.__O___



Function:           OR()



Syntax:                a=OR(b,c)



DESCRIPTION:



     This function returns b OR c



SEE ALSO:           AND(), OR, AND



                                                            461




6.16.__O_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        OUT



Syntax:                OUT  #n,a



DESCRIPTION:



     Writes a byte a to an open (output) channel or ole #n.



SEE ALSO:           PRINT, INP()



                                                            462




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



6.17         P



                                                            463




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           PARAM$()



Syntax:                p$=PARAM$(i%)



DESCRIPTION:



     Returns the i'th word from the commandline.  Usually parameters are passed

this way to a program. The PARAM$(0) usually is the name of the program, which

has been excecuted.  If there are no more parameter words, an empty string will

be returned.



EXAMPLE:



i=1
WHILE  LEN(param$(i))
   IF  LEFT$(param$(i))="-"
      IF  param$(i)="--help"  OR  param$(i)="-h"
         @intro
         @using
      ELSE  IF  param$(i)="--version"
         @intro
         QUIT
      ELSE  IF  param$(i)="-o"
         INC  i
         IF  LEN(param$(i))
           outputfilename$=param$(i)
         ENDIF
      ENDIF
   ELSE
      inputfile$=param$(i)
   ENDIF
   INC  i
WEND



                                                            464




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Command:        PAUSE



Syntax:                PAUSE  !sec?



DESCRIPTION:



     Pauses  !sec?  seconds.  The  resolution  of  this  command  is  microseconds  (in

theory).



     Comment:



     PAUSE can be interrupted by AFTER and EVERY.



SEE ALSO:           DELAY, AFTER, EVERY



                                                            465




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        PBOX



Syntax:                PBOX  x1,y1,x2,y2



DESCRIPTION:



     Draws a olled box with coordinates x1,y1 and x2,y2.



SEE ALSO:           BOX, RBOX, DEFFILL, COLOR



                                                            466




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Variable:            PC



Syntax:                i%=PC



DESCRIPTION:



     Returns the Program counter value. This is normally the line number of the line

actually processed, or the pointer into bytecode of the code actually processed.



SEE ALSO:           SP



                                                            467




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        PCIRCLE



Syntax:                PCIRCLE  x%,y%,r%[,a1,a2]



DESCRIPTION:



     Draws a olled circle (or sector) at center coordinates x,y with radius r and op-

tional starting angle a1 and ending angle a2 (in radians).



SEE ALSO:           CIRCLE, DEFFILL, COLOR



                                                            468




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Function:           PEEK()



Syntax:                !int-result?=PEEK(!address?)



DESCRIPTION:



     PEEK() reads a byte from an address in memory. The following example dumps

a section of the internal memory near a string t$.



EXAMPLE:



t$="Hallo,  this  is  a  string..."
i=varptr(t$)-2000
DO
   PRINT  "$";HEX$(i,8)'
   FOR  iu=0  TO  15
      PRINT  HEX$(PEEK(i+iu)  and  255,2)'
   NEXT  iu
   PRINT  '
   FOR  iu=0  TO  15
      a=PEEK(i+iu)
      IF  a?31
         PRINT  CHR$(a);
      ELSE
         PRINT  ".";
      ENDIF
   NEXT  iu
   PRINT
   ADD  i,16
LOOP



SEE ALSO:           POKE



                                                            469




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        PELLIPSE



Syntax:                PELLIPSE  x,y,a,b[,a1,a2]



DESCRIPTION:



     Draws a olled ellipse (or or elliptic sector) at center coordinates x,y with radii a

and b.



SEE ALSO:           PCIRCLE, ELLIPSE, DEFFILL, COLOR



                                                            470




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Variable:            PI



Syntax:                a=PI



DESCRIPTION:



     Returns the value of PI. The value of PI is 3.1415926535... etc.



SEE ALSO:           SIN(), COS(), EXP()



                                                            471




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        PIPE



Syntax:                PIPE  #n1,#n2



DESCRIPTION:



     PIPE links two ole channels n1 and n2 together to form a pipe. n1 is for reading,

n2 is for writing.  Whatever you write to the pipe can be read from it at a dioeerent

time.  The content is buoeered in the kernel.  The mechanism is FIFI (0 orst in orst

out).   The  biggest  advantage  is,  that  you  can  read  and  write  to  it  from  dioeerent

processes (created by FORK()). This allows inter-process communication.



EXAMPLE:



PIPE  #1,#2
PRINT  #2,"Hello,  get  me  out  of  the  pipe..."
FLUSH  #2
LINEINPUT  #1,t$
PRINT  t$



SEE ALSO:           CLOSE, OPEN, FORK()



                                                            472




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Command:        PLAYSOUND



Syntax:                PLAYSOUND  channel,s$



DESCRIPTION:



     PLAYSOUND plays a WAV sample on the sound card. s$ must contain the data

from a sound ole.  (WAV format).  The sample is then played once on the channel

c. If c is -1 a free channel is selected. There are 16 channels.



     Comment:



     Currently this only works in the MS WINDOWS or SDL version.  On ANDROID

please use the PLAYSOUNDFILE command, see below.



EXAMPLE:


           OPEN  "I",#1,"sound.wav"
           t$=INPUT$(#1,LOF(#1))
           CLOSE  #1
           PLAYSOUND  ,t$



SEE ALSO:           SOUND



                                                            473




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        PLAYSOUNDFILE



Syntax:                PLAYSOUNDFILE  filename$



DESCRIPTION:



     PLAYSOUNDFILE  play  a  soundole  of  standard  ole  formats  like  WAV,  OGG,

MP3.  The sound is played in the background.  Any previously played sounds will

be stopped if they have not been onished so far.  (currently this only works in the

ANDROID version of X11-Basic.)



     Comment:



     You should use absolute paths for the ole names.



EXAMPLE:


           PLAYSOUNDFILE  "/mnt/sdcard/bas/explosion.ogg"
           PLAYSOUNDFILE  DISR$(0)+"/explosion.ogg"



SEE ALSO:           SOUND, PLAYSOUND, DIR$()



                                                            474




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Command:        PLIST



Syntax:                PLIST  [#n]



DESCRIPTION:



     Outputs  a  formatted  listing  of  the  actual  program  in  memory.   If  an  open  ole

channel is given, the listing will be dumped into that ole.  Also the internal tokens

are printed ans some internal Information. This is intended for internal use only.



EXAMPLE:



?  PLIST
    0:  $00001a  ---    0,0  ---CLS
    1:  $000279  ---    0,0  ---PRINT
    2:  $000279  ---    0,1  ---PRINT  "  example  how  to  use  the  ANSI  color  spec."
    3:  $000279  ---    0,0  ---PRINT
    4:  $000279  ---    0,1  ---PRINT  "X  0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5  6  7  8  9  0"
    5:  $310240  ---   12,1  ---FOR  U=0  TO  3
    6:  $310240  ---   11,1  ---   FOR  J=0  TO  7
    7:  $310240  ---   10,1  ---      FOR  I=0  TO  7
    8:  $000279  ---    0,1  ---         PRINT  AT(J+6,2*I+2+16*U);CHR$(27)+"["+STR$(U)+"
                                                  ";"+STR$(30+I)+";"+STR$(40+J)+"m  *";
    9:  $320266  ---    7,1  ---      NEXT  I
   10:  $320266  ---    6,1  ---   NEXT  J
   11:  $320266  ---    5,1  ---NEXT  U
   12:  $000279  ---    0,0  ---PRINT
   13:  $00047f  ---    0,0  ---QUIT
   14:  $0008ff  ---    0,0  ---=?=?  2303



SEE ALSO:           LIST, DUMP



                                                            475




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        PLOT



Syntax:                PLOT  x,y



DESCRIPTION:



     Draws a point (single pixel) at screen coordinate x,y



SEE ALSO:           LINE, POINT(), COLOR



                                                            476




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Function:           PNGDECODE$()



Syntax:                bmp$=PNGDECODE$(png$)



DESCRIPTION:



     Converts the content of png$ which should contain data of a Portable Network

Graphics format into a bmp data format which then can be pasted to the screen

with PUT.



EXAMPLE:


   OPEN  "I",#1,"image.png"
              png$=INPUT$(#1,LOF(#1))
   CLOSE  #1
   bmp$=PNGDECODE$(png$)
              PUT  32,32,bmp$           !  display  the  image
   SHOWPAGE



SEE ALSO:           PUT, PNGENCODE$()



                                                            477




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           PNGENCODE$()



Syntax:                png$=PNGENCODE$(bmp$)



DESCRIPTION:



     Converts bitmap data in bmp$ into the Portable Network Graphics format.  The

content of png$ can then be saved into a ole with ending .png.



EXAMPLE:


    SGET  screen$      !  save  the  graphics  screen  content  in  screen$
    png$=PNGENCODE$(screen$)
    BSAVE  "screen.png",varptr(png$),len(png$)



SEE ALSO:           GET, SGET, BSAVE, PNGDECODE$()



                                                            478




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Function:           POINT()



Syntax:                c=POINT(x,y)



DESCRIPTION:



     Returns the color of the graphic point x,y in the current window. The color values

are of the same format than those used by COLOR and returned by GET.COLOR().



SEE ALSO:           PLOT, COLOR



                                                            479




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        POKE



Syntax:                POKE  adr%,byte%



DESCRIPTION:



     POKE writes a byte to address adr% of the program memory.



SEE ALSO:           PEEK(), DPOKE, LPOKE



                                                            480




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Command:        POLYFILL



Syntax:                POLYFILL  n,x(),y()[,x.off,y.off]



DESCRIPTION:



     POLYFILL  draws  a  olled  polygon  with  n  corners.  The  x,y  coordinates  for  the

corner points are given in arrays x() and y().  The optional parameters x.ooe,y.ooe

will be added to each of these coordinates.

     POLYFILL  olls  the  polygon  with  the  color  and  pattern  previously  deoned  by

COLOR and DEFFILL.



SEE ALSO:           COLOR, DEFFILL, POLYLINE, POLYMARK



                                                            481




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        POLYLINE



Syntax:                POLYLINE  n,x(),y()[,x.off,y.off]



DESCRIPTION:



     POLYLINE draws a polygon with n corners.  The x,y coordinates for the corner

points are given in arrays x() and y().  The optional parameters x.ooe,y.ooe will be

added to each of these coordinates.

     To draw a closed polygon, the orst point hast to be equal to the last point.



SEE ALSO:           LINE, DEFLINE, COLOR, POLYFILL, POLYMARK



                                                            482




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Command:        POLYMARK



Syntax:                POLYMARK  n,x(),y()[,x.off,y.off]



DESCRIPTION:



     POLYMARK marks the corner points of an invisible polygon with n corners. The

x,y coordinates for the corner points are given in arrays x() and y().  The optional

parameters x.ooe,y.ooe will be added to each of these coordinates.

     POLYMARK marks the points with the shape deoned by DEFMARK.



SEE ALSO:           COLOR, DEFLINE, POLYLINE, POLYFILL



                                                            483




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           POWM()



Syntax:                c&=POWM(base&,exp&,m&)



DESCRIPTION:



     Return (base raised to exp) modulo m. c=base^exp mod m

     A negative exp is supported if an inverse base^-1 mod m exists.



SEE ALSO:           INVERT()



                                                            484




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Command:        PRBOX



Syntax:                PRBOX  x1,y1,x2,y2



DESCRIPTION:



     Draws a olled box with rounded corners at x1,y1 and x2,y2.



SEE ALSO:           BOX, PBOX, DEFFILL, COLOR



                                                            485




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           PRED()



Syntax:                i=PRED(x)



DESCRIPTION:



     PRED() returns the preceding integer of x.  It returns the biggest integer value

that is less than x.



EXAMPLE:


PRINT  PRED(1.2345)    Result:  1
PRINT  PRED(0.6)         Result:  0
PRINT  PRED(-0.5)       Result:  -1
PRINT  PRED(0)           Result:  -1



                                                            486




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Function:           PRIMORIAL()



Syntax:                w&=PRIMORIAL(i%)



DESCRIPTION:



     Returns the promorial of i%, i.e. the product of all positive prime numbers !=i%.



     Comment:



     This function works only in the interpreter and only when used in a direct as-

signment to a big integer variable. The function is not implemented in some of the

X11-Basic versions.



EXAMPLES:


   w&=LUCNUM(100)   --?  Result:  2305567963945518424753102147331756070



SEE ALSO:           FIB(), LUCNUM()



                                                            487




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           PRG$()



Syntax:                t$=PRG$(i%)



DESCRIPTION:



     PRG$() returns the i'th BASIC program line (source code). It will of course only

work in the interpreter.



     Comment:

This does not work in compiled programs.



SEE ALSO:           TRON, TRACE, TRACE$, PC



                                                            488




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Command:        PRINT



Syntax:                PRINT  [[AT(),TAB(),SPC(),COLOR()]a$--;',"]

                              PRINT  [#n,]a$;b;const;...  USING  ...  --;',"



DESCRIPTION:



     The  print-statement  writes  all  its  arguments  to  the  screen  (standard  output);

after writing its last argument, print goes to the next line (as in PRINT "Hello ",a$,"

!");  to avoid this automatic newline,  place a semicolon (;)  after the last argument

(as  in  PRINT  "Please  enter  your  Name:";).   To  insert  a  tabulator  instead  of  the

automatic newline append a colon (,), e.g. print "Please enter your Name:", . Note

that print can be abbreviated with a single question mark (?).

     The PRINT command has special functions,  which modify the appearance of

the text and the position of the text on the screen.  Namely AT(), TAB(), SPC() and

COLOR(). Also a powerful formatting is possible with PRINT USING.

     If a ole channel of an opened ole is given (n),  the output is written to that ole

instead.



EXAMPLE:


    PRINT  "Hello  ",a$,"  !"
    PRINT  "Please  enter  your  Name:";
    ?  "A  short  form..."



SEE ALSO:           PRINT  AT(), PRINT  COLOR(), PRINT  TAB(), PRINT  SPC(),



                                                            489




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



PRINT USING


                              _________________________________*________________________________



Command:        PRINT    AT()



Syntax:                PRINT  AT(line,row)[;...]



DESCRIPTION:



     For interactive programs you might want to print output at specioc screen loca-

tions.  PRINT AT(lin,row) will place the text cursor at row row line lin.  The top left

corner of the screen corresponds to the position (1,1).



EXAMPLE:


    PRINT  AT(4,7);"Test"
    PRINT  AT(3,1);"    This  is  a  Title    "



SEE ALSO:           GPRINT, COLS, ROWS, CRSCOL, CRSLIN



                             _________________________________*________________________________



                                                            490




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Command:        PRINT    TAB()    SPC()



Syntax:                PRINT  TAB(x)[;...]

                              PRINT  SPC(x)[;...]



DESCRIPTION:



     TAB(x) and SPC(x) move the text cursor x positions to the right.  TAB starts at

the beginning of the line,  SPC at current cursor position.  So TAB is an absolute

and SPC a relative movement.



EXAMPLE:


    PRINT  "Hallo";TAB(30);"Test"
    PRINT  "Hallo";SPC(30);"Test"



SEE ALSO:           GPRINT, COLS, ROWS, CRSCOL, CRSLIN



                             _________________________________*________________________________



Command:        PRINT    COLOR()



                                                            491




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Syntax:                PRINT  COLOR(s[,s2,...])



DESCRIPTION:



     Changes the foreground and background text color and also sets the style at-

tributes for the console text.

     The  COLOR  statement  s  can  be  of  three  types  depending  on  their  number

range. Their meaning is:


    Text  Mode:                      Text  color:              Background  color:



    0    default  setting      30    black                  40    black

    1    intensive                  31    red                      41    red

    2    dark                           32    green                  42    green

                                             33    yellow                43    yellow

    4    underline                  34    blue                    44    blue

    5    blink                          35    magenta              45    magenta

                                             36    cyan                    46    cyan

    7    reverse                      37    white                  47    white


You  can  pass  one  or  more  arguments  to  the  COLOR()  function  to  combine  the

attributes and colors.



EXAMPLE:


PRINT  COLOR(32,2);"Hallo"



SEE ALSO:           COLOR()



                                                            492




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Command:        PRINT    USING



Syntax:                PRINT  a$  USING  format$



DESCRIPTION:



     To  control  the  way  numbers  are  printed,  use  the  PRINT  USING  statement:

PRINT 12.34 USING "###.####" produces 12.3400. The format string ("###.####")

consists of hashes (#) with one optional dot and it pictures the appearance of the

number  to  print.   For  all  the  details  of  this  command  please  read  the  X11-Basic

user manual.



EXAMPLE:


PRINT  12.34  USING  "###.####"



SEE ALSO:           STR$(), USING$()



                                                            493




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        PROCEDURE



Syntax:                PROCEDURE  procname  [(p1  [,p2]  ...  )]  *  RETURN



DESCRIPTION:



     PROCEDURE  starts  a  user-deoned  multi-line  subroutine  which  can  be  exe-

cuted  by  the  GOSUB  command.   Any  number  of  parameters  may  be  passed  to

the  PROCEDURE  via  the  parameter  list.   The  variables  in  that  list  act  like  local

variables inside the subroutine.

     All variables declared inside the PROCEDURE block are global variables unless

you declare them as local with the LOCAL command.  Variables in the calling line

reach the PROCEDURE "by-value" unless the VAR keyword is used in the calling

line.  In  that  case,  the  variable  is  passed  "by-reference"  to  the  PROCEDURE  so

that the PROCEDURE "gets" the variable and not only its value. Variables passed

"by-reference"  can  be  changed  by  the  PROCEDURE.  The  PROCEDURE  block

is terminated by the RETURN statement which resumes execution of the calling

expression.   Unlike  a  FUNCTION-subroutine,  a  PROCEDURE  can  not  return  a

value.

     Procedures  are  usually  deoned  at  the  end  of  the  program  source  code.  The

program AEow may not hit a procedure or function deonition.  In this case it would

produce an error 36 - error in program structure.  If you want them in the middle of

the "main" part, use GOTOs to jump over them.



EXAMPLE:


           PRINT  "this  is  the  main  part  of  the  program
           GOTO  a
           PROCEDURE  b
              PRINT  "this  is  inside  the  procedure..."
           RETURN



                                                            494




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



           a:
           PRINT  "go  on"
           GOSUB  b
           END



SEE ALSO:           GOSUB, RETURN, LOCAL, FUNCTION



                                                            495




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        PROGRAM



Syntax:                PROGRAM  !title?



DESCRIPTION:



     This statement does nothing.  it is ignored.  It can be used to specify a title to

the program.  In future releases this statement may be used to pass some options

to the compiler.



SEE ALSO:           REM



                                                            496




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Function:           PTST()



Syntax:                c=PTST(x,y)



DESCRIPTION:



     PTST returns the color of the graphic point x,y in the current window.  It is the

same as POINT().



SEE ALSO:           POINT(), PLOT



                                                            497




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        PUBLISH



Syntax:                PUBLISH  topic$,message$[,qos,retained]



DESCRIPTION:



     Publishes a message to the topic on a (mqtt) broker. You can optionally specify

the quality of service (0-2) and the retained-AEag (0,1).  By default the retained AEag

is 1 if the qos is 0. If qos?0 the default for retained is 1.



EXAMPLE:



BROKER  "tcp://localhost:1883"
PUBLISH  "TIME",time$



SEE ALSO:           BROKER, SUBSCRIBE



                                                            498




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Command:        PUT



Syntax:                PUT  x,y,var$[,scale[,trans[,xs,ys,w,h],angle]]



DESCRIPTION:



     Maps a graphic bitmap contained in var$ into the graphic window at coordinate

x,y.  The picture can be scaled by scale factor (default:  1).  The ole or data format

used in var$ is a BMP ole format. It can contain uncompressed bitmaps optionally

with alpha channel.

     If you want to paint only a portion of the image you can specify the coordinates,

width and height of a rectangular area of the source image (after scaling).

     (*not implemented yet: a rotation angle and if transparency is given (trans) and

the  picture  has  a  color  table,  this  is  interpreted  as  a  color  index,  which  will  be

treated as transparent.  If an alpha channel is present, this is used as a threshold

for the alpha value (0-255).  Default is 32.  If the coordinates xs,ys,w,h are given,

only a rectangular part of the image is mapped.)

     If you want to use .png oles for your icons to be mapped with PUT, orst convert

them  with  PNGDECODE$()  to  BMP.  Also  the  alpha  channel  can  be  preserved.

The images also can be included into the sourcecode of the program. See the tool

inline.bas on how to make inline data.



     Comment:



     You must avoid to put the image or parts of the image outside of the screen.

Always make sure, that the image or the specioed portion of the image ots on the

screen.



                                                            499




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



EXAMPLE:



         OPEN  "I",#1,"picture.bmp"
         t$=INPUT$(#1,LOF(#1))
         CLOSE  #1
         CLEARW
         PUT  0,0,t$,2                     !  scaled  by  a  factor  of  2
         PUT  100,100,t$,,,0,32,32,32   !  32x32  portion  of  the  image  is  put
         SHOWPAGE



SEE ALSO:           GET, PUT.BITMAP, PNGDECODE$()



                                                            500




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.17.__P__



Command:        PUTBACK



Syntax:                PUTBACK  [#n,]a



DESCRIPTION:



     Puts a character back into an input channel #n.



SEE ALSO:           OUT



                                                            501




6.17.__P_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        PUT.BITMAP



Syntax:                PUT.BITMAP  bitmp$,x,y,w,h



DESCRIPTION:



     Maps  a  monochrome  bitmap  contained  in  bitmp$  into  the  graphic  window  at

coordinate x,y.  The bitmap is stored in raw format,  so you must specify the size

of the bitmap with w (width) and h (height) in pixels.  The Bitmap is drawn with the

color set by COLOR and transparency if set with GRAPHMODE. You must avoid

to put the bitmap or parts of it outside the screen.  The bitmap data format is such

that the least signiocant bit of each byte is drawn to the left.  Each line must start

on a new byte. So a 9x12 Bitmap stores in 24 Bytes.



SEE ALSO:           PUT, COLOR, GRAPHMODE



                                                            502




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.18.__Q___



6.18         Q



                                                            503




6.18.__Q_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        QUIT



Syntax:                QUIT  [!return-code?]



DESCRIPTION:



     QUIT exits the interpreter.  You may set a !return-code? which will be passed

to the program which has called the interpreter.



SEE ALSO:           END



                                                            504




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



6.19         R



                                                            505




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           RAD()



Syntax:                r=RAD(x)



DESCRIPTION:



     Converts x from degrees to radians.



EXAMPLE:


           PRINT  RAD(180)         !  Result:  3.14159265359



SEE ALSO:           DEG()



                                                            506




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Function:           RADIX$()



Syntax:                a$=RADIX$(x%[,base%[,len%]])



DESCRIPTION:



     RADIX$() returns a string containing the representation of the integer number

x% in base base%.  A minimal length of the string can be specioed with len%.  If

len% is bigger than necessary, preceiding zeros will be used to oll in.  The base%

can be between 2 and 62 inclusive. If base% is not specioed it defaults to 62. The

symbols used are digits from 0 to 9 then capital letters A to Z and then lowercase

letters a to z, followed by @ and $.



EXAMPLE:


           PRINT  RADIX$(180,17)         !  Result:  AA



SEE ALSO:           BIN$(), OCT$(), HEX$()



                                                            507




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           RAND()



Syntax:                r%=RAND(0)



DESCRIPTION:



     RAND()  returns  a  pseudo-random  integer  number  between  0  (inclusive)  and

2147483647.   The  sequence  of  pseudo-random  numbers  is  identical  each  time

you start the interpreter unless the RANDOMIZE statement is used prior to using

RANDOM():  RANDOMIZE seeds the pseudo-random number generator to get a

new sequence of numbers from RANDOM().



     Comment:



     On WINDOWS operating systems, the RAND() function returns a pseudo-random

integer number between 0 (inclusive) and 32767.



SEE ALSO:           RND(), RANDOMIZE, GASDEV



EXAMPLE:


   RANDOMIZE  TIMER
   FOR  i=0  TO  10000
      a=MAX(a,RAND(0))
   NEXT  i
   PRINT  a,HEX$(a)



                                                            508




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



SEE ALSO:           RANDOM(), RND(), RANDOMIZE, GASDEV



                                                            509




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           RANDOM()



Syntax:                r%=RANDOM(maximum%)

                              r&=RANDOM(maximum&)

                              r=RANDOM(maximum)

                              r#=RANDOM(maximum#)



DESCRIPTION:



     RANDOM()  returns  a  pseudo-random  (integer)  number  between  0  (inclusive)

and maximum% (exclusive). The sequence of pseudo-random numbers is identical

each time you start the interpreter unless the RANDOMIZE statement is used prior

to using RANDOM():  RANDOMIZE seeds the pseudo-random number generator

to get a new sequence of numbers from RANDOM().  If the argument is a AEoating

point or complex expression, a random AEoatingpoint or complex number between

0 (inclusive) and maximum (exclusive) is returned.



     Comment:



     If the argument to the RANDOM() function is negative,  a random number be-

tween the argument (exclusive) and zero (inclusive) is returned.



     Comment:



     WINDOWS operating systems uses a 15 bit random generator only and linux

AEavours a 31 bit random generator.



                                                            510




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



EXAMPLE:


           PRINT  RANDOM(10)      !    Result:  8
           PRINT  RANDOM(-10)    !    Result:  -8
PRINT  RANDOM(10.1)   !    Result:  8.065922004714
PRINT  RANDOM(1+2i)   !    (0.9116473579368+1.596880066952i)
PRINT  RANDOM(10000000000000000000)  !  Result:  7314076133279565627



SEE ALSO:           RND(), RANDOMIZE, GASDEV



                                                            511




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        RANDOMIZE



Syntax:                RANDOMIZE  [!seed-expression?]



DESCRIPTION:



     RANDOMIZE  seeds  the  pseudo-random  number  generator  to  get  a  new  se-

quence  of  numbers  from  RND().  Recommended  argument  to  RANDOMIZE  is  a

"random" number to randomly select a sequence of pseudo-random numbers.  If

RANDOMIZE is not used then the sequence of numbers returned by RND() will be

identical each time the interpreter is started.  If no argument is given, the TIMER

value will be used as a seed.



SEE ALSO:           RND(), TIMER



                                                            512




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Command:        RBOX



Syntax:                RBOX  x1,y1,x2,y2



DESCRIPTION:



     Draws a rectangle with rounded corners from the two diagonally opposite corner

points 'x1,y1' and 'x2,y2'



SEE ALSO:           BOX, PBOX, PRBOX



                                                            513




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        READ



Syntax:                READ  var[,var2,  ...]



DESCRIPTION:



     Reads constant values from a DATA command and assigns them to a variable

'var'. Reading is taken from the last point a RESTORE was done (if any).



SEE ALSO:           DATA, RESTORE



                                                            514




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Function:           REAL()



Syntax:                x=REAL(z#)



DESCRIPTION:



     Returns the real part of the complex number z#.



EXAMPLE:


PRINT  REAL(1-2i)       Result:  1



SEE ALSO:           CONJ(), IMAG()



                                                            515




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           REALLOC



Syntax:                adr.new%=REALLOC(adr%,newsize%)



DESCRIPTION:



     The realloc() function changes the size of the memory block pointed to by adr%

to newsize% bytes.  The contents will be unchanged in the range from the start of

the region up to the minimum of the old and new sizes. If the new size is larger than

the old size, the added memory will not be initialized.  If adr% is 0, then the call is

equivalent to MALLOC(newsize%), for all values of newsize; if newsize is equal to

zero, and adr% is not 0, then the call is equivalent to FREE(adr%).  Unless adr%

is 0, it must have been returned by an earlier call to MALLOC(), or REALLOC().  If

the area pointed to was moved, a FREE(adr%) is done.



SEE ALSO:           MALLOC(), FREE



                                                            516




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Command:        RECEIVE



Syntax:                RECEIVE  #n,t$[,a]



DESCRIPTION:



     RECEIVE  is  used  to  receive  messages  t$  from  a  socket  or  USB-device  #n,

which has been opened with OPEN before.  If a is given, this variable will take the

host address of the sender (IPv4 32 bit format) or the bluetooth device ID.



SEE ALSO:           OPEN, SEND



                                                            517




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           REGEXP()



Syntax:                a%=REGEXP(a$,r$)



DESCRIPTION:



     Searches to see if a substring matching the regular expression r$ is present in

a$ and returns its position.  If no matching substring is found in a$, 0 is returned.

In case of an ERROR in the regular expression, -1 is returned.



     Comment:



     Regular expressions are very powerful in pattern matching.  Compared to IN-

STR()  or  GLOB()  you  have  nearly  inonite  AEexibility.   If  you  do  not  know  what  a

regular expression is or what the syntax of it should be, please look elsewhere for

information.  An full explanation would be too much for this manual.  Unfortunately

there  are  many  dioeerent  standards  for  regular  expression.   The  Implementation

uses here is the so called "POSIX.2" type. Note: Zero-Bytes (CHR$(0)) cannot be

matched and will indicate the end of the content of a$.



     Comment:



     This command is currently no available in the WINDOWS version of X11-Basic.



EXAMPLES:


t$="This  1  is  nice  2  so  33  for  4254"
PRINT  REGEXP(t$,"([[:digit:]]+)[^[:digit:]]+([[:digit:]]+)")



                                                            518




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Result:  6



SEE ALSO:           INSTR(), RINSTR(), GLOB(), MATCH()



                                                            519




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        RELSEEK



Syntax:                RELSEEK  [#]n,d



DESCRIPTION:



     Place ole pointer on new relative position d which means it moves the ole pointer

forward (d?0) or backwards (d!0) d bytes.



SEE ALSO:           SEEK, LOC(), LOF(), EOF()



                                                            520




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Command:        REM    ABBREV.    '



Syntax:                REM  This  is  a  comment

                              '  This  also  is  a  comment



DESCRIPTION:



     This command reserves the entire line for a comment.



     Comment:



     Note, that rem is an abbreviation for remark.

     Do use comments in your programs, the more the better.  Yes, the program will

become longer, but it's nice to be able to understand a well-documented program

that you've never seen before.  Or one of your own masterpieces that you haven't

looked at for a couple of years.  Don't worry about the speed of your program, the

slowdown is only marginally.  A comment after '!'  has no inAEuence on the speed of

a program at all, so you can use these everywhere.



SEE ALSO:           !



                                                            521




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        RENAME



Syntax:                RENAME  oldpathfilename$,newpathfilename$



DESCRIPTION:



     RENAME  renames  a  ole,  moving  it  between  directories  if  required.   If  new-

patholename$ already exists it will be atomically replaced.  oldpatholename$ can

specify a directory. In this case, newpatholename$ must either not exist, or it must

specify an empty directory.



EXAMPLE:


RENAME  "myfile.dat","/tmp/myfile.dat"



SEE ALSO:           KILL, OPEN



                                                            522




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Command:        REPEAT



Syntax:                REPEAT  ...  UNTIL  !expression?



DESCRIPTION:



     REPEAT initiates a REPEAT...UNTIL loop.  The loop ends with UNTIL and ex-

ecution reiterates until the UNTIL !expression? is not FALSE (not null).  The loop

body is executed at least once.



SEE ALSO:           DO, LOOP, UNTIL, EXIT  IF, BREAK, WHILE



EXAMPLE:


           REPEAT
                 INC  n
           UNTIL  n=10



                                                            523




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           REPLACE$()



Syntax:                n$=REPLACE$(t$,s$,r$)



DESCRIPTION:



     REPLACE$() returns string-expression where all search strings s$ have been

replaced by r$ in t$.



SEE ALSO:           INSTR(), WORT.SEP



EXAMPLE:


          PRINT  REPLACE$("Hello","l","w")
          Result:  Hewwo



                                                            524




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Command:        RESTORE



Syntax:                RESTORE  [!label?]



DESCRIPTION:



     RESTORE sets the position DATA is read from to the orst DATA line of the pro-

gram (or to the orst DATA line after !label? if RESTORE is used with an argument).



SEE ALSO:           DATA, READ



EXAMPLE:


           READ   a,  b,  c
           RESTORE
           READ   a,  b,  c
           DATA   1,  2,  3



                                                            525




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        RESUME



Syntax:                RESUME

                              RESUME  NEXT

                              RESUME  !label?



DESCRIPTION:



     The RESUME command is especially meaningful with error capture (ON ER-

ROR  GOSUB)  where  it  allows  a  reaction  to  an  error.  Anyway,  X11-Basic  allows

the us of RESUME !label? everywhere in the program (instead of GOTO !label?),

and can be used to jump out of a subroutine.  If you jump into another Subroutine,

you  must  not  reach  its  RETURN  statement.  RESUME  is  a  bad  command  and  I

dislike it very much.

     RESUME repeats the erroneous command. RESUME NEXT resumes program

execution after an incorrect command. RESUME !label? branches to the !label?.

If a fatal error occurs only RESUME !label? is possible



     Comment:



     **** RESUME is still not working. If you use ON ERROR GOSUB to a subroutine

then  RESUME  NEXT  is  the  default  if  the  subroutine  reaches  a  RETURN.  If  you

want to resume somewhere else you can just GOTO out of the subroutine.  This is

possible, but leaves the internal stack pointer incremented, so you should not do

this too often during run-time.  Otherwise there will be a stack overAEow after 200

events.

     **** looks like this also happens with ON ERROR GOTO.

     *** In future versions of X11-Basic there might be a RESUME !label? command

which properly resets the stack.  If you want this to be oxed,  please send me an

email with your test program.



                                                            526




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



SEE ALSO:           ON  ERROR, GOTO, ERROR



                                                            527




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        RETURN



Syntax:                RETURN

                              RETURN  !expression?



DESCRIPTION:



     RETURN terminates a PROCEDURE reached via GOSUB and resumes execu-

tion after the calling line.  Note that code reached via ON ERROR GOSUB should

be terminated with a RESUME NEXT, not with RETURN.

     RETURN !expression? states the result of the expression as a result of a user

deoned function. This can not be used in PROCEDURES but in FUNCTIONS. The

expression must be of the type the function was.



EXAMPLE:


           PROCEDURE  testroutine
                 PRINT  "Hello  World  !"
           RETURN
           FUNCTION  givemefive
                 RETURN  5
           ENDFUNCTION



SEE ALSO:           PROCEDURE, FUNCTION, ENDFUNCTION, RESUME, GOSUB, @,



ON ERROR



                                                            528




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Function:           REVERSE$()



Syntax:                a$=REVERSE$(t$)



DESCRIPTION:



     Return the reverses of a string.



EXAMPLE:


print  reverse$("Markus  Hoffmann")
Result:  nnamffoH  sukraM



SEE ALSO:           UPPER$(), TRIM$()



                                                            529




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           RIGHT$()



Syntax:                a$=RIGHT$(t$[,number])



DESCRIPTION:



     RIGHT$() returns the specioed number of characters from its string argument,

beginning at its right side. If the number of characters is not specioed then RIGHT$()

returns only the rightmost character.



SEE ALSO:           LEFT$(), MID$()



EXAMPLE:


          PRINT  RIGHT$("Hello",1)
          Result:  o



                                                            530




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Function:           RIGHTOF$()



Syntax:                a$=RIGHTOF$(t$,s$)



DESCRIPTION:



     RIGHTOF$() returns the right part of t$ at the position of the orst occurrence of

s$ in t$. If s$ is not contained in t$, an empty string is returned.



SEE ALSO:           RIGHTOF$(), MID$()



EXAMPLE:


          PRINT  RIGHTOF$("Hello","ll")
          Result:  o



                                                            531




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           RINSTR()



Syntax:                !int-result?=RINSTR(s1$,s2$[,n])



DESCRIPTION:



     Operates in same way as INSTR except that search begins at the right end of

s1$.

     If the string s2$ is not found in s1$, a 0 is returned.  If found, the start position

of s2$ in s1$ is returned.

     If n is specioed, the comparison starts at at position n instead of the end of the

string s1$



SEE ALSO:           INSTR()



                                                            532




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Function:           RLD$()



Syntax:                a$=RLD$(a$)



DESCRIPTION:



     Does a run length decoding of string a$.  This function reverses the run length

encoding function RLE$() on a string.

     In the input string, any two consecutive characters with the same value AEag a

run.  A byte following those two characters gives the count of additional(!)  repeat

characters, which can be anything from 0 to 255.



EXAMPLE:


PRINT  RLD$("1233"+CHR$(8)+"456")
Result:  123333333333456



SEE ALSO:           RLE$()



                                                            533




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           RLE$()



Syntax:                a$=RLE$(a$)



DESCRIPTION:



     Does a run length encoding of string a$.

     In the output string, any two consecutive characters with the same value AEag a

run.  A byte following those two characters gives the count of additional(!)  repeat

characters,  which  can  be  anything  from  0  to  255.   The  resulting  string  might  be

shorter  than  the  input  string  if  there  are  many  equal  characters  following  each

other. In the worst case the resulting string will be 50% longer.



EXAMPLE:


PRINT  RLE$("123.....................................456")
Result:  123..#456



SEE ALSO:           RLD$()



                                                            534




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Command:        RMDIR



Syntax:                RMDIR  !path-name?



DESCRIPTION:



     RMDIR deletes a directory, which must be empty.



EXAMPLE:


RMDIR  "old"



SEE ALSO:           MKDIR, CHDIR



                                                            535




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           RND()



Syntax:                r  =  RND([!dummy?])



DESCRIPTION:



     RND()  returns  a  pseudo-random  number  between  0  (inclusive)  and  1  (exclu-

sive)  with  a  uniform  distribution.   The  sequence  of  pseudo-random  numbers  is

identical each time you start the interpreter unless the RANDOMIZE statement is

used prior to using RND():  RANDOMIZE seeds the pseudo-random number gen-

erator to get a new sequence of numbers from RND().  The optional dummy pa-

rameter is ignored. The granularity of the random values depends on the operating

system and is usually only 31 bits.



     Comment:



     On WINDOWS operating systems, the granularity of the RND() function is only

15 bit.



SEE ALSO:           RANDOMIZE, GASDEV(), RANDOM()



EXAMPLE:


           PRINT  RND(1)
           Result:  0.3352227557149



                                                            536




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Function:           ROL()



Syntax:                i%=ROL(j%,n%[,b%])



DESCRIPTION:



     Returns the bit pattern in j% rotated left by n% bits.  The optional oeld length

b% defaults to 32.



EXAMPLE:


PRINT  ROL(8,2)       !   Result:  32
PRINT  ROL(8,2,4)    !   Result:  2



SEE ALSO:           SHL(), ROR()



                                                            537




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        ROOTWINDOW



Syntax:                ROOTWINDOW



DESCRIPTION:



     Directs all following graphic output to the root window of the screen.  (root win-

dow = desktop background).



     Comment:



     The root window is usually the desktop background. Not in any case is the root

window really shown. On linux systems the GNOME desktop always overwrites the

root window,  so output of X11-Basic is not visible.  Use another windowmanager

like fvwm2 instead.



SEE ALSO:           USEWINDOW



                                                            538




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Function:           ROOT()



Syntax:                b&=ROOT(a&,n%)



DESCRIPTION:



     Returns the truncated integer part of the nth root of a.



SEE ALSO:           SQRT()



                                                            539




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           ROR()



Syntax:                i%=ROR(j%,n%[,b%])



DESCRIPTION:



     Returns the bit pattern in j% rotated right by n% bits.  The optional oeld length

b% defaults to 32.



EXAMPLE:


PRINT  ROR(8,2)       !   Result:  2
PRINT  ROR(8,2,3)    !   Result:  8
PRINT  ROR(8,4,8)    !   Result:  128



SEE ALSO:           SHR(), ROL()



                                                            540




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Function:           ROUND()



Syntax:                b=ROUND(a[,n])



DESCRIPTION:



     Rounds ooe a value to n fractional digits.  If n!0:  round to digits in front of the

decimal point.



SEE ALSO:           INT(), FIX(), FLOOR(), TRUNC()



                                                            541




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            ROWS



Syntax:                n%=ROWS



DESCRIPTION:



     Returns the number of rows of the text terminal (console).



EXAMPLE:


   PRINT  COLS,  ROWS       !  Result:  80         24



SEE ALSO:           COLS, PRINT  AT(), CRSCOL, CRSLIN



                                                            542




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Command:        RSRC.FREE



Syntax:                RSRC.FREE



DESCRIPTION:



     RSRC.FREE unloads the graphical resources loaded with RSRC.LOAD and

frees any memory assigned to it.



SEE ALSO:           RSRC.LOAD



                                                            543




6.19.__R_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        RSRC.LOAD



Syntax:                RSRC.LOAD  filename$



DESCRIPTION:



     RSRC.LOAD  loads  a  GEM  resource  ole  (*.rsc)-File  (ATARI  ST  format)  into

memory and prepares it to be used.



SEE ALSO:           RSRC.FREE, OBJ.DRAW(), FORM.DO()



                                                            544




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.19.__R__



Command:        RUN



Syntax:                RUN



DESCRIPTION:



     starts program execution (RUN)



SEE ALSO:           STOP, CONT, LOAD



                                                            545




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



6.20         S



                                                            546




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SAVE



Syntax:                SAVE  [a$]



DESCRIPTION:



     SAVE writes the BASIC-program into a ole with the name a$.  If no olename is

specioed the program will be saved to the ole which was loaded before.



EXAMPLE:



   SAVE  "new.bas"



SEE ALSO:           LOAD



                                                            547




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SAVESCREEN



Syntax:                SAVESCREEN  t$



DESCRIPTION:



     Saves the whole Graphic-screen (desktop) into a ole with name t$. The graphics

format is XWD (X Window Dump image data) on UNIX systems and BMP (device

independent bitmap image) else.



EXAMPLE:



   SAVESCREEN  "fullscreen.bmp"



SEE ALSO:           SAVEWINDOW



                                                            548




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SAVEWINDOW



Syntax:                SAVEWINDOW  t$



DESCRIPTION:



     Saves  the  actual  X11-Basic  Graphic-Window  into  a  ole  with  name  t$.   The

graphics format is XWD (X Window Dump image data) on UNIX systems and BMP

(device independent bitmap image) else.



EXAMPLE:



   SAVEWINDOW  "window.bmp"



SEE ALSO:           SAVESCREEN, SGET



                                                            549




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SCOPE



Syntax:                SCOPE  a(),typ,yscale,yoffset

                              SCOPE  y(),x(),typ,yscale,yoffs,xscale,xoffs



DESCRIPTION:



     SCOPE performs an extended polyline on one or two dimensional data.  Draw-

ing and scaling is done very fast.  It is possible to plot a million points and lines at

once.

     The variable typ specioes the type of plot:


              0  --  draw  a  polyline

              1  --  draw  points  (without  lines)

              2  --  draw  impulses


With xscale,  yscale,  xooeset and yooeset you can specify a scaling function to the

data.



EXAMPLE:



   l=2^10
   DIM  a(l)
   SIZEW  ,l,400
   CLEARW
   FOR  i=0  TO  l-1
      a(i)=200/100*@si(3*i/512*2*pi)+i/100*sin(20*i/512*2*pi)
   NEXT  i
   COLOR  COLOR.RGB(1,0.5,0)
   SCOPE  a(),1,-10,300   !  Plot  the  original  function
   FFT  a()                    !  Do  a  Fourier  transformation
   '  Normalize
   FOR  i=0  TO  l-1
      a(i)=a(i)/SQRT(l)
   NEXT  i
   SHOWPAGE



                                                            550




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



   PAUSE  1
   FOR  i=4  TO  86
      a(i)=0
   NEXT  i
   FOR  i=l-1  DOWNTO  l-86
      a(i)=0
   NEXT  i
   FFT  a(),-1
   COLOR  COLOR.RGB(0,1/2,1)
   SCOPE  a(),0,-10/SQRT(l),300   !  Plot  the  modified  function
   SHOWPAGE
   END
   DEFFN  si(x)=x  mod  pi



SEE ALSO:           LINE, POLYLINE



                                                            551




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SCREEN



Syntax:                SCREEN  n



DESCRIPTION:



     This commands select the Screen-Resolution in SVGA-Mode.  It is only avail-

able in the SVGA-Version of X11-Basic and has no eoeect on any other versionid

X11-Basic.

     Following Screen modes are supported:


  n        Mode

================================

  0        TEXT-Mode,  no  graphics

  1            320x  200    16  colors

  2            640x  200    16  colors

  3            640x  350    16  colors

  4            640x  480    16  colors

  5            320x  200  256  colors

  6            320x  240  256  colors

  7            320x  400  256  colors

  8            360x  480  256  colors

  9            640x  480          monochrome

10            640x  480  256  colors

11            800x  600  256  colors

12          1024x  768  256  colors

13          1280x1024  256  colors

14            320x200  15Bit  colors

15            320x200  16Bit  colors

16            320x200  24Bit  colors

17            640x480  15Bit  colors

18            640x480  16Bit  colors



                                                            552




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



19            640x480  24Bit  colors

20            800x600  15Bit  colors

21            800x600  16Bit  colors

22            800x600  24Bit  colors

23            1024x768  15Bit  colors

24            1024x768  16Bit  colors

25            1024x768  24Bit  colors

26            1280x1024  15Bit  colors

27            1280x1024  16Bit  colors

28            1280x1024  24Bit  colors

29            800x  600  16  colors

30            1024x  768  16  colors

31            1280x1024  16  colors

32            720x  348  monochrome    Hercules  emulation  mode

33-37      32-bit  per  pixel  modes.

38-74      additional  resolutions



SEE ALSO:           VGA-Version  of  X11-Basic



                                                            553




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SEEK



Syntax:                SEEK  #n[,d]



DESCRIPTION:



     Place ole pointer of channel n on new absolute position d (Default on position 0

which is the beginning of the ole.)



SEE ALSO:           RELSEEK, LOC(), EOF(), LOF()



                                                            554




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SELECT



Syntax:                SELECT  !expression?



DESCRIPTION:



     Divides a program up into dioeerent blocks depending on the result of the expres-

sion.  Only the integer part of the result of the expression is used to compare with

the values given by CASE statements. Program AEow branches to the block of code,

given by the CASE statement which matches the value of expression.  If no CASE

block matches, it branches to the DEFAULT block.  If no DEFAULT block is given

and none of the CASE blocks match, the program resumes after the ENDSELECT.

Also after the CASE block is onished, the program resumes after the ENDSELECT.

You must not use GOTO out of the SELECT~ENDSELECT block.  (although in the

interpreter this works, the compiler will not compile it correctly.)

     You can leave the block any time with BREAK.



     Comment:



     The statement after SELECT will be evaluated/calculated only once, then com-

pared  to  all  the  values  given  by  the  CASE  statements,  one  by  one  in  the  order

given.   If  the  orst  matches,  the  others  will  not  be  evaluated  anymore.   The  DE-

FAULT section will always match, if no other match before was found. BREAK can

be  used,  but  there  is  no  way  to  CONTINUE  with  the  SELECT  after  one  (CASE)

BLOCK was entered.

     Code between SELECT and the orst CASE or DEFAULT statement will be dead

code and should be avoided.

     If you need to compare AEoating point (real) numbers, you must use a IF ~ ELSE

IF ~ ELSE construct.



                                                            555




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



EXAMPLE:



i=5
SELECT  i
   CASE  1
      PRINT  1
   CASE  2,3,4
      PRINT  "its  2,3,  or  4"
   CASE  5
      PRINT  5
   DEFAULT
      PRINT  "default"
ENDSELECT



SEE ALSO:           CASE, DEFAULT, ENDSELECT, BREAK, IF



                                                            556




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SEND



Syntax:                SEND  #n,msg$[,adr%,port%]



DESCRIPTION:



     SEND is used to transmit a message via fast UDP datagrams to another socket

which may be on another host.  Or, send is used to send a data packet to a pre-

viously  opened  USB  device.   Or,  send  is  used  to  transmit  a  data  packet  to  to  a

previously opened BLUETOOTH L2CAP connection.

     Send with only two parameters may be used only when the socket is in a con-

nected state (see CONNECT), otherwise the destination address and the port has

to be specioed.

     The address of the target is given by adr%,  which usually contains a IP4 ad-

dress (e.g. cvl(chr$(127)+chr$(0)+chr$(0)+chr$(1)) which corresponds to 127.0.0.1).

msg$  can  be  an  arbitrary  message  with  any  data  in  it.   The  length  of  the  mes-

sage must not exceed 1500 Bytes.  If the message is too long to pass automically

through the underlying protocol, an error occurs, and the message is not transmit-

ted.

     No indication of failure to deliver is implicit in a send.

     When the message does not ot into the send buoeer of the socket, send blocks.

The OUT?() function may be used to determine when it is possible to send more

data.



     Comment:



     SEND  is  currently  working  for  USB  and  Bluetooth  devices  only  in  connected

state.



                                                            557




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



EXAMPLE:



   port=5555
   server$="localhost"    !  if  the  receiver  runs  on  the  same  computer
   OPEN  "UU",#1,"sender",port+1
   CONNECT  #1,server$,port
   i=0
   DO
      @sendmessage(i,"The  time  is:  "+date$+"  "+time$+"  "+str$(i))
      WHILE  INP?(#1)
         t$=@getmessage$()
         IF  LEN(t$)
           a=CVI(LEFT$(t$,2))
           PRINT  "received:  ";a;"  ";right$(t$,len(t$)-2)
         ENDIF
      WEND
      INC  i
      PAUSE  1
   LOOP
   CLOSE  #1
   END
   PROCEDURE  sendmessage(id,m$)
      PRINT  "sending  packet  #";id
      SEND  #1,mki$(id)+m$
   RETURN
   FUNCTION  getmessage$()
      LOCAL  t$,adr
      RECEIVE  #1,t$,adr
      pid=CVI(MID$(t$,1,2))
      IF  pid=0
         @sendACK(pid,adr)
      ENDIF
      RETURN  t$
   ENDFUNCTION
   PROCEDURE  sendACK(pid,adr)
      @sendmessage(6,CHR$(pid),adr)
   RETURN



SEE ALSO:           OPEN, CLOSE, CONNECT, RECEIVE, OUT?()



                                                            558




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SENSOR



Syntax:                SENSOR  ON

                              SENSOR  OFF



DESCRIPTION:



     Switches  the  sensor  phalanx  on  or  ooe.   Sensors  can  be  accelerometer,  tem-

perature, pressure, light, humidity, gyroscope, etc...  They need to be switched on,

before you can use them. If you do not use them anymore, you should switch them

ooe to save battery.



SEE ALSO:           GPS, SENSOR?, SENSOR()



                                                            559




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            SENSOR?



Syntax:                a=SENSOR?



DESCRIPTION:



     This system variable is 0 if no sensors are available on this hardware platform,

otherwise the number of usable sensors is returned. Sensors can be accelerome-

ter, temperature, pressure, light, humidity, gyroscope, etc...



SEE ALSO:           GPS, SENSOR, SENSOR()



                                                            560




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Function:           SENSOR()



Syntax:                a=SENSOR(n)



DESCRIPTION:



     Readout the n-th value of the sensor-phalanx. Usually


n=0    --?  Temperature

    1    --?  Ambient  light

    3    --?  Proximity

    4,5,6    --?  Orientation  x,y,z

    7,8,9    --?  Gyroscope      x,y,z

    10,11,12    --?  Magnetic  field  x,y,z

    13,14,15    --?  Accelerometer  x,y,z



SEE ALSO:           GPS, SENSOR, SENSOR?, ANDROID?, GPIO()



                                                            561




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SETENV



Syntax:                SETENV  t$,a$



DESCRIPTION:



     Sets  the  environment  variable  t$  of  the  operating  system  to  the  value  given

by  a$.   The  environment  variables  are  not  persistent  after  a  reboot  or  restart  of

X11-Basic.

     (This command is not yet implemented)



EXAMPLE:


SETENV  "LASTLAUNCHED",DATE$+"  "+time$



SEE ALSO:           ENV$()



                                                            562




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SETFONT



Syntax:                SETFONT  t$



DESCRIPTION:



     Loads and sets a font for graphical text commands. t$ may be


          "SMALL"  or    "5x7"      for  a  small  font,

          "MEDIUM  or    "8x8        for  a  medium  sized  font,

          "BIG"      or    "8x16"    for  a  big  font,

          "LARGE"  or  "16x32"    for  an  even  bigger  font,

          "HUGE"    or  "24x48"    for  an  even  bigger  font,

          "GIANT"  or  "32x64"    for  a  gigantic  font  size.


This setting aoeects the text style and size of the commands TEXT and GPRINT.

     With UNIX and the X-WINDOW system, the font name t$ may be any valid font

name or pattern.  On other platforms true-type font olenames can be used.  This

way, also proportional fonts can be used.



     Comment:



     The support for true-type .TTF fonts is not usable at the moment.  You should

prefer the standard names given obove instead of platform dependant names to

stay platform independant.

     Currently the font setting is overwritten by ALERT, FILESELCT and others every

time they are used.  It is planned to have this independant and also have a way to

independantly change the font sizes and style of the GUI functions, but this is work

in progress.



                                                            563




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



EXAMPLE:


SETFONT  "BIG"
TEXT  100,100,"Hi,  this  is  a  big  font"
SETFONT  "5x7"
TEXT  100,150,"The  small  variant"
SETFONT  "-*-lucidatypewriter-medium-r-*-*-10-*-*-*-m-*-*-*"
TEXT  100,200,"This  may  work  on  a  UNIX  system."
SETFONT  "C:"Arial.ttf"
TEXT  100,200,"This  may  work  on  some  other  platform."



SEE ALSO:           TEXT



                                                            564




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SETMOUSE



Syntax:                SETMOUSE  x,y[,k[,m]]



DESCRIPTION:



     The SETMOUSE command permits the positioning of the mouse cursor under

program control.  The optional parameter k can simulate the mouse button being

pressed or released. The optional parameter m specioes if the coordinates are rel-

ative to the windows origin (m=0, default) or relative to the mouses current position

(m=1).



EXAMPLE:



ROOTWINDOW
i=0
REPEAT
   SETMOUSE  2,i,,1   !  Move  relative  by  2  in  x  and  by  i  in  y
   SHOWPAGE
   PAUSE  0.04
   INC  i
UNTIL  MOUSEY?800



SEE ALSO:           MOUSE



                                                            565




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SGET



Syntax:                SGET  screen$



DESCRIPTION:



     SGET stores the content of the graphics window or screen in screen$. The data

format is BMP (in case you want to write this into a ole).



EXAMPLE:



   CLEARW                !  clear  the  screen,  otherwise  sometimes  there  is  garbage  left
   FOR  i=1  TO  64
      FOR  j=1  TO  40
         COLOR  COLOR.RGB(i/64,j/40,SQRT(1-(i/64)^2-(j/40)^2))
         CIRCLE  i*10,j*10,3      !  draw  something
      NEXT  j
   NEXT  i
   CIRCLE  100,100,30
   SHOWPAGE

   SGET  screen$
   BSAVE  "screen.bmp",VARPTR(screen$),LEN(screen$)



SEE ALSO:           SPUT, SAVEWINDOW, GET, PUT



                                                            566




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Function:           SGN()



Syntax:                a=SGN(b)



DESCRIPTION:



     SGN returns the sign of a number b. It may be -1 if b is negative 0 if b equals 0

1 if b is positive.



SEE ALSO:           ABS()



                                                            567




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SHELL



Syntax:                SHELL  file$[,argument$,...]



DESCRIPTION:



     This command executes an executable program which name and path is given

in ole$.  The text console/terminal will be connected to the running program.  Op-

tional string arguments can be specioed.  The dioeerence to SYSTEM (which exe-

cutes a shell command) is,  that with SHELL you execute the ole and not a com-

mand.



EXAMPLE:


SHELL  "/usr/bin/sh"   !  starts  the  sh  shell  interactively



SEE ALSO:           SYSTEM



                                                            568




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Function:           SHL()



Syntax:                i%=SHL(j%,n%)



DESCRIPTION:



     Returns the bit pattern in j% shifted left by n% bits.



EXAMPLE:


PRINT  SHL(8,2)       Result:  32



SEE ALSO:           SHR()



                                                            569




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           SHM.ATTACH()



Syntax:                adr=SHM.ATTACH(id)



DESCRIPTION:



     SHM.ATTACH()  attaches  the  shared  memory  segment  identioed  by  id  (see

SHM.MALLOC()) to the programs address space. The address is returned.

     You can also attach shared memory segments, which are originally created by

another process, but you must know the id, and the process must have read and

write permission for the segment.



SEE ALSO:           SHM.MALLOC(), SHM.DETACH, SHM.FREE



                                                            570




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SHM.DETACH



Syntax:                SHM.DETACH  adr



DESCRIPTION:



     SHM.DETACH detaches the shared memory segment located at the address

specioed by adr from the address space of the program. The to-be-detached seg-

ment must be currently attached with adr equal to the value returned by the attach-

ing SHM.ATTACH() call.



SEE ALSO:           SHM.MALLOC(), SHM.ATTACH()



                                                            571




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SHM.FREE



Syntax:                SHM.FREE  id



DESCRIPTION:



     Mark the shared memory segment identioed by id to be destroyed.  The seg-

ment  will  only  actually  be  destroyed  after  the  last  process  detaches  it.   You  can

only free a shared memory segment, if you are the owner, means, you must have

created it with SHM.MALLOC().



SEE ALSO:           SHM.MALLOC()



                                                            572




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Function:           SHM.MALLOC()



Syntax:                id=SHM.MALLOC(size,key)



DESCRIPTION:



     SHM.MALLOC() returns the identioer of the shared memory segment associ-

ated with key. A new shared memory segment, with size equal to the value of size

rounded up to a multiple of the operating system internal page size, is created if

no shared memory segment corresponding to key exists.

     Open the shared memory segment - create if necessary.

     Return value is the id of the shared memory segment.  The id can be used by

dioeerent processes to attach and access the segment (read and write).  In case of

an error, -1 is returned.



SEE ALSO:           SHM.FREE, SHM.ATTACH()



                                                            573




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SHOWK



Syntax:                SHOWK



DESCRIPTION:



     Show the vitual keyboard (make it visible) and activate it for input.



     Comment:



     This command works currently only on Android.  An other platforms it has no

eoeect.



SEE ALSO:           HIDEK



                                                            574




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SHOWM



Syntax:                SHOWM



DESCRIPTION:



     Show the mouse cursor (make it visible).



SEE ALSO:           HIDEM



                                                            575




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SHOWPAGE



Syntax:                SHOWPAGE



DESCRIPTION:



     SHOWPAGE refreshes the graphic output.  Usually the drawing to the graphic

output  window  or  screen  is  not  visible  until  SHOWPAGE  is  performed.  (Only  on

TomTom devices this command has no eoeect,  because all graphics drawn is im-

mediately visible).



SEE ALSO:           VSYNC



                                                            576




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Function:           SHR()



Syntax:                i%=SHR(j%,n%)



DESCRIPTION:



     Returns the bit pattern in j% shifted right by n% bits.



EXAMPLE:


PRINT  SHR(8,2)       Result:  2



SEE ALSO:           SHL(), ROR(), ROL()



                                                            577




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           SIGN$()



Syntax:                s$=SIGN$(message$,key$[,type])



DESCRIPTION:



     SIGN$()  returns  a  digital  signature  based  on  message$  and  a  (private)  key

key$.   The  type  parameter  determines,  which  algorithm  is  to  be  used.   Default:

type=0.  The returned signature can be used to verify (the same) message and its

authenticity with VRFY() and the corresponding (public) key.



     Comment:



     This function is only available if libgcrypt was compiled in.



SEE ALSO:           ENCRYPT$(), HASH$(), VRFY()



                                                            578




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Function:           SIN()



Syntax:                !num-result?=SIN(!num-expression?)



DESCRIPTION:



     Returns the sinus of the expression in radians.



EXAMPLE:


PRINT  SIN(PI/2)       Result:  1



SEE ALSO:           COS(), TAN(), ACOS()



                                                            579




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           SINH()



Syntax:                !num-result?=SINH(!num-expression?)



DESCRIPTION:



     Returns the sinus hyperbolicus of the expression in radians.



SEE ALSO:           SIN(), ASINH()



                                                            580




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Function:           SIZE()



Syntax:                l%=SIZE(file$)



DESCRIPTION:



     Returns the size of a ole given by its olename (including path).



SEE ALSO:           LOF()



                                                            581




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SIZEW



Syntax:                SIZEW  nr,w,h



DESCRIPTION:



     Resizes the graphic window #nr with width w and height h.



SEE ALSO:           OPENW, MOVEW



                                                            582




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Function:           SOLVE()



Syntax:                x()=SOLVE(m(),d())



DESCRIPTION:



     Solves  a  set  of  linear  equations  of  the  form  M()*x()=d().   M()  has  to  be  a  2

dimensional  array  (a  matrix)  not  necessarily  a  square  matrix.   d()  must  be  a  1

dimensional array (a vector) with exactly as many elements as lines of M(). x() will

be a 1 dimensional array (a vector) with exactly as many elements as rows of M().

Internally a singular value decomposition is used to solve the equation. If the linear

equation system does not have an exact solution,  the returned vector is the one

which minimizes (least square) ---M*x-d---.



EXAMPLE:


r=3
c=5
DIM  a(r,c),b(r)
ARRAYFILL  a(),0
a(0,0)=1
a(0,2)=1
a(1,1)=10
a(2,2)=100
b(0)=4
b(1)=2
b(2)=300
PRINT  "solve:"
FOR  i=0  TO  r-1
      PRINT  i;":  (";
      FOR  j=0  TO  c-1
         PRINT  a(i,j);
         IF  j!c-1
           PRINT  ",  ";
         ENDIF
      NEXT  j
      PRINT  ")(x)=(";b(i);")"



                                                            583




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



NEXT  i
PRINT
er()=SOLVE(a(),b())
PRINT  "solution:"
FOR  i=0  TO  c-1
   PRINT  "(x";i;")=(";er(i);")"
NEXT  i



Comment:



     This function is only available,  if X11-Basic was compiled and linked together

with the LAPACK library. (currently only on linux).



SEE ALSO:           INV(), DET()



                                                            584




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SORT



Syntax:                SORT  array()[,n%[,idx%()]]

                              SORT  array%()[,n%[,idx%()]]

                              SORT  array$()[,n%[,idx%()]]



DESCRIPTION:



     SORT sorts the one-dimensional array array(),  array%() or array$().  Numeric

arrays and string arrays can be sorted.  If n% is given, only the orst n% values are

sorted.  If idx%() is given, this (numerical) array will also be sorted corresponding

to the orst one. This is useful for creating an index table. SORT uses the canonical

ASCII coding for sorting strings.  If you want a string array sorted by a dioeerent al-

phabet or being sorted case insensitive, you can implement such sorting functions

with the index tables.



EXAMPLE:



   DIM  test$(100)
   CLR  anzdata
   DO
      READ  a$
      EXIT  IF  a$="*"
      test$(anzdata)=a$
      INC  anzdata
   LOOP
   SORT  test$(),anzdata      !  normal  sort  according  to  ASCII
   @asort(test$(),anzdata)  !  special  alphabet  sort
   @usort(test$(),anzdata)  !  sort  ignoring  the  case  of  characters
   PRINT  "Result  of  SORT:"
   FOR  x=0  TO  anzdata-1
      PRINT  test$(x)
   NEXT  x
   END

'



                                                            585




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



'  Sort  case  insensitive
'
PROCEDURE  usort(VAR  s$(),anz%)
   LOCAL  k%,t$(),i%(),t2$()
   t$()=s$()
   DIM  i%(anz%)                 !  create  index  table
   FOR  k%=0  TO  anz%-1
      i%(k%)=k%
      t$(k%)=UPPER$(t$(k%))
   NEXT  k%
   SORT  t$(),anz%,i%()       !  Sort  with  index  table
   DIM  t2$(DIM?(s$()))
   FOR  k%=0   TO  anz%-1
      t2$(k%)=s$(i%(k%))
   NEXT  k%
   s$()=t2$()
RETURN
'
'  Sort  with  a  custom  alphabet
'
PROCEDURE  asort(VAR  s$(),anz%)
   LOCAL  k%,alphabet$,j%,t$(),i%(),t2$()
   t$()=s$()
   alphabet$="0123456789AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz"
   DIM  i%(anz%)                !  create  index  table
   FOR  k%=0  TO  anz%-1
      i%(k%)=k%
      FOR  j%=0  TO  LEN(t$(k%))-1
         POKE  VARPTR(t$(k%))+j%,INSTR(alphabet$,MID$(t$(k%),j%+1))
      NEXT  j%
   NEXT  k%
   SORT  t$(),anz%,i%()       !  Sort  with  index  table
   DIM  t2$(DIM?(s$()))
   FOR  k%=0   TO  anz%-1
      t2$(k%)=s$(i%(k%))
   NEXT  k%
   s$()=t2$()
RETURN



SEE ALSO:           DIM



                                                            586




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SOUND



Syntax:                SOUND  !channel?,!frequency?[,volume[,duration]]



DESCRIPTION:



     SOUND  sets  a  tone  for  the  sound  generator  for  channel  c%.   There  are  16

sound channels which are mixed together, so c may be between 0 and 15.  If c is

omitted or -1, a free channel (which is quiet at that time) will be used.

     The tone has frequency [Hz], volume [0-1] and a duration [s].  If frequency=0

(or volume=0) the channel will be switched ooe. If duration is omitted or -1 a perma-

nent sound will be played (inonite duration, until it is cleared by the next SOUND

command to that channel).

     Each  of  the  16  channels  also  support  sound  samples,  which  can  be  set  via

PLAYSOUND. Volume can be 0 (ooe) to 1 (maximum).  The duration is counted in

seconds. The parameters of the sound synthesizer of this channel can be set with

WAVE (envelope and wave form). Also noise can be set for a channel.



     Comment:



     On  systems  without  ALSA/PCM  sound  the  internal  speaker  is  used.   The  in-

ternal speaker has only one channel (and produces sort of a square wave).  The

internal speaker is accessed via a console device and needs privileges. Except for

on ANDROID devices, the sound currently does not work under UNIX/LINUX.



EXAMPLE:


           WAVE  1,1,0.05,0.1,0.5,0.1      !  set  the  instrument  parameters
           DO
              MOUSEEVENT                        !  wait  for  mouseclick



                                                            587




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



              SOUND  1,2*MOUSEX+50,1,0.3   !  play  a  nice  sound
           LOOP
'  Also  this  is  possible:
SOUND  1,500      !  SOUND  ON
PAUSE  0.1
SOUND  1,0         !  SOUND  OFF



SEE ALSO:           WAVE, PAUSE, PLAYSOUND



                                                            588




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Variable:            SP



Syntax:                i%=SP



DESCRIPTION:



     The variable SP represents the internal X11-Basic stack pointer.  Do not name

any other variable SP (or PC) since no value can be assigned to it.



SEE ALSO:           PC



                                                            589




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           SPACE$()



Syntax:                t$=SPACE$(n)



DESCRIPTION:



     Returns a string containing n spaces.



SEE ALSO:           STRING$()



                                                            590




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SPAWN



Syntax:                SPAWN  procedure



DESCRIPTION:



     Spawns a new thread using the given procedure as an entry point.  This entry

point can be considered the "main" function of that thread of execution.  The new

thread  will  run  in  parallel  to  the  main  thread  and  can  access  the  same  memory

(unlike a process which was forked with fork()).

     This command is not fully implemented and at the moment messes up the pro-

gram execution stack of the interpreter since all internal control structures are ac-

cessed by two threads.  Anyway, in a natively compiled program this can work as

expected.



SEE ALSO:           FORK()



                                                            591




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SPEAK



Syntax:                SPEAK  t$[,pitch,rate,locale$]



DESCRIPTION:



     Reads text t$ loud.  (It uses Text-to-speech synthesis if it is available).  You can

adjust a factor for pitch (!1 male, ?1 female) and rate (!1 slow, ?1 fast).

     The locale can be:



"de"  for  German    pronunciation,

"en"  for  English  pronunciation,

"us"  for  English  pronunciation,

"fr"  for  French    pronunciation,

"es"  for  Spanish  pronunciation,

"it"  for  Italian  pronunciation.



Comment:



     This command is implemented in the Android version of X11-Basic only. Not all

locales might be installed. If a locale is missing, you will be asked to install it.



EXAMPLE:


SPEAK  ""  !  The  first  SPEAK  command  initializes  the  text-to-speech  engine
SPEAK  "Are  you  hungry?"
SPEAK  "Ich  glaube  nicht.",1,1,"de"



                                                            592




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



SEE ALSO:           PLAYSOUND, WAVE



                                                            593




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SPLIT



Syntax:                SPLIT  t$,d$,mode%,a$[,b$]



DESCRIPTION:



     Splits up string t$ into two parts a$ and b$ concerning a delimiter string d$. So

that t$=a$+d$+b$.

     mode can be: 0 ~ default 1 ~ do not search in parts of t$ which are in brackets.

     Quoted parts of the string are not split up.



EXAMPLE:


SPLIT  "Hello,  this  is  a  string.","  ",0,a$,b$



SEE ALSO:           WORT.SEP, WORD$()



                                                            594




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SPUT



Syntax:                SPUT  screen$



DESCRIPTION:



     Map a screen bitmap, which was stored in screen$ (and saved with SGET) back

to the screen.



EXAMPLE:



   CLEARW                !  clear  the  screen,  otherwise  sometimes  there  is  garbage  left
   FOR  i=1  TO  64
      FOR  j=1  TO  40
         COLOR  COLOR.RGB(i/64,j/40,SQRT(1-(i/64)^2-(j/40)^2))
         CIRCLE  i*10,j*10,3      !  draw  something
      NEXT  j
   NEXT  i
   CIRCLE  100,100,30
   SHOWPAGE

   SGET  b$       !  get  the  whole  screen  bitmap  and  save  it  in  b$
   CLEARW
   SHOWPAGE      !  screen  is  now  blank
   PRINT  "now  reput  the  screen"
   PAUSE  1
   SPUT  b$       !  put  back  the  saved  screen  content
   SHOWPAGE



SEE ALSO:           SGET, PUT.BITMAP



                                                            595




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           SQR(),    SQRT()



Syntax:                !num-result?  =  SQR(!num-expression?)

                              !num-result?  =  SQRT(!num-expression?)



DESCRIPTION:



     SQR() and SQRT() return the square root of its argument. The function can also

be  used  on  complex  numbers,  then  returning  a  complex  result.  You  can  always

force the function return the complex sqare root (given a real argument) by using:

SQRT(a+0i).



EXAMPLES:



PRINT  SQR(25)         !  Result:  5
PRINT  SQRT(-1+0i)   !  Result:  (0+1i)

PRINT  "Calculate  square  root  of  a  number."
INPUT  "Number=",z
r124=1
105:
r123=r124
r124=(r123^2+z)/(2*r123)
IF  ABS(r124-r123)-0.00001?0
   PRINT  r124
   GOTO  105
ENDIF
PRINT  "Result  of  this  algorithm:"'r124
PRINT  "Compare  with:  sqrt(";z;")=";SQRT(z)
PRINT  "Deviation:"'ABS(SQRT(z)-r124)



                                                            596




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Function:           SRAND()



Syntax:                VOID  SRAND(b)



DESCRIPTION:



     The  SRAND()  function  sets  its  argument  as  the  seed  for  a  new  sequence  of

pseudo-random integers to be returned by RAND(), RANDOM() or RND().  These

sequences are repeatable by calling SRAND() with the same seed value.



SEE ALSO:           RANDOMIZE, RANDOM(), RND(), RAND()



                                                            597




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            STIMER



Syntax:                !int-result?=STIMER



DESCRIPTION:



     STIMER returns the integer part of TIMER. So the resolution is 1 second and

the value ots in 32 bit integers. (And it is a bit faster than TIMER).



SEE ALSO:           TIMER, CTIMER



                                                            598




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        STOP



Syntax:                STOP



DESCRIPTION:



     STOP halts program execution and sets the interpreter to interactive mode. The

execution can be continued with the CONT command.



SEE ALSO:           CONT, END, QUIT



                                                            599




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           STR$()



Syntax:                t$=STR$(a[,b,c[,d]])



DESCRIPTION:



     STR$() converts a number into a string of length b with c signiocant digits.  If b

or c are omitted, the string will contain as much digits as the number requires.  if

d=1, leading zeros are printed.



EXAMPLES:


PRINT  STR$(PI)           !  Result:  3.14159265359
PRINT  STR$(PI,2,2)      !  Result:  3.1
PRINT  STR$(PI,5,2,1)   !  Result:  003.1
PRINT  STR$(PI+3i,5,2,1)  !  Result:  (003.1+00003i)



SEE ALSO:           VAL(), PRINT  USING, USING$()



                                                            600




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Function:           STRING$()



Syntax:                a$=STRING$(i%,b$)



DESCRIPTION:



     The STRING$() function returns a string consisting of i% copies of b$.



SEE ALSO:           SPACE$()



                                                            601




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SUB



Syntax:                SUB  a,b

                              SUB  a%,b%

                              SUB  a#,b#

                              SUB  a&,b&



DESCRIPTION:



     Decrease the value of the variable a by the result of b.



EXAMPLE:


a=0.5
SUB  a,5
Result:  -4.5



SEE ALSO:           ADD, MUL, DIV



                             _________________________________*________________________________



Function:           SUB()



                                                            602




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Syntax:                c=SUB(a,b)

                              c%=SUB(a%,b%)

                              c#=SUB(a#,b#)

                              c&=SUB(a&,b&)



DESCRIPTION:



     Returns the result of a minus b.



SEE ALSO:           SUB, ADD()



                                                            603




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SUBSCRIBE



Syntax:                SUBSCRIBE  topic$,value$[,callback[,qos]]



DESCRIPTION:



     Subscribes  to  (or  unsubscribes  from)  a  topic  on  the  (mqtt)  broker.   You  can

optionally  specify  a  quality  of  service  value.   When  a  message  is  received,  its

content  will  be  stored  in  the  global  variable  value$  and  the  procedure  callback

is  excecuted.  If  qos=-1,  the  topic  will  be  unsubscribed.  The  callback  function  is

optional.

     The Quality of service can be:


-1    --  unsubscribe

0      --  receive  at  most  once

1      --  receive  ar  least  once

2      --  receive  exactly  once


     The  callback  procedure  takes  exactly  two  arguments.   A  string  with  the  topic

name and another string with the message content.  You can use mqtt-wildcards

in the topic name on subscriptions, so the callback procedure gets called on mes-

sages from any of these topics.



EXAMPLE:



BROKER  "tcp://localhost:1883"
SUBSCRIBE  "CMD",cmd.var$,cmd.callback,2
SUBSCRIBE  "TEMPERATURE",temp.var$,engine
SUBSCRIBE  "HUMIDITY",hum.var$,engine
SUBSCRIBE  "SOMETHING",something.var$
DO
   PUBLISH  "ACTIVITY",STR$(i  MOD  4)
   INC  i



                                                            604




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



   PAUSE  1
   EXIT  IF  cmd.var$="exit"
LOOP
SUBSCRIBE  "CMD",,,-1      !  Unsubscribe  from  CMD
QUIT

'  This  realizes  a  "rule".  The  input  topics  will  trigger  this.
PROCEDURE  engine(topic$,message$)
   LOCAL  temp,hum,dev
   PRINT  "engine  triggered  on  ";topic$
   temp=VAL(temp.var$)
   hum=VAL(hum.var$)
   dev=temp*hum   !  please  implement  the  correct  formula
   PUBLISH  "DEWPOINT",STR$(dev)
RETURN
PROCEDURE  cmd.callback(topic$,message$)
   PRINT  "cmd.callback  trigered:  cmd.var=";cmd.var$
RETURN



SEE ALSO:           BROKER, PUBLISH



                                                            605




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           SUCC()



Syntax:                a=SUCC(b)



DESCRIPTION:



     Determines the next higher integer number.



SEE ALSO:           PRED()



                                                            606




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Command:        SWAP



Syntax:                SWAP  a,b

                              SWAP  a%,b%

                              SWAP  a$,b$

                              SWAP  a(),b()



DESCRIPTION:



     Exchanges the values of the variables a and b. A and b can be of any type, but

the types of a and b must be equal. SWAP a(0),b would also be possible.



EXAMPLE:



a=4
b=5
SWAP  a,b
print  a         !  Result:  5



SEE ALSO:           LET, Operator:  =



                             _________________________________*________________________________



Function:           SWAP()



                                                            607




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Syntax:                a%=SWAP(b%)



DESCRIPTION:



     Swaps High and Low words of b and returns the result.  b is always treated as

a 32 bit unsigned integer.



EXAMPLE:



    PRINT  HEX$(SWAP(5))      !  Result:  0000000050000



SEE ALSO:           BYTE(), CARD(), WORD()



                                                            608




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Function:           SYM.ADR()



Syntax:                adr=SYM.ADR(#n,sym.name$)



DESCRIPTION:



     SYM.ADR() resolves the address of a symbol name of a given shared object

library which has been linked before.



EXAMPLE:



t$="/usr/lib/libreadline.so"      !   If  the  readline  shared  object  file
IF  EXIST(t$)                            !   exist,
   LINK  #1,t$                            !   link  it,  resolve  the  symbol  "readline"
   DUMP  "#"                               !   and  execute  that  subroutine  with
   promt$="???"                         !   one  string  parameter.
   adr=EXEC(SYM.ADR(#1,"readline"),L:VARPTR(promt$))
   r=adr
   WHILE  PEEK(r)?0                     !  Print  the  result
      PRINT  CHR$(PEEK(r));
      INC  r
   wend
   PRINT
   UNLINK  #1  !  Unlink  the  dynamic  lib
   FREE  adr
ENDIF



SEE ALSO:           LINK, UNLINK



                                                            609




6.20.__S_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        SYSTEM



Syntax:                SYSTEM  !string-expression?



DESCRIPTION:



     Passes a command to the shell.  Executes the shell command.  SYSTEM pro-

vides  a  way  to  use  alle  commands  like  rm,  rmdir,  mkdir  etc.   which  are  not  im-

plemented in X11-Basic, but which are available from a command shell.  (This is

usually sh or busybox on UNIX/LINUX/ANDROID and TomTom systems and DOS

on MS WINDOWS).



EXAMPLE:


SYSTEM  "mkdir  folder"



SEE ALSO:           SYSTEM$()



                             _________________________________*________________________________



Function:           SYSTEM$()



                                                            610




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.20.__S__



Syntax:                ret$=SYSTEM$(command$)



DESCRIPTION:



     Passes a command to the shell. Executes shell command. The function returns

a string containing the stdout of the command executed.



EXAMPLE:



d$=SYSTEM$("ls")
PRINT  d$



SEE ALSO:           SYSTEM



                                                            611




6.21.__T_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



6.21         T



                                                            612




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.21.__T__



Function:           TALLY()



Syntax:                a%=TALLY(t$,s$[,start%])



DESCRIPTION:



     TALLY()  returns  the  number  of  occurrences  of  s$  in  t$,  starting  at  the  given

position start% in t$. If s$ is not present in t$, zero is returned.



EXAMPLE:


PRINT  TALLY("Hello","l")      !  Result:  2



SEE ALSO:           INSTR()



                                                            613




6.21.__T_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           TAN()



Syntax:                b=TAN(a)



DESCRIPTION:



     Returns the tangens of the expression in radians.



SEE ALSO:           SIN(), ATAN(), TANH()



                                                            614




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.21.__T__



Function:           TANH()



Syntax:                b=TANH(a)



DESCRIPTION:



     Returns the tangens hyperbolicus of the expression in radians.



SEE ALSO:           SIN(), ATANH(), TAN()



                                                            615




6.21.__T_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            TERMINALNAME$



Syntax:                a$=TERMINALNAME$



DESCRIPTION:



     Returns the device name of the terminal connected to the stdout standard out-

put (if a terminal device is connected).



EXAMPLE:



PRINT  TERMINALNAME$
Result:  /dev/pts/0



                             _________________________________*________________________________



Function:           TERMINALNAME$()



Syntax:                t$=TERMINALNAME$(#n)



DESCRIPTION:



     Returns the device name of the terminal connected to ole #n if it is a terminal

device.



                                                            616




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.21.__T__



Command:        TEXT



Syntax:                TEXT  x,y,t$



DESCRIPTION:



     Draws text t$ in graphics window at position x,y.



EXAMPLE:



'  Show  the  complete  ASCII  Font
SETFONT  "*writer*18*"
COLOR  GET.COLOR(65535,10000,10000)
FOR  x=0  to  15
   FOR  y=0  to  15
      TEXT  320+16*y,20+24*x,CHR$(y+16*x)
   NEXT  y
NEXT  x
SHOWPAGE



SEE ALSO:           SETFONT, DEFTEXT



                                                            617




6.21.__T_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            TIME$



Syntax:                a$=TIME$



DESCRIPTION:



     Returns the system time as a string.  Format:  hh:mm:ss and is updated every

second.



EXAMPLE:



PRINT  TIME$,DATE$    !  14:49:44           11.03.2014



SEE ALSO:           DATE$, TIMER, UNIXTIME$()



                                                            618




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.21.__T__



Variable:            TIMER



Syntax:                TIMER



DESCRIPTION:



     Returns actual time in number of seconds since 01.01.1970 00:00 GMT. The

value has milliseconds resolution. TIMER is often used to measure times.



EXAMPLE:


n%=1000000
DIM  t$(n%),u%(n%)
t=TIMER
PRINT  "filling  the  string  array  with  ";n%;"  strings  ..."
FOR  i%=0  TO  n%-1
   t$(i%)=STR$(RANDOM(n%))
   u%(i%)=i%
NEXT  i%
PRINT  "this  took  ";TIMER-t;"  seconds."
END



SEE ALSO:           STIMER, CTIMER, TIME$, DATE$, UNIXTIME$(), UNIXDATE$()



                                                            619




6.21.__T_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        TITLEW



Syntax:                TITLEW  n,title$



DESCRIPTION:



     Gives the window #n the new title title$.



SEE ALSO:           OPENW, INFOW



                                                            620




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.21.__T__



Command:        TOPW



Syntax:                TOPW  [n]



DESCRIPTION:



     Activates the windows number n and moves it to the front of the screen.



SEE ALSO:           BOTTOMW, MOVEW



                                                            621




6.21.__T_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        TOUCH



Syntax:                TOUCH  #n



DESCRIPTION:



     Updates the date and time stamps of a ole, giving it the current system time and

date.



EXAMPLE:


       OPEN  "U",#1,"test.txt"
           TOUCH  #1
           CLOSE  #1



SEE ALSO:           OPEN, CLOSE



                                                            622




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.21.__T__



Variable:            TRACE$



Syntax:                a$=TRACE$



DESCRIPTION:



     The variable TRACE$ contains the command which is next to be processed.



EXAMPLE:


PRINT  TRACE$         !  Result:  END
END



SEE ALSO:           TRON, TROFF, PC



                                                            623




6.21.__T_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           TRIM$()



Syntax:                b$=TRIM$(a$)



DESCRIPTION:



     TRIM$(a$) returns a modioed string taken a$

     1. replace Tabs by space,

     2. replace double spaces by single ones ,

     3. remove leading and trailing spaces.

     4. Parts of the string which are in quotes ("") will not be changed.



SEE ALSO:           XTRIM$(), REPLACE$()



                                                            624




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.21.__T__



Command:        TROFF



Syntax:                TROFF



DESCRIPTION:



     TROFF  disables  tracing  output.   This  command  is  meant  to  be  used  during

program development.



SEE ALSO:           TRON, ECHO



                                                            625




6.21.__T_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        TRON



Syntax:                TRON



DESCRIPTION:



     TRON enables tracing output:  each program line is displayed on the console

before it is executed. This command is meant to be used during program develop-

ment.



SEE ALSO:           TROFF, ECHO



                                                            626




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.21.__T__



Variable:            TRUE



Syntax:                TRUE



DESCRIPTION:



     Constant -1.  This is simply another way of expressing the value of a condition

when it is true and is equal to -1 (all bits not zero).



SEE ALSO:           FALSE



                                                            627




6.21.__T_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           TRUNC()



Syntax:                a=TRUNC(x)



DESCRIPTION:



     TRUNC() rounds x to the nearest integer not larger in absolute value.  TRUNC

complements FRAC:


                        TRUNC(x)=x-FRAC(x)



SEE ALSO:           FRAC(), FLOOR(), FIX()



                                                            628




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.21.__T__



Function:           TYP?()



Syntax:                a%=TYP?(!var?)



DESCRIPTION:



     Returns the type of a variable.


          0  --  invalid

          1  --  32  bit  integer

          2  --  64  bit  floating  point

          3  --  big  integer

          4  --  ARBFLOATTYP

          5  --  complex

          6  --  ARBCOMPLEXTYP

          7  --  String

        +8  --  Array  of  typ  0-7

      +32  --  it  is  a  constant  of  typ  0-7



     Comment:



     This function is nearly useless. It only shows internals of X11-Basic.



EXAMPLES:



  PRINT  typ?(a)   -?  2
  PRINT  typ?(a$)  -?  7
  PRINT  typ?(a())-?  10



                                                            629




6.22.__U_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



6.22         U



                                                            630




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.22.__U__



Function:           UBOUND()



Syntax:                n%=UBOUND(array()[,i%])



DESCRIPTION:



     The UBOUND function returns the largest subscript for the indicated dimension

of  an  array  plus  one.   This  is  the  size  of  the  i'th  dimension.   i%  specioes  which

dimension's upper bound to return. 0 = orst dimension, 1 = second dimension, and

so on. Default is 0.



SEE ALSO:           DIM, DIM?(), ARRPTR()



                                                            631




6.22.__U_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           UCASE$()



Syntax:                a$=UCASE$(!string-expression?)



DESCRIPTION:



     Transforms all lower case letters of a string to upper case.  Any non letter char-

acters are left unchanged.



SEE ALSO:           UPPER$(), LOWER$()



                                                            632




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.22.__U__



Variable:            UNCOMPRESS$()



Syntax:                t$=UNCOMPRESS$(c$)



DESCRIPTION:



     Un-compresses  the  content  of  a  string  which  has  been  compressed  with  the

COMPRESS$() function before.



SEE ALSO:           COMPRESS$()



                                                            633




6.22.__U_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            UNIX?



Syntax:                a%=UNIX?



DESCRIPTION:



     Returns TRUE (-1) If the program is running under a UNIX environment.



SEE ALSO:           WIN32?, ANDROID?



                                                            634




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.22.__U__



Function:           UNIXTIME$(),    UNIXDATE$()



Syntax:                t$=UNIXTIME$(i)

                              d$=UNIXDATE$(i)



DESCRIPTION:



     These functions return the date and time as a string which has the same format

as DATE$ and TIME$ given by a TIMER value.  Time and Date returned are local

times adjusted to summer and winter time and based on CET.



EXAMPLE:


PRINT  UNIXDATE$(1045390004.431),  UNIXTIME$(1045390004.431)
Result:    16.02.2003    11:06:44



SEE ALSO:           DATE$, TIME$, TIMER



                                                            635




6.22.__U_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        UNLINK



Syntax:                UNLINK  #n



DESCRIPTION:



     Un-links a shared object which has been linked before and occupies ole channel

#n.



SEE ALSO:           LINK, CLOSE



                                                            636




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.22.__U__



Command:        UNMAP



Syntax:                UNMAP  adr%,len%



DESCRIPTION:



     Un-map oles or devices out of memory.

     The UNMAP command deletes the mappings for the specioed address range.

Further PEEK() and POKEs to addresses within the old range will produce an error

(crash). The region is also automatically unmapped when X11-Basic is terminated.

On the other hand, closing the ole does not un-map the region.



SEE ALSO:           MAP



                                                            637




6.22.__U_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        UNTIL



Syntax:                UNTIL  !expression?



DESCRIPTION:



     UNTIL terminates a REPEAT...UNTIL loop.



SEE ALSO:           REPEAT, DO



EXAMPLE:


          REPEAT
                N=N+1
          UNTIL  (N=10)



                                                            638




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.22.__U__



Function:           UPPER$()



Syntax:                u$=UPPER$(t$)



DESCRIPTION:



     Transforms all lower case letters of a string to upper case.  Any non letter char-

acters are left unchanged.



SEE ALSO:           UCASE$(), LOWER$()



                                                            639




6.22.__U_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        USEWINDOW



Syntax:                USEWINDOW  #n



DESCRIPTION:



     Use the window n for all following graphic commands.



SEE ALSO:           OPENW, ROOTWINDOW



                                                            640




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.22.__U__



Function:           USING$()



Syntax:                t$=USING$(a,format$)



DESCRIPTION:



     The function USING$() returns a formatted string made out of a numeric value

a. How the number is formatted can be set by a format$ consisting of one or more

of the following characters.

    #      Denotes  a  numerical  digit  (leading  spaces),

    0      Denotes  a  numerical  digit  (leading  zeros),

    *      Denotes  a  numerical  digit  (leading  asterisks),

    $      Denotes  a  numerical  digit  (single  leading  Dollar),

    ?      Denotes  a  numerical  digit  (single  leading  EURO).

^^^^    After  #  digits  prints  numerical  value  in  exponential

            e+xx  format.

            Use  ^^^^^  for  E+xxx  values.  The  exponent  is  adjusted

            with  significant  digits  left-justified.

    .      Period  sets  a  number's  decimal  point  position.  Digits

            following  determine  rounded  value  accuracy.

    +      Plus  sign  denotes  the  position  of  the  number's  sign.  +

            or  -  will  be  displayed.

    -      Minus  sign  (dash)  placed  before  or  after  the  number,

            displays  only  a  negative  value's  sign.

    .      Underscore  preceding  a  format  symbol  prints  those  symbols

            as  literal  string  characters.

Note: Any string character not listed above will be printed as a literal text character

(useful to add commas or units). If the number cannot be expressed with the given

format, a series of "*" will be displayed. The returned string will always have exactly

the same length than format$. USING$() rounds to the nearest printed digit.



                                                            641




6.22.__U_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



EXAMPLE:


PRINT  USING$(1.23456,"+##.###^^^^")    !  Result:  +  1.235e+00



SEE ALSO:           PRINT  USING, STR$()



                                                            642




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.23.__V__



6.23         V



                                                            643




6.23.__V_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           VAL()



Syntax:                a=VAL(t$)



DESCRIPTION:



     VAL()  converts  a  string  representing  a  AEoating  point  number  into  a  numeric

value. If the string does not represent a valid number 0 is returned.



EXAMPLE:


           a=VAL("3.1415926")



SEE ALSO:           VAL?(), STR$()



                             _________________________________*________________________________



Function:           VAL?()



                                                            644




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.23.__V__



Syntax:                a=VAL?(t$)



DESCRIPTION:



     Returns the number of characters from a string which can be converted into a

number.



EXAMPLE:


PRINT  VAL?("12345.67e12Hallo")       !  Result:  11



SEE ALSO:           VAL()



                                                            645




6.23.__V_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Operator:           VAR



Syntax:                PROCEDURE  name(...,VAR  a,...)

                              FUNCTION  name(...,VAR  z,...)



DESCRIPTION:



     This  operator  can  declare  a  variable  in  a  parameter  list  of  a  procedure  or  a

function  to  be  passed  by  reference  instead  of  by  value.   This  is  useful  to  pass

(more than one) return values.



EXAMPLE:


          @sum(13,12,a)
          @sum(7,9,b)
          PRINT  a,b
          '
          PROCEDURE  sum(x,y,VAR  z)
             z=x+y
          RETURN



SEE ALSO:           PROCEDURE, FUNCTION



                                                            646




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.23.__V__



Function:           VARIAT()



Syntax:                a%=VARIAT(n%,k%)



DESCRIPTION:



     Returns  the  number  of  permutations  of  n  elements  to  the  k-th  order  without

repetition.



EXAMPLE:


PRINT  VARIAT(6,2)         !  Result:  30



SEE ALSO:           COMBIN(), FACT()



                                                            647




6.23.__V_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           VARLEN()



Syntax:                a=VARLEN(!variable?)



DESCRIPTION:



     Determines the length of the content of a variable in memory. For AEoat variables

usually 8 is returned, meaning, 8 bytes following the adress returned by VARPTR()

belong to the variable.  For string variables the length of the string content is re-

turned.  This is the same result as of LEN(var$) but the calculation is much faster

for very long strings.



SEE ALSO:           VARPTR(), PEEK(), POKE, ABSOLUTE



                                                            648




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.23.__V__



Function:           VARPTR()



Syntax:                adr%=VARPTR(!variable?)



DESCRIPTION:



     Determines the address of the content of a variable in memory and returns a

pointer. Usually this is used together with PEEK() and POKE to modify the content

of the variable.  VARPTR() can also be used to determine the address of an array

index.



EXAMPLE:


PRINT  VARPTR(t$),VARPTR(a(2,4))
POKE  VARPTR(t$),ASC("A")



SEE ALSO:           VARLEN(), ARRPTR(), PEEK(), POKE, ABSOLUTE



                                                            649




6.23.__V_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        VERSION



Syntax:                VERSION



DESCRIPTION:



     Shows X11-Basic version number and date.



EXAMPLE:


VERSION
Result:  X11-BASIC  Version:  1.27  Mon  Jun  04  12:00:38  CET  2019



                                                            650




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.23.__V__



Command:        VOID    ABBREV.    ~



Syntax:                VOID  !expression?



DESCRIPTION:



     This command performs a calculation and forgets the result.  Sounds silly but

there are occasions when this command is required, e.g. when you want to execute

a function but you are not really interested in the return value;  e.g.  waiting for a

keystroke (INP(-2)).



EXAMPLE:


~INP(-2)
VOID  FORM.ALERT(1,"[1][Hello][OK]")



SEE ALSO:           GOSUB



                                                            651




6.23.__V_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           VRFY()



Syntax:                flag%=VRFY(message$,signature$,key$[,type])



DESCRIPTION:



     Returns TRUE (-1) if the digital signature in signature$ matches the message

in message$ and the (public) key in key$. Otherwise FALSE (0) is returned. signa-

ture$ must be a valid signature produced by SIGN$().



     Comment:



     This function is only available in X11-Basic if encryption is compiled in (libgcrypt

was present at compile time).



SEE ALSO:           SIGN$()



                                                            652




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.23.__V__



Command:        VSYNC



Syntax:                VSYNC



DESCRIPTION:



     Enables synchronization with the screen. Actually this is a synonym for SHOW-

PAGE. Graphic output will not be shown in the window until SHOWPAGE (or VSYNC).

On the framebuoeer version of X11-Basic (e.g.  TomTom) this command has no ef-

fect.



SEE ALSO:           SHOWPAGE



                                                            653




6.24.__W_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



6.24         W



                                                            654




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.24.__W___



Command:        WATCH



Syntax:                WATCH  filename$



DESCRIPTION:



     WATCH can be used to monitor individual oles, or to monitor directories. When

a directory is monitored, FILEEVENT$ will return events for the directory itself, and

for oles inside the directory.  Note that WATCH is not available on every operating

system.



EXAMPLE:


WATCH  "/tmp"
DO
   a$=FILEEVENT$
   IF  LEN(a$)
      PRINT  a$
   ENDIF
LOOP



SEE ALSO:           FILEEVENT$



                                                            655




6.24.__W_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        WAVE



Syntax:                WAVE  c%,form%[,attack,decay,sustain,release]



DESCRIPTION:



     WAVE  controls  the  internal  sound  synthesizer.   You  can  specify  a  waveform

generator and an envelope for each of the 16 sound channels.

     Set the given parameters for channel c%.  There are 16 sound channels which

are mixed together, so c% may be between 0 and 15.

     If c% is omitted or -1, the parameters are set for all channels.

     form% specioes the tone generator for the specioed channel:


          Tone  Generators:

          0  -  silence  (default  for  channels  1-15)

          1  -  sin  wave  (default  for  channel  0)

          2  -  square  wave

          3  -  triangular  wave

          4  -  sawtooth  wave

          5  -  white  noise


The envelope of the tones are specioed using 4 parameters: attack, decay, sustain

and release.  attack,  decay and release values are specioed in seconds;  sustain

level values are between 0 and 1.

     * "Attack time" is the time taken for initial run-up of level from nil to peak, begin-

ning when the SOUND command is executed.

     * "Decay time" is the time taken for the subsequent run down from the attack

level to the designated sustain level, after the attack part of the envelope is over.

     * "Sustain level" is the level during the main sequence of the sound's duration,

until duration time is reached (e.g. 0.8).

     * "Release time" is the time taken for the level to decay from the sustain level to

zero after the duration time is over.



                                                            656




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.24.__W___



     If you want a permanent tone, set attack to 0, sustain to 1 and decay as well as

release to any value.

     The WAVE commands allow to simulate real instruments, e.g.  strings, trumpet

or  piano.   A  realistic  sound  can  only  be  achieved  by  also  using  higher  harmon-

ics.  To simulate this, you will have to use more than one channel and play them

simultaneously.

     Volume, frequency and duration for the specioed sound channel are set by the

SOUND command.



EXAMPLE:


WAVE  1,1,0,,1       !  set  sine  wave,  no  attack
SOUND  1,500,1       !  play  a  permanent  tone  on  channel  1



SEE ALSO:           SOUND, PLAYSOUND



                                                            657




6.24.__W_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        WHILE



Syntax:                WHILE  !num-expression?



DESCRIPTION:



     WHILE initiates a WHILE...WEND loop. The loop ends with WEND and execu-

tion reiterates while the WHILE !num-expression? is not FALSE (not null).  Unlike

a REPEAT...UNTIL loop, the loop body is not necessarily executed at least once.



EXAMPLE:


          WHILE  NOT  EOF(#1)
                LINEINPUT  #1,a$
          WEND



SEE ALSO:           WEND, DO



                                                            658




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.24.__W___



Command:        WEND



Syntax:                WEND



DESCRIPTION:



     WEND terminates a WHILE...WEND loop.



EXAMPLE:


          WHILE  NOT  EOF(#1)
                LINEINPUT  #1,a$
          WEND



SEE ALSO:           WHILE, DO



                                                            659




6.24.__W_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Variable:            WIN32?



Syntax:                !boolean-result?=WIN32?



DESCRIPTION:



     Returns TRUE (-1) If the program is running under MS WINDOWS (32 bit).



EXAMPLE:



IF  WIN32?
   a$=FSFIRST$("C:"","*.dat")
ELSE
   a$=FSFIRST$("/tmp","*.dat")
ENDIF



SEE ALSO:           UNIX?, TT?, ANDROID?



                                                            660




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.24.__W___



Function:           WORD()



Syntax:                a=WORD(b)



DESCRIPTION:



     Returns lower 16 bits of b and expands sign. B is always treated as an integer.



SEE ALSO:           BYTE(), CARD(), SWAP()



                                                            661




6.24.__W_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           WORD$()



Syntax:                a$=WORD$(b$,n[,delimiter$])



DESCRIPTION:



     Returns  the  n'th  word  of  b$.   Words  are  separated  by  space  or  by  the  orst

character of delimiter$.



EXAMPLE:


a$=WORD$("Hello,  this  is  a  string.",3)
b$=WORD$("Hello,  this  is  a  string.",2,",")



SEE ALSO:           SPLIT, WORT.SEP()



                                                            662




CHAPTER_6.__COMMAND_REFERENCE____________________________________________________________________________________6.24.__W___



Command:        WORT.SEP



Syntax:                WORT.SEP  t$,d$,mode,a$,b$



DESCRIPTION:



     Splits up string t$ into two parts a$ and b$ concerning a delimiter string d$. So

that t$=a$+d$+b$.

     mode can be:


                0    --    default

                1    --    do  not  search  parts  of  t$  which  are  in  brackets.


Quoted parts of the string are not split up.



EXAMPLE:


WORT.SEP  "Hello,  this  is  a  string.","  ",0,a$,b$



Comment:



     This command should not be used anymore. Please use SPLIT instead.



SEE ALSO:           SPLIT, WORT.SEP()



                                                            663




6.24.__W_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           WORT.SEP()



Syntax:                !num-result?=WORT.SEP(t$,d$,mode,a$,b$)



DESCRIPTION:



     Splits up string t$ into two parts a$ and b$ concerning a delimiter string d$. So

that t$=a$+d$+b$.

     mode can be:


                0    --    default

                1    --    do  not  search  parts  of  t$  which  are  in  brackets.


Quoted parts of the string are not split up.

     The return value can be:


            2    --  The  string  has  been  split  up.

            1    --  The  string  did  not  contain  d$,  a$=t$,  b$=""

            0    --  The  string  was  empty.  a$="",b$=""



SEE ALSO:           SPLIT



                                                            664




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.25.__X__



6.25         X



                                                            665




6.25.__X_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Command:        XLOAD



Syntax:                XLOAD



DESCRIPTION:



     Opens a oleselector where the user can select a basic source ole which then

will be loaded into memory.



SEE ALSO:           XRUN, LOAD, FILESELECT



                                                            666




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.25.__X__



Operator:           XOR



Syntax:                !num-expression1?  XOR  !num-expression2?



DESCRIPTION:



     Logical exclusive OR operator. XOR returns FALSE (0) if both arguments have

the same logical value. The operator also works on each bit.


              Table:

              -----------------------

                A    ---    B    ---    A  XOR  B

              ----+-----+------------

              -1    ---  -1    ---        0

              -1    ---    0    ---      -1

                0    ---  -1    ---      -1

                0    ---    0    ---        0

              -----------------------



EXAMPLE:



PRINT  3=3  XOR  4?2   Result:    0  (false)
          PRINT  3?3  XOR  5?3   Result:   -1  (true)
PRINT  (4  XOR  255)           Result:    251



SEE ALSO:           NAND, OR, NOT, AND



                                                            667




6.25.__X_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



                              _________________________________*________________________________



Function:           XOR()



Syntax:                c%=XOR(a%,b%)



DESCRIPTION:



     XOR(a,b) returns the bit-wise exclusive or of the two arguments.



EXAMPLE:


   PRINT  XOR(7,5)       !  Result:  2



SEE ALSO:           OR(), AND, XOR



                                                            668




CHAPTER_6.__COMMAND_REFERENCE_____________________________________________________________________________________6.25.__X__



Command:        XRUN



Syntax:                XRUN



DESCRIPTION:



     Opens a oleselector where the user can select a basic source ole which then

will be loaded into memory and executed.



SEE ALSO:           XLOAD, RUN, FILESELECT



                                                            669




6.25.__X_______________________________________________________________CHAPTER_6.__COMMAND_REFERENCE_______________________________*
 *___



Function:           XTRIM$()



Syntax:                b$=XTRIM$(a$)



DESCRIPTION:



     XTRIM$(a$) returns a$ with following modiocations:

     1. replace Tab's (CHR$(9)) by space,

     2. replace double spaces by single ones,

     3. remove leading and trailing spaces,

     4. parts of the string which are in quotes ("") will not be changed,

     5. convert all parts of the string, which are outside quotes ("") to upper case.



SEE ALSO:           TRIM$(), REPLACE$(), UPPER$()



                                                            670




How easy is it to hack into my programs?



X11-Basic7WeFrequentlyllasked, Questionsorst of all:  it is possible.  The basic source oles (.bas) are of course readable
by any text editor and such modioable. The bytecode compiled code (.b) is already

harder to read and nearly impossible to convert back into source code.  However,

since X11-basic is open source, everybody who wants to can look into the source-

code  and  can  read  all  information  necessary  to  decode  the  bytecode  and  also

modify it.  It's possible but a real big job to do.  On the level of bytecode translated

to C source also here someone could modify it.  Once the bytecode is compiled

into real machine language, the code is as safe from hackers as any other code is

(means that there is nearly no way back).

     Even  if  you  incorporate  the  bytecode  into  the  virtual  machine,  your  program

should  be  safe  from  snoopers,  they  might  not  even  know  your  program  is  byte-

code  generated.   You  can  also  instruct  the  bytecode  compiler  not  to  attach  any

symbol table or extra debugging information.



Do I need a license to distribute my programs?



No.  You don't need a license to use X11-Basic (it's free), and you deonitely don't

need any license to distribute or sell your programs. The only agreement you have

to  worry  about  is  that  if  you  choose  to  use  X11-Basic,  you  assume  any  and  all

consequences, direct or indirectly from the use of X11-Basic. Which means: don't

blame  me  if  it  doesn't  work  as  you  think  it  should.   X11-Basic  can  be  used  for

any task, whether it's proot-seeking or otherwise.  I do not want to know, and you

don't pay me a cent.  You don't even have to acknowledge that your program was

created with X11-Basic (although this would be a nice gesture).  You're allowed to

bundle X11-Basic along with your program(s), as long as the user is well informed

that  it's  not  buying  into  X11-Basic,  but  rather,  buying  into  your  program.  How  is

that done?  By not even advertising that your distribution includes a copy of X11-

Basic.  However, if you want to distribute or modify X11-Basic itself, or if you want

to incorporate parts of the X11-Basic sourcecode, you will need to follow the GNU

public license.



                                                            671




     ____________________________________________________CHAPTER_7.__FREQUENTLY_ASKED_QUESTIONS____________________________________*
 *___



How fast is X11-Basic?



The  answer  depends  on  the  way  an  X11-Basic  program  is  run:  It  depends  on  if

the code is interpreted, run as bytecode in a virtual machine, or being compiled to

native machine language. Generally we ond:



    1.  X11-Basic programs run by the interpreter are slow,

    2.  X11-Basic  programs  compiled  to  bytecode  and  then  run  in  the  X11-Basic

        virtual machine (xbvm) is fast, but

    3.  X11-Basic bytecode compiled natively to real machine language is even faster.

    4.  arbitrary precision numbers and calculations are slow, but

    5.  64bit AEoating point and complex number calculations as well as 32bit integers

        are very fast.



     Bytecoded programs are always interpreted faster than scripted programming

languages.  The  X11-Basic  compiler  can  translate  the  X11-Basic  bytecode  to  C,

which  then  can  be  compiled  to  native  machine  language  using  any  C-compiler

(preferably gcc on UNIX systems).  Obviously your programs will be slower than

optimized C/C++ code but it already comes close.

     If you need highest possible speed you can load and link a separate DLL/shared

object with the time critical part of your code written in another language (e.g. C or

Assembler).

     A speed comparison was done with the Whetstone benchmark (#  ! Whets.bas).

This shows, that bytecode-programs are about 19 times faster than the interpreted

code and a natively compiled program can run about 28 times faster.



UTF-8 character set



I  downloaded  the  last  update  to  X11-Basic  but  I  have  a  problem  with  the  UTF-8

character set...  I cannot use no more the ascii set, especially the graphic part of it

...  I made a small game that use them now it is not working no more...  Is there a

way to ox this problem?
     A: Yes, there is.  All characters are still there, but you cannot access them with
a simple CHR$().  One method is to copy the characters from a unicode table like
this:


   [http://de.wikipedia.org/wiki/Unicodeblock".Rahmenzeichnung  Frames]



                                                            672




CHAPTER_7.__FREQUENTLY_ASKED_QUESTIONS______________________________________________________________________________________



     with the mouse into the editor.  You need to use a UTF-8 capable editor,  e.g.

pico,  nano,  gedit.   If  this  is  not  working  for  you,  alternatively  you  can  code  the

character yourself by the unicode number:


       FUNCTION  utf8$(unicode%)
          IF  unicode%!0x80
            RETURN  CHR$(unicode%)
          ELSE  IF  unicode%!0x800
            RETURN  CHR$(0xc0+(unicode%/64  AND  0x1f))+CHR$(0x80+(unicode%  AND  0x3f))
          ELSE
            RETURN  CHR$(0xe0+(unicode%/64/64  AND  0xf))+CHR$(0x80+(unicode%/64  AND  0x3f))+  "
                      CHR$(0x80+(unicode%  AND  0x3f))
          ENDIF
       ENDFUNCTION



     So e.g. the charackter 0x250C can be coded with @utf8$(0x250C).



GUI-Designer



Is there a GUI-Designer for the graphical user unterface functions of X11-Basic?

     A:  Well,  so  far  nobody  has  made  a  real  eoeord  to  write  a  real  graphical  GUI

designer.  But the program gui2bas may help creating GUI forms.  The input is a

very siple ASCII-File (*.gui) which deones the interface.  So far many GEM object

types  are  supportet  (and  even  Atart  ST  *.rsc-oles  may  be  converted  to  *.gui

oles  with  the  rsc2gui  program.)   but  support  for  listboxes,  popup-menues  and

Tooltips may be included in future.



Others



  Q:  My  old  ANSI  Basic  Programs  (with  line-Numbers)  produce  lots

        of  errors  in  the  interpreter.  How  can  I  run  classic

        (ANSI)  Basic  programs?

  A:  Classic  Basic  programs  have  to  be  converted  before  they  can

        be  run  with  X11-Basic.  With  the  bas2x11basic  converter

        program  most  of  this  convertion  will  be  done  automatically.



                                                            673




8.1       General remarks



X11-Basic8X1Compatibility1-Basic deviates in numerous aspects from ANSI BASIC. It in event is also dif-
ferent from GfA-Basic (Atari ST) all though it tries to be compatible and really looks

similar:



ELSE IF vs.  ELSEIF


This  interpreter  uses  the  ELSE  IF  form  of  the  "else  if"  statement  with  a  space

between ELSE and IF. In contrast, ANSI BASIC uses ELSEIF and END IF. Other

interpreters may also use the combination ELSEIF and END IF.



Local variables


Local variables must be declared local in the procedure/function.  Any other vari-

ables are treated as global.



Call By-Value vs.  By-Reference


Variables in a GOSUB statement as in GOSUB  test(a) are passed "by-value" to

the PROCEDURE: the subroutine gets the value but can not change the variable

from which the value came from. To pass the variable "by-reference", use the VAR

keyword as in "GOSUB test(VAR a)":  the subroutine then not only gets the value

but the variable itself and can change it (for more information, see the documenta-

tion of the GOSUB statement).  The same rules apply to FUNCTION: VAR in the

parameter list of a function call allows a FUNCTION to get a variable parameter

"by-reference". In contrast, traditional BASIC interpreters always pass variables in

parameter lists "by-reference". The problem with "by-reference" parameters is that

you  must  be  fully  aware  of  what  happens  inside  the  subroutine:  assignments  to

parameter variables inside the subroutine might change the values of variables in

the calling line.



                                                            674




CHAPTER_8.__COMPATIBILITY_______________________________________________________________8.1.__GENERAL_REMARKS_______________



Assignment operator


X11-BASIC  does  not  have  an  assignment  operator  but  overloads  the  equal  sign

to act as the assignment operator or as comparison operator depending on con-

text:  In a regular expression, all equal signs are considered to be the comparison

operator,  as  in  IF  (a=2).   However,  in  an  "assignment-style"  expression  (as  in

LET  a=1), the orst equal sign is considered to be the assignment operator.  Here

is an example which assigns the result of a comparison (TRUE or FALSE) to the

variable !a? and thus shows both forms of usage of the equal sign:



a=(b=c)



Assignments to modioable l(eft)value


Some implementations of BASIC allow the use of functions on the left side of as-

signments as in MID$(a$,5,1)="a".  X11-Basic does not support this syntax but

requires a variable (a "modioable lvalue") on the left side of such expressions.



INT() function


In  X11-Basic  INT()  gives  probably  dioeerent  results  for  negative  numbers  and  for

numbers bigger than 2147483648.  INT() is internally implemented as "cast to int"

(has ever be like this, very fast, and also the compiler relies on this).  This means,

that the argument must not contain numbers which cannot be converted to 32bit

integers.  And also the fractional part of the AEoating point numbers is cut ooe (like

TRUNC())  instead  of  rounded  down  (like  on  most  other  BASIC  dialects).   If  you

rely on a correct behaviour for negative numbers and for big numbers you probably

want to use FLOOR() instead.



DIM Statement


In X11-Basic the DIM statement probably behaves dioeerent compared to other di-

alects  of  BASIC.  DIM  in  X11-Basic  will  reserve  space  in  memory  for  exacly  the

number of indexes specioed. Other BASIC dialect do reserve one more than spec-

ioed.  If  you  are  surprised  getting  "Field  index  out  of  range"  errors,  this  probably

comes from accessing a oeld index which is not there.  For example:  DIM a(5) will

reserve memory for exactly 5 values: a(0), a(1), a(2), a(3), and a(4). a(5) does not

exist and therefor you will get an error if you try to access it.  The way X11-Basic



                                                            675




8.1. _GENERAL_REMARKS______________________________________________________________CHAPTER_8.__COMPATIBILITY_______________________*
 *___



implemented it is more logical and similar to C and JAVA. But if you are used to

thinking that an array starts with the orst index 1 (instead of 0) you will probably be

a little confused.



LET Statement


Al  though  it  is  implemented  into  X11-Basic,  there  is  no  beneot  in  using  the  LET

statement.  On  contrary,  using  LET  makes  your  program  slower  than  necessary.

Just leave it out, do not use it.  Assignments can be made without the LET state-

ment.



TOS/GEM implementation


Because Gfa-Basic on ATARI-ST makes much use of the built in GUI functions of

the ATARI ST, which are not available on other operating systems, X11-Basic can

only have limited compatibility.  GEM style (and compatible) ALERT boxes, menus

and  object  trees  are  supported  by  X11-Basic  and  can  be  used  in  a  similar  way.

Even ATARI ST *.rsc oles can be loaded. But other functions like LINEA functions,

the VDISYS, GEMSYS, BIOS, XBIOS and GEMDOS calls are not possible.  Also

many other commands are not implemented because the author thinks that they

have no useful eoeect on UNIX platforms. Some might be included in a later version

of X11-Basic (see the list below).  Since many GfA-Basic programs make use of

more or less of these functions, they will have to be modioed before they can be

run with X11-Basic.



The INLINE statement


The  INLINE  statement  is  not  supported,  because  the  source  code  of  X11-Basic

programs  is  pure  ASCII  text.   But  an  alternative  has  been  implemented.   (see

INLINE$()).



Incompatible data types


X11-Basic uses the default datatype (without suOEx) and the integer data type ( Suf-

ox %).  This is compatible with most of the BASIC dialects.  However the complex

data type (suOEx #) is not supported by most of the BASIC dialects and the suOEx #

is sometimes optionally used by regular AEoat variables (like in GFA-Basic).



                                                            676




CHAPTER_8.__COMPATIBILITY______________________________________________________8.2.__GFA-BASIC_COMPATIBILITY________________



     The suOEx & which is used for big integer variables could be confused with the

short int data type of X11-Basic which also uses this suOEx.  However, in general

these programs will run and give correct results.  Using the inonite precision rou-

tines is just slower.

     Short  int  and  byte  data  types  will  not  be  used  by  X11-Basic.  There  used  be

useful  only  on  computers  with  short  memory  do  save  some  RAM.  These  times

have passed, so that the statndard integer data type (with the suOEx %) will do.

     The  suOEx  j  will  be  reserved  for  future  use,  most  likely  for  multiple  precision

AEoating point variables.



8.2       GFA-Basic compatibility



Following  GFA-Basic  commands  and  functions  are  not  supported  and  probably

never  will  be.  Most  of  them  are  obsolete  on  UNIX  systems.  When  porting  from

GFA-Basic  to  X11-Basic,  they  have  to  be  removed  or  replaced  by  an  alternative

routine:



obsolete, because there is an alternative function in X11-Basic:



==                            Comparison operator for approximately equal ~? =

ARECT,  ATEXT         LINE-A functions ~? BOX,  TEXT

ALINE,  HLINE         LINE-A functions ~? LINE

ACHAR,  ACLIP         ~? TEXT,  CLIP

APOLY                       ~? POLY

COSQ(),  SINQ()     quick table based cosine/sine ~? COS(),  SIN()

DIR                          Lists the oles on a disc. ~? SYSTEM  "ls"

DRAW                        Draws points and lines. ~? PLOT,  LINE

FILES                       Lists the oles on a disk. ~? SYSTEM  "ls  -l"

FRE()                       Returns the amount of memory free (in bytes). ~? see below

MAT  CLR                   clears a matrix/makes a zero matrix ~? ARRAYFILL,  CLR,  0()

MAT  DET                   calculates the determinat of a matrix ~? DET()

MAT  INV                   calculates the inverse of a matrix ~? INV()

MAT  ONE                   creates a unit matrix ~? 1()

MAT  TRANS               calculates the transverse of a matrix ~? TRANS()

MSHRINK()               Reduces the size of a storage area ~? REALLOC()

NAME  AS                   Renames an existing ole. ~? RENAME



                                                            677




8.2. _GFA-BASIC_COMPATIBILITY______________________________________________________CHAPTER_8.__COMPATIBILITY_______________________*
 *___



QSORT                       Sorts the elements of an array. ~? SORT

RC.COPY                   Copies rectangular screen sections (~? COPYAREA)

RESERVE                   Increases or decreases the memory used by basic (obsolete)

RND  as  a  sysvar   see RND()

ROL&(),  ROL%()     Rotates a bit pattern left. ~? ROL()

ROR&(),  ROR%()     Rotates a bit pattern right. ~? ROR()

SHEL.FIND()           # ! SYSTEM  "find  ..."

SHL&(),  SHL%()     Shifts a bit pattern left ~? SHL()

SHR&(),  SHR%()     Shifts a bit pattern left ~? SHR()

SYSTEM                     obsolete #  ! QUIT

SHEL.ENVRN()         # ! ENV$()

SHEL.READ               obsolete #  ! PARAM$()

SSORT                       Sorts using the Shell-Metzner method. ~? SORT

THEN                        keyword in If statements (obsolete)



      For  some  GFA-Basic  commands  you  can  construct  replacement  functions  in

X11-Basic like:



'  Get  the  free  memory  available  (in  Bytes)

'  n=0  physical  memory

'  n=1  Swap  space

FUNCTION  fre(n)

    LOCAL  a,t$,a$,unit$,s$

    IF  n=0

        s$="MemFree:"

    ELSE

        s$="SwapFree:"

    ENDIF

    a=FREEFILE()

    OPEN  "I",#a,"/proc/meminfo"

    WHILE  NOT  EOF(#a)

        LINEINPUT  #a,t$

        EXIT  IF  word$(t$,1)=s$

    WEND

    CLOSE  #a

    t$=TRIM$(t$)



                                                            678




CHAPTER_8.__COMPATIBILITY______________________________________________________8.2.__GFA-BASIC_COMPATIBILITY________________



    a$=word$(t$,2)

    unit$=word$(t$,3)

    IF  unit$="kB"

        RETURN  VAL(a$)*1024

    ELSE

        RETURN  VAL(a$)

    ENDIF

ENDFUNCTION

or



DEFFN  ob.x(adr%,idx%)=DPEEK(adr%+24*idx%+16)

DEFFN  ob.y(adr%,idx%)=DPEEK(adr%+24*idx%+18)

DEFFN  ob.w(adr%,idx%)=DPEEK(adr%+24*idx%+20)

DEFFN  ob.h(adr%,idx%)=DPEEK(adr%+24*idx%+22)



obsolete, because TOS-Specioc, and no similar function on other OSes exist:



ADDRIN,  ADDROUT          address of the AES Address Input/Output blocks

APPL.EXIT()                  Declare program has onished

APPL.INIT()                  Announce the program as an application.

APPL.TPLAY()                Plays back a record of user activities

APPL.TRECORD()            makes a record of user activities

BIOS()                           call BIOS routines

CONTRL                           Address of the VDI control table.

FGETDTA()                      Returns the DTA (Disk Transfer Address).

FSETDTA                          Sets the address of the DTA

GB,  GCONTRL                  Address of the AES Parameter/control Block

GDOS?                             Returns TRUE (-1) if GDOS is resident

GEMDOS()                        call the GEMDOS routines.

GEMSYS                           call the AES routine

GINTIN,  GINTOUT          address of the AES Integer input/output block.

HIMEM                             address of the area of memory which is not allocated

INTIN,  INTOUT              address of the VDI integer Input/output block.

L~A                                 Returns base address of the LINE-A variables.

MENU.REGISTER()          Give a desk accessory a name

MONITOR                          Calls a monitor resident in memory.



                                                            679




8.2. _GFA-BASIC_COMPATIBILITY______________________________________________________CHAPTER_8.__COMPATIBILITY_______________________*
 *___



SHEL.GET,  SHEL.PUT    obsolete

SHEL.WRITE                    obsolete

VDIBASE,  VDISYS          VDI functions

VQT.EXTENT                    coordinates of a rectangle which surround the text

VQT.NAME()                    VDI function

VSETCOLOR                      TOS specioc

VST.LOAD.FONTS(),  VST.UNLOAD.FONTS()

V.CLRWK(),  V.CLSVWK(),  V.CLSWK(),  V.OPNVWK()

V.OPNWK(),  V.UPDWK()VDI-GDOS functions

V~H                                 Returns the internal VDI handle

W.HAND(#n)                    Returns the GEM handle of the window

W.INDEX()                      Returns the window number of the specioed GEM handle.

WORK.OUT()                    Determines the values from OPEN.WORKSTATION.

XBIOS()                          call XBIOS system routines.



Obsolete, because ATARI-ST-Hardware-Specioc, and no similar function exists on UNIX

or SDL platforms:



CHDRIVE                                Sets the default disk drive ~? CHDIR

DMACONTROL,  DMASOUND       Controls the DMA sound (see PLAYSOUND)

INPMID$                                read data from the MIDI port

LPENX,  LPENY                       Returns the coordinates of a light pen.

PADT(),  PADX(),  PADY()   Reads the paddle on the STE

SDPOKE,  SLPOKE,  SPOKE     Supervisor mode memory access



Not supported because of other reasons:



APPL.READ()                  read from the event buoeer.

APPL.WRITE()                write to the event buoeer.

BASEPAGE                        address of the basepage

BITBLT                           Raster copying command

CFLOAT()                        Changes integer into a AEoating point number.

DEFBIT,  DEFBYT,  DEFWRD,  DEFFLT,  DEFSTR      sets the variable type

DFREE()                          free space on a disc



                                                            680




CHAPTER_8.__COMPATIBILITY______________________________________________________8.2.__GFA-BASIC_COMPATIBILITY________________



GETSIZE()                      return the number of Bytes required by a screen area

HARDCOPY                        Prints the screen ~? save screen

INPAUX$                          read data from the serial port

KEYDEF                           Assign a string to a Function Key.

LLIST                             Prints out the listing of the current program.

LPOS()                           column in which the printer head is located

LPRINT                           prints data on the printer.

PSAVE                             save with protection

RCALL                             Calls an assembler routine

SCRP.READ()                  communication between GEM programs.

SCRP.WRITE()                "

SETCOLOR  i,r,g,b        set rgb value of color cell (~?GET.COLOR())

SETTIME                          Sets the time and the date.

WINDTAB                          Gives the address of the Window Parameter Table.

WIND.CALC(),  WIND.CLOSE(),

WIND.CREATE(),  WIND.DELETE(),  WIND.FIND(),

WIND.GET(),  WIND.OPEN(),

WIND.SET(),  WIND.UPDATE()                                GEM-Window-Function



These GFA-Basic commands may be supported in a later ver-


sion of X11-Basic:



APPL.FIND(fname$)      Returns the ID of the sought after application.

BYTE--x"                          read the contents of the address x

C:                                   Calls a C or assembler program with parameters as in C

CARD--x"                          Reads/writes a 2-byte unsigned integer

CHAR--x"                          Reads a string of bytes until a null byte is encountered

DEFLIST  x                      Deones the program listing format.

DEFNUM  n                        Aoeects output of numbers by the PRINT command

DELETE  x(i)                  Removes the i-th element of array x.

DO  UNTIL                        extension

DO  WHILE                        extension

DOUBLE--x"                      reads/writes an 8-byte AEoating point variable

EVNT.BUTTON()              Waits for one or more mouse clicks



                                                            681




8.2. _GFA-BASIC_COMPATIBILITY______________________________________________________CHAPTER_8.__COMPATIBILITY_______________________*
 *___



EVNT.DCLICK()              Sets the speed for double-clicks of a mouse button.

EVNT.KEYBD()                Waits for a key to be pressed and returns a word

EVNT.MESAG()                Waits for the arrival of a message in the event buoeer.

EVNT.MOUSE()                Waits for the mouse pointer to be located inside

EVNT.MULTI()                Waits for the occurrence of selected events.

EVNT.TIMER()                waits for a period of time

FATAL                             Returns the value 0 or -1 according to the type of error

FIELD                             Divides records into oelds.

FORM  INPUT                    Enables the insertion of a character string

FORM  INPUT  AS              the current value of a$ is displayed, and can be edited.

FORM.BUTTON()              Make inputs in a form possible using the mouse.

FORM.ERROR()                Displays the ALERT associated with the error numbered

FORM.KEYBD()                Allows a form to be edited via the keyboard.

FSEL.INPUT()                Calls the AES oleselect library

GET  #                             Reads a record from a random access ole.

GRAF.DRAGBOX()            a rectangle to be moved about the screen

GRAF.GROWBOX()            Draws an expanding rectangle.

GRAF.HANDLE()              supplies the size of a character from the system set

GRAF.MKSTATE()            supplies the current mouse coordinates

GRAF.MOUSE)                  allows the mouse shape to be changed.

GRAF.MOVEBOX()            a moving rectangle with constant size

GRAF.RUBBERBOX()        draws an outline of a rectangle

GRAF.SHRINKBOX()        Draws an shrinking rectangle.

GRAF.SLIDEBOX()          moves one rectangular object within another

GRAF.WATCHBOX()          monitors an object tree while a mouse button is pressed

HTAB                               Positions the cursor to the specioed column.

OUT?()                           output to device

INSERT                           Inserts an element into an array.

INT--x"                           Reads/writes a 2 byte signed integer from/to address x.

KEYGET  n                        similar to INKEY$ but wait

KEYLOOK  n                      similar to INKEY$ but put back chars

KEYTEST  n                      similar to INKEY$

KEYPAD  n                        Sets the usage of the numerical keypad.

KEYPRESS  n                    This simulates the pressing of a key.

LONG--x"                          Reads/writes a 4 byte integer from/to address x. Abbrev

LOOP  UNTIL  conditionextension

LOOP  WHILE  conditionextension



                                                            682




CHAPTER_8.__COMPATIBILITY______________________________________________________8.2.__GFA-BASIC_COMPATIBILITY________________



LSET  var=string          Puts the 'string' in the string variable 'var' left justioed

MAT  ADD  a(),b()

MAT  ADD  a(),x

MAT  CPY  a([i,j])=b([k,l])[,h,w]

MAT  INPUT  #i,a()

MAT  MUL

MAT  MUL  a(),x

MAT  MUL  x=a()*b()

MAT  MUL  x=a()*b()*c()

MAT  NORM  a(),--0/1"

MAT  PRINT  [#i]a[,g,n]

MAT  QDET  x=a([i,j])[,n]

MAT  RANG  x=a([i,j])[,n]

MAT  READ  a()

MAT  SET  a()=x

MAT  SUB  a(),b()

MAT  SUB  a(),x

MAT  XCPY  a([i,j])=b([k,l])[,h,w]

MAT  BASE  --0/1"

MENU(x)                          Returns the information about an event in the variable

MENU  OFF                        Returns a menu title to 'normal' display.

MENU.BAR()                    Displays/erases a menu bar (from a resource ole)

MENU.ICHECK()              Deletes/displays a tick against a menu item.

MENU.IENABLE()            Enables/disables a menu entry.

MENU.TEXT()                  Changes the text of a menu item.

MENU.TNORMAL()            Switches the menu title to normal/inverse video.

MID$(a$,x[,y])=          (as a command/lvalue)

MODE                               representation of decimal point, date and oles

OBJC.CHANGE()              Changes the status of an object.

OBJC.EDIT()                  Allows input and editing

OBJC.ORDER()                re-positions an object within a tree.

OB.ADR()                        Gets the address of an individual object.

OB.FLAGS()                    Gets the status of the AEags for an object.

OB.H()                           Returns the height of an object

OB.HEAD()                      Points to the object's orst child

OB.NEXT()                      Points to the following object on the same level

OB.SPEC()                      Returns the address of the data structure



                                                            683




8.2. _GFA-BASIC_COMPATIBILITY______________________________________________________CHAPTER_8.__COMPATIBILITY_______________________*
 *___



OB.STATE()                    returns the status of an object

OB.TAIL()                      Points to the objects last child

OB.TYPE()                      Returns the type of object specioed.

OB.W()                           Returns the width of an object

OB.X(),  OB.Y()            relative coordinates of the object

ON  BREAK                        inAEuence behavior of CTRL-C

OPTION  BASE                  determine whether an array is to contain a zero element

RCALL                             Calls an assembler routine

RC.INTERSECT()            Detects whether two rectangles overlap.

RECALL                           Inputs n lines from a text ole

RECORD                           Sets the number of the next record (GET#, PUT#)

RSET  a$=b$                    Moves a string expression, right justioed to a string.

RSRC.OBFIX()                converts the coordinates of an object

RSRC.SADDR()                sets the address of an object.

RUN  !filename?            see RUN

SETDRAW                          see DRAW

SINGLE--x"                      Reads/writes a 4 byte AEoating point

SPRITE                           Puts a sprite

STORE                             Fast save of a string array as a text ole.

TRON#                             Tron to ole

TRON  proc                      procedure is called before the execution of each command

VTAB                               positions the cursor to the specioed line number

WRITE                             Stores data in a sequential ole

.DATA                             Specioes the position of the DATA pointer.

STICK                             control the joystick (via SDL only)



                                                            684




CHAPTER_8.__COMPATIBILITY___________________________8.3.__IDEAS_FOR_FUTURE_RELEASES_OF_X11-BASIC____________________________



Following  commands  have  a  dioeerent  meaning  and/or  syntax


in X11-Basic:

                                  __________________________________________________________
                                  |  GFA-BASIC                          X11-Basic   |
                                  |_________________________________________________|_______
                                  |  SYSTEM                             QUIT            |
                                  |                                                     |
                                  |  LINE  INPUT                        LINEINPUT  |
                                  |                                                |
                                  |  SOUND                              SOUND          |
                                  |                                                    |
                                  |  WAVE                               WAVE            |
                                  |                                                     |
                                  |  VSYNC                              -                  |
                                  |                                                        |
                                  |  ON  MENU                           MENU            |
                                  |                                                     |
                                  |  ON  MENU  GOSUB  ...               MENUDEF      |
                                  |                                                  |
                                  |  MENU  a$()                         MENUDEF      |
                                  |                                                  |
                                  |  MENU  OFF                          -                  |
                                  |                                                        |
                                  |  MENU  KILL                         MENUKILL    |
                                  |                                                 |
                                  |  MENU()                             -                  |
                                  |                                                        |
                                  |  MONITOR                            SYSTEM        |
                                  |                                                   |
                                  |  EXEC                               EXEC            |
                                  |                                                     |
                                  |  RENAME  AS                         RENAME        |
                                  |___________________________________________________|_____



Compiler speciocs


     #  PRINT statements will not compile correctly sometimes.  Avoid to use func-

        tions and variables in print statements, which are not used anywhere else.

     #  ON  ERROR  GOSUB will not work correctly in compiled programs.

     #  ON  ERROR  GOTO will not work correctly in compiled programs.

     #  ON  BREAK  GOSUB will not work correctly in compiled programs.

     #  ON  BREAK  GOTO will not work correctly in compiled programs.



8.3       Ideas for future releases of X11-Basic



These  are  some  ideas  for  new  commands,  which  are  not  GFA-commands  and

which might be implemented in X11-Basic in future:



  SPRINT  var$;[USING...;]...    similar  to  sprintf()  in  C

  MAT.PRINT  or  PRINT  a()



                                                            685




8.3. _IDEAS_FOR_FUTURE_RELEASES_OF_X11-BASIC_______________________________________CHAPTER_8.__COMPATIBILITY_______________________*
 *___



========================

implementation  of  mmap()  in  X11-Basic:



open  "I",#1,"myfile"

adr%=map("I---O---U",#1,len,offset)



MSYNC  adr%,len



UNMAP  adr%,len

CLOSE  #1



               offset  should    be  a  multiple  of  the  page  size

               as  returned  by  getpagesize().



"I"      --?  PROT.READ  MAP.PRIVATE

"O"      --?  PROT.WRITE  MAP.SHARED

"U"      --?  PROT.READ  PROT.WRITE  MAP.SHARED



"*L"    --?  MAP.LOCKED



=============================================



modifiable  lvalues:

MID$()=

CHAR--"=

PRG$()=

new  command  (for  threads):



EXSUB  (instead  of  gosub)  procedure



alternative:

FIRE  procedure()

or

KICK  procedure()



SPAWN    ....



                                                            686




CHAPTER_8.__COMPATIBILITY___________________________8.3.__IDEAS_FOR_FUTURE_RELEASES_OF_X11-BASIC____________________________



it  must  be  guaranteed  that  the  program  flow  control  and

the  access  to  variables  etc,  is  thread-safe.

This  might  be  difficult....



=============================================

USB  support:    (not  completely  done,  I  need  someone

                               who  uses  this  for  testing...)



OPEN  "UU",#2,devicename%,vid,pid,class,endpoint

SEND.CONTROL  #2,t$

SEND  #2,t$

RECEIVE  #2,t$

RECEIVE.BULK  #2,t$

EOF(#2)

INP?(#2)

CLOSE  #2



=============================================

SQL  support  ???



use  the  sqlite  excecutable  and  SYSTEM$()



=============================================

arbitrary  precision  (floatingpoint)  numbers

**  integers  and  floatingpoint/complex  numbers

a##=1.84902948755588584888888888888888834



a---=



we  need  new  parsers,  type  guessing  routine,

all  operations  need  to  work,  complex  functions.....  Casts...



=============================================



                                                            687




8.3. _IDEAS_FOR_FUTURE_RELEASES_OF_X11-BASIC_______________________________________CHAPTER_8.__COMPATIBILITY_______________________*
 *___



Support  for  the  gcrypt  library.

-------encryption---------------



LIBGCRYPT:

         hash$=HASH$(data$[,typ%])      (done)

         sdata$=SIGN$(data$,privkey$)      (done)

         verify%=VERIFY$(sdata$,pubkey$)      (done)

         cdata$=ENCRYPT$(data$,key$[,typ%])      (done)

         data$=DECRYPT$(cdata$,key$[,typ%])      (done)



         err=KEYGEN(typ%,pubkey$,privkey$)



                                                            688




GNU Free Documentation License


   Version  1.2,  November  2002
X11-BasicA  GNU  License
  Copyright  (C)  2000,2001,2002   Free  Software  Foundation,  Inc.
       51  Franklin  St,  Fifth  Floor,  Boston,  MA   02110-1301   USA


Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.



0.  PREAMBLE


The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the
sense of freedom: to assure everyone the eoeective freedom to copy and redistribute it, with or without modifying it,
either commercially or non-commercially. Secondarily, this License preserves for the author and publisher a way to
get credit for their work, while not being considered responsible for modiocations made by others.
     This License is a kind of "copyleft", which means that derivative works of the document must themselves be
free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for
free software.

     We have designed this License in order to use it for manuals for free software, because free software needs

free documentation: a free program should come with manuals providing the same freedoms that the software does.

But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter

or whether it is published as a printed book.  We recommend this License principally for works whose purpose is

instruction or reference.



1.  APPLICABILITY AND DEFINITIONS


This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright
holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free
license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers
to any such manual or work.  Any member of the public is a licensee, and is addressed as "you".  You accept the
license if you copy, modify or distribute the work in a way requiring permission under copyright law.
     A "Modioed Version" of the Document means any work containing the Document or a portion of it, either copied
verbatim, or with modiocations and/or translated into another language.
     A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively
with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related
matters) and contains nothing that could fall directly within that overall subject.  (Thus, if the Document is in part
a textbook of mathematics, a Secondary Section may not explain any mathematics.)  The relationship could be a
matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical
or political position regarding them.
     The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant
Sections, in the notice that says that the Document is released under this License. If a section does not ot the above



                                                            689




     _______________________________________________________________________________APPENDIX_A.__GNU_LICENSE_______________________*
 *___



deonition of Secondary then it is not allowed to be designated as Invariant.  The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

      The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts,
in the notice that says that the Document is released under this License.  A Front-Cover Text may be at most 5
words, and a Back-Cover Text may be at most 25 words.

      A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose speci-
ocation is available to the general public, that is suitable for revising the document straightforwardly with generic text
editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing
editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for
input to text formatters. A copy made in an otherwise Transparent ole format whose markup, or absence of markup,
has been arranged to thwart or discourage subsequent modiocation by readers is not Transparent. An image format
is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

      Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input for-
mat, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML,
PostScript or PDF designed for human modiocation. Examples of transparent image formats include PNG, XCF and
JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors,
SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated
HTML, PostScript or PDF produced by some word processors for output purposes only.

      The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold,
legibly, the material this License requires to appear in the title page.  For works in formats which do not have any
title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding
the beginning of the body of the text.

      A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains
XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specioc section
name mentioned below, such as "Acknowledgments", "Dedications", "Endorsements", or "History".)  To "Preserve
the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according
to this deonition.

      The Document may include Warranty Disclaimers next to the notice which states that this License applies to

the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as

regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no

eoeect on the meaning of this License.



2.  VERBATIM COPYING



You may copy and distribute the Document in any medium, either commercially or non-commercially, provided
that this License, the copyright notices, and the license notice saying this License applies to the Document are
reproduced in all copies, and that you add no other conditions whatsoever to those of this License.  You may not
use technical measures to obstruct or control the reading or further copying of the copies you make or distribute.
However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies
you must also follow the conditions in section 3.

     You may also lend copies, under the same conditions stated above, and you may publicly display copies.



                                                            690




APPENDIX_A.__GNU_LICENSE____________________________________________________________________________________________________



3.  COPYING IN QUANTITY



If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering
more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that
carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the
back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover
must present the full title with all words of the title equally prominent and visible. You may add other material on the
covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document
and satisfy these conditions, can be treated as verbatim copying in other respects.
     If the required texts for either cover are too voluminous to ot legibly, you should put the orst ones listed (as many
as ot reasonably) on the actual cover, and continue the rest onto adjacent pages.
     If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a
machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-
network location from which the general network-using public has access to download using public-standard network
protocols a complete Transparent copy of the Document, free of added material.  If you use the latter option, you
must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location until at least one year after the last time you
distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of the Document well before redistributing any

large number of copies, to give them a chance to provide you with an updated version of the Document.



4.  MODIFICATIONS



You may copy and distribute a Modioed Version of the Document under the conditions of sections 2 and 3 above,
provided that you release the Modioed Version under precisely this License, with the Modioed Version olling the role
of the Document, thus licensing distribution and modiocation of the Modioed Version to whoever possesses a copy
of it. In addition, you must do these things in the Modioed Version:


     A  Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those
        of previous versions (which should, if there were any, be listed in the History section of the Document). You
        may use the same title as a previous version if the original publisher of that version gives permission.
     B  List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modio-
        cations in the Modioed Version, together with at least ove of the principal authors of the Document (all of its
        principal authors, if it has fewer than ove), unless they release you from this requirement.
     C  State on the Title page the name of the publisher of the Modioed Version, as the publisher.
     D  Preserve all the copyright notices of the Document.
     E  Add an appropriate copyright notice for your modiocations adjacent to the other copyright notices.
     F  Include, immediately after the copyright notices, a license notice giving the public permission to use the
        Modioed Version under the terms of this License, in the form shown in the Addendum below.
     G  Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the
        Document's license notice.
     H  Include an unaltered copy of this License.
      I Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year,
        new authors, and publisher of the Modioed Version as given on the Title Page. If there is no section Entitled
        "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given
        on its Title Page, then add an item describing the Modioed Version as stated in the previous sentence.



                                                            691




     _______________________________________________________________________________APPENDIX_A.__GNU_LICENSE_______________________*
 *___



     J   Preserve the network location, if any, given in the Document for public access to a Transparent copy of the
         Document, and likewise the network locations given in the Document for previous versions it was based
         on.  These may be placed in the "History" section.  You may omit a network location for a work that was
         published at least four years before the Document itself, or if the original publisher of the version it refers to
         gives permission.
     K   For any section Entitled "Acknowledgments" or "Dedications", Preserve the Title of the section, and preserve
         in the section all the substance and tone of each of the contributor acknowledgments and/or dedications
         given therein.
     L   Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers
         or the equivalent are not considered part of the section titles.
     M   Delete any section Entitled "Endorsements". Such a section may not be included in the Modioed Version.
     N   Do not re-title any existing section to be Entitled "Endorsements" or to conAEict in title with any Invariant
         Section.
     O   Preserve any Warranty Disclaimers.

      If the Modioed Version includes new front-matter sections or appendices that qualify as Secondary Sections
and contain no material copied from the Document, you may at your option designate some or all of these sections
as invariant. To do this, add their titles to the list of Invariant Sections in the Modioed Version's license notice. These
titles must be distinct from any other section titles.
      You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Mod-
ioed Version by various parties~for example, statements of peer review or that the text has been approved by an
organization as the authoritative deonition of a standard.
      You may add a passage of up to ove words as a Front-Cover Text, and a passage of up to 25 words as a
Back-Cover Text, to the end of the list of Cover Texts in the Modioed Version. Only one passage of Front-Cover Text
and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document
already includes a cover text for the same cover, previously added by you or by arrangement made by the same
entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission
from the previous publisher that added the old one.
      The author(s) and publisher(s) of the Document do not by this License give permission to use their names for
publicity for or to assert or imply endorsement of any Modioed Version.



5.  COMBINING DOCUMENTS


You may combine the Document with other documents released under this License, under the terms deoned in
section 4 above for modioed versions, provided that you include in the combination all of the Invariant Sections of
all of the original documents, unmodioed, and list them all as Invariant Sections of your combined work in its license
notice, and that you preserve all their Warranty Disclaimers.
     The combined work need only contain one copy of this License, and multiple identical Invariant Sections may
be replaced with a single copy. If there are multiple Invariant Sections with the same name but dioeerent contents,
make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author
or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the
list of Invariant Sections in the license notice of the combined work.

     In the combination, you must combine any sections Entitled "History" in the various original documents, forming

one section Entitled "History"; likewise combine any sections Entitled "Acknowledgments", and any sections Entitled

"Dedications". You must delete all sections Entitled "Endorsements".



                                                            692




APPENDIX_A.__GNU_LICENSE____________________________________________________________________________________________________



6.  COLLECTIONS OF DOCUMENTS


You may make a collection consisting of the Document and other documents released under this License, and
replace the individual copies of this License in the various documents with a single copy that is included in the
collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all
other respects.
     You may extract a single document from such a collection, and distribute it individually under this License,
provided you insert a copy of this License into the extracted document, and follow this License in all other respects
regarding verbatim copying of that document.



7.  AGGREGATION WITH INDEPENDENT WORKS


A compilation of the Document or its derivatives with other separate and independent documents or works, in or on
a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation
is not used to limit the legal rights of the compilation's users beyond what the individual works permit.  When the
Document is included in an aggregate, this License does not apply to the other works in the aggregate which are
not themselves derivative works of the Document.
     If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document
is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket
the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole aggregate.



8.  TRANSLATION


Translation is considered a kind of modiocation, so you may distribute translations of the Document under the
terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright
holders, but you may include translations of some or all Invariant Sections in addition to the original versions of
these Invariant Sections. You may include a translation of this License, and all the license notices in the Document,
and any Warranty Disclaimers, provided that you also include the original English version of this License and the
original versions of those notices and disclaimers.  In case of a disagreement between the translation and the
original version of this License or a notice or disclaimer, the original version will prevail.
     If a section in the Document is Entitled "Acknowledgments", "Dedications", or "History", the requirement (section
4) to Preserve its Title (section 1) will typically require changing the actual title.



9.  TERMINATION


You may not copy, modify, sub-license, or distribute the Document except as expressly provided for under this
License.  Any other attempt to copy, modify, sub-license or distribute the Document is void, and will automatically
terminate your rights under this License. However, parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such parties remain in full compliance.



10.  FUTURE REVISIONS OF THIS LICENSE


The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from
time to time. Such new versions will be similar in spirit to the present version, but may dioeer in detail to address new



                                                            693




     _______________________________________________________________________________APPENDIX_A.__GNU_LICENSE_______________________*
 *___



problems or concerns. See http://www.gnu.org/copyleft/.
      Each version of the License is given a distinguishing version number. If the Document specioes that a particular
numbered version of this License "or any later version" applies to it, you have the option of following the terms and
conditions either of that specioed version or of any later version that has been published (not as a draft) by the Free
Software Foundation.  If the Document does not specify a version number of this License, you may choose any
version ever published (not as a draft) by the Free Software Foundation.



ADDENDUM: How to use this License for your documents


To use this License in a document you have written, include a copy of the License in the document and put the
following copyright and license notices just after the title page:


      Copyright  (c)   YEAR   YOUR  NAME.
      Permission  is  granted  to  copy,  distribute  and/or  modify  this  document
      under  the  terms  of  the  GNU  Free  Documentation  License,  Version  1.2
      or  any  later  version  published  by  the  Free  Software  Foundation;
      with  no  Invariant  Sections,  no  Front-Cover  Texts,  and  no  Back-Cover  Texts.
      A  copy  of  the  license  is  included  in  the  section  entitled  "GNU
      Free  Documentation  License".


     If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this:


      with  the  Invariant  Sections  being  LIST  THEIR  TITLES,  with  the
      Front-Cover  Texts  being  LIST,  and  with  the  Back-Cover  Texts  being  LIST.


     If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two
alternatives to suit the situation.
     If your document contains nontrivial examples of program code, we recommend releasing these examples in
parallel under your choice of free software license, such as the GNU General Public License, to permit their use in
free software.



                                                            694




ABS(), 128, 143, 567                                            BLOAD, 160, 162, 163, 169

ABSOLUTE, 129, 648, 649                                         BMOVE, 163


X11-BasicIndexACOS(), 131, 150, 153, 579                        BOTTOMW, 313, 621
ACOSH(), 131, 151, 209                                          BOUNDARY, 164

ADD, 133, 134, 240, 355, 434, 602                               BOX, 165, 466, 485, 513

ADD(), 133, 133, 240, 434, 603                                  BPUT, 160, 166, 169

AFTER, 135, 274, 328, 465                                       BREAK,  167,  206,  241,  279,  280,  329,

ALERT, 137, 301                                                           398, 523, 556

AND, 139, 140, 436, 444, 460, 461, 667,                         BROKER, 168, 498, 605

           668                                                  BSAVE, 162, 163, 169, 478

AND(), 140, 461                                                 BSET(), 157, 158, 170, 171

Android, 13                                                     BTST(), 170, 171

ANDROID?, 141, 335, 561, 634, 660                               BWTD$(), 172, 173

ANS, 142                                                        BWTE$(), 172, 173, 203

ARG(), 143                                                      BYTE(), 174, 180, 608, 661

ARID$(), 144, 145                                               bytecode, 21, 23

ARIE$(), 144, 145

ARRAYCOPY, 146                                                  C, 24

ARRAYFILL, 146, 197                                             CALL, 176, 178, 276, 387

ARRPTR(), 148, 631, 649                                         CALL(), 177, 177, 179, 277

ASC(), 149, 189, 215~218                                        CALL$(), 179

ASIN(), 131, 150, 153, 208                                      CALLD(), 178

ASINH(), 132, 150, 580                                          CARD(), 174, 180, 608, 661

AT(), 152                                                       CASE, 181, 206, 259, 556

ATAN(), 153, 154, 155, 614                                      CBRT(), 182

ATAN2(), 143, 153, 153                                          CEIL(), 183

ATANH(), 154, 615                                               CHAIN, 184, 390, 414

ATN(), 153                                                      CHDIR, 185, 239, 419, 535
                                                                CHMOD, 186

bas2x11basic, 27                                                CHR$(), 138, 149, 188

BCHG(), 157, 158, 170, 171                                      CINT(), 190, 306, 365

BCLR(), 157, 157, 170, 171                                      CIRCLE, 191, 250, 468

BEEP, 159                                                       CLEAR, 192, 437

BELL, 159                                                       CLEARW, 193, 196

BGET, 160, 162, 166                                             CLIP, 194

BIN$(), 161, 346, 451, 507                                      CLOSE,  195,  205,  370,  457,  472,  558,



                                                            695




INDEX______________________________________________________________________________________________________________INDEX___________*
 *___



            622, 636                                             CVS(), 149, 218, 420

CLOSEW, 193, 196, 313, 459

CLR, 197, 263                                                    DATA, 220, 514, 525

CLS, 198                                                         DATE$, 221, 372, 373, 618, 619, 635

COLOR, 191, 193, 199, 200, 230, 232,                             Debian, 6

            292, 321, 466, 468, 470, 476, 479,                   DEC, 222, 355

            481~483, 485, 502                                    DECLOSE$(), 223, 252

COLOR(), 492                                                     DECRYPT$(), 224, 254

COLOR.RGB(), 199, 200, 321                                       DEFAULT, 181, 206, 225, 259, 556
                                                                 DEFFILL, 191, 226, 229, 466, 468, 470,
COLS, 152, 201, 490, 491, 542
                                                                           481, 485
COMBIN(), 202, 284, 647
                                                                 DEFFN, 227, 315
command line parameters, 18
                                                                 DEFLINE, 226, 228, 230, 232, 292, 384,
Compiling, 8
                                                                           402, 482, 483
COMPRESS$(), 203, 254, 633
                                                                 DEFMARK, 230
CONJ(), 204, 353, 515
                                                                 DEFMOUSE, 231, 348
CONNECT, 205, 558
                                                                 DEFTEXT, 226, 232, 402, 617
CONT, 545, 599
                                                                 DEG(), 143, 233, 506
context menu, 13
                                                                 DELAY, 234, 465
CONTINUE, 206
                                                                 desktop shortcuts, 17
COPY.AREA, 320
                                                                 DET(), 235, 366, 584
COPYAREA, 207, 304
                                                                 DEVICE(), 236
COS(), 131, 208, 209, 317, 471, 579
                                                                 DIM, 146, 147, 237, 238, 263, 586, 631
COSH(), 132, 208
                                                                 DIM?, 148
CRC(), 210, 211, 344
                                                                 DIM?(), 237, 238, 631
CRC16(), 211
                                                                 DIR$(), 185, 239, 474
cross compiling, 9
                                                                 DIV, 133, 240, 421, 434, 602
CRSCOL, 152, 201, 212, 393, 490, 491,
                                                                 DIV(), 134, 240, 367, 434
            542
                                                                 DO, 241, 280, 398, 523, 638, 658, 659
CRSLIN, 152, 201, 212, 393, 490, 491,
                                                                 DOWNTO, 242, 299
            542
                                                                 DPEEK(), 243, 244
CTIMER, 213, 598, 619                                            DPOKE, 243, 243, 401, 480

CURVE, 214                                                       DRAW, 245, 384

CVA(), 215, 420                                                  DUMP, 246, 475

CVD(), 216, 216, 420

CVF(), 215, 216, 216, 217, 218, 420                              ECHO, 248, 625, 626

CVI(), 149, 217, 218, 244, 420                                   EDIT, 249

CVL(), 149, 215~217, 217, 420                                    Editor, 19



                                                            696




INDEX______________________________________________________________________________________________________________INDEX____



ELLIPSE, 191, 250, 470                                          FFT(), 288

ELSE, 251, 257, 352                                             FIB(), 289, 404, 487

ELSE IF, 251, 257                                               FILEEVENT$, 290, 655

ENCLOSE$(), 223, 252                                            FILESELECT, 291, 389, 666, 669

ENCRYPT$(), 224, 253, 578                                       FILL, 292

END, 255, 504, 599                                              FIT, 293, 294, 295

ENDFUNCTION, 256, 258, 315, 528                                 FIT.LINEAR, 293, 294, 295

ENDIF, 251, 257, 352                                            FIT.POLY, 293, 294, 295

ENDPROCEDURE, 258                                               FIX(), 296, 297, 365, 541, 628

ENDSELECT, 181, 259, 556                                        FLOOR(), 297, 541, 628

ENV$(), 239, 260, 562                                           FLUSH, 298

EOF(), 261, 520, 554                                            FOR, 242, 280, 299, 438

EQV, 262, 354                                                   FORK(), 300, 472, 591

ERASE, 237, 263                                                 FORM INPUT AS, 362

ERR, 264, 265, 266                                              FORM.ALERT(), 138, 301

ERR$(), 264, 265                                                FORM.CENTER(), 302

ERROR, 264, 266, 455, 527                                       FORM.DIAL(), 303

EVAL, 267, 268                                                  FORM.DO(), 305, 544

EVAL(), 267, 267                                                FRAC(), 190, 296, 306, 365, 628

EVEN(), 269, 452                                                framebuoeer, 9

EVENT, 270, 272, 375, 426                                       FREE, 307, 516

EVENT?(), 271, 272, 375, 426                                    FREE(), 406

EVERY, 136, 273, 328, 465                                       FREEFILE(), 308

example programs, 17                                            FSEL.INPUT(), 291

EXEC, 177, 178, 275, 277                                        FSFIRST$(), 309, 312

EXEC(), 276, 276                                                FSNEXT$(), 311, 312

EXIST(), 278, 359, 423, 440, 457                                FULLW, 313

EXIT, 279, 280                                                  FUNCTION,  227,  256,  314,  495,  528,

EXIT  IF,  167,  241,  279,  280,  329,  398,                             646

           523

EXP(), 209, 281, 282, 395, 397, 471                             GAMMA(), 284, 317, 383

EXPM1(), 282                                                    GASDEV, 508, 509, 511
                                                                GASDEV(), 318, 536

FACT(), 202, 284, 647                                           GCD(), 319, 378, 439

FALSE, 141, 142, 262, 285, 354, 627                             GET, 207, 304, 320, 478, 500, 566

FATAL, 286, 455                                                 GET.COLOR(), 321

FFT, 287, 288                                                   GET.GEOMETRY, 165, 322, 325



                                                            697




INDEX______________________________________________________________________________________________________________INDEX___________*
 *___



GET.LOCATION, 323                                                INLINE$(), 358

GET.SCREENSIZE, 325                                              INODE(), 359, 423, 440

GFA-Basic, 27                                                    INP(), 357, 360, 361, 363, 462

gfalist, 27                                                      INP?(), 272, 361

GLOB(), 326, 364, 408, 519                                       INP%(), 360

GOLOR.RGB(), 340                                                 INP&(), 360

GOSUB, 227, 329, 453, 455, 495, 528,                             INPUT, 162, 362, 363, 385, 457

            651                                                  INPUT$(), 162, 360, 363, 386

GOSUB ABBREV. , 328                                              INSTR(), 327, 364, 408, 519, 524, 532,

GOTO, 328, 329, 453, 454, 527                                              613

GPIO, 332, 335                                                   INT(), 183, 190, 296, 297, 306, 365, 541

GPIO(), 333, 334, 335, 561                                       INV(), 235, 366, 584

GPIO?, 333, 334                                                  INVERT(), 367, 484

GPIO.SET, 334                                                    IOCTL(), 368

GPRINT, 152, 330, 340, 490, 491

GPS, 324, 335, 336, 337~339, 559~561                             JULDATE$(), 372, 373

GPS?, 334, 336, 337                                              JULIAN(), 372, 373

GPS.ALT, 324, 336~338, 338, 339
                                                                 KEYEVENT, 271, 272, 357, 375, 426
GPS.LAT, 324, 336~338, 338, 339
                                                                 KILL, 376, 522
GPS.LON, 324, 336~338, 339

GRAPHMODE, 207, 340, 502                                         LCM(), 319, 378

GRAY(), 341                                                      LEFT$(), 379, 417, 530

                                                                 LEFTOF$(), 380
HASH$(), 210, 211, 343, 578

HELP, 246, 345                                                   LEN(), 210, 381

HEX$(), 161, 346, 451, 507                                       LET, 382, 607

HIDEK, 347, 574                                                  LGAMMA(), 317, 383

HIDEM, 231, 348, 575                                             LINE, 199, 214, 229, 245, 384, 476, 482,

HOME, 349                                                                  551

HYPOT(), 350                                                     LINEINPUT, 362, 385, 386, 457
                                                                 LINEINPUT$(), 385

IDE, 13                                                          LINK, 195, 387, 609, 636

IF, 139, 251, 257, 280, 352, 556                                 Linux, 10

IMAG(), 143, 204, 353, 515                                       LIST, 246, 388, 475

IMP, 262, 354                                                    LISTSELECT(), 389

INC, 222, 355                                                    LN(), 281, 395, 397

INFOW, 356, 620                                                  LOAD, 16, 184, 249, 390, 414, 545, 547,

INKEY$, 357                                                                666



                                                            698




INDEX______________________________________________________________________________________________________________INDEX____



LOC(), 391, 394, 520, 554                                       MOD(), 421, 421

LOCAL, 315, 392, 495                                            MODE(), 422, 440

LOCATE, 152, 393                                                MOTIONEVENT, 271, 272, 424

LOF(), 391, 394, 457, 520, 554, 581                             MOUSE, 424, 425, 426, 428, 565

LOG(), 281, 395, 396, 397                                       MOUSEEVENT, 271, 272, 375, 424, 426,

LOG10(), 395                                                              428

LOG1P(), 282, 397                                               MOUSEK, 424~426, 427

LOGB(), 281, 396                                                MOUSES, 427

LOOP, 241, 398, 523                                             MOUSEX, 424~426, 427

LOWER$(), 399, 632, 639                                         MOUSEY, 424~426, 427

LPEEK(), 243, 244, 400                                          MOVEW, 313, 325, 429, 459, 582, 621

LPOKE, 401, 480                                                 MSHRINK(), 430

LTEXT, 232, 402, 403                                            MSYNC, 431

LTEXTLEN(), 402, 403                                            MTFD$(), 432, 433

LUCNUM(), 289, 404, 487                                         MTFE$(), 203, 432, 433
                                                                MUL, 133, 240, 434, 434, 602

MALLOC(), 162, 307, 406, 416, 430, 516                          MUL(), 134, 240, 434, 434

MAP, 431, 637

MATCH(), 327, 364, 407, 519                                     NAND, 139, 436, 442, 444, 460, 667

MAX(), 409, 418                                                 NEW, 192, 437
                                                                NEXT, 242, 299, 438
MENU, 410, 411, 413
                                                                NEXTPRIME(), 439
MENUDEF, 410, 411, 412
                                                                NLINK(), 440
MENUKILL, 411, 412
                                                                NOOP, 441
MENUSET, 411, 413
                                                                NOP, 441
MERGE, 184, 390, 414
                                                                NOR, 436, 442, 444, 460
MFREE, 416
                                                                NOROOTWINDOW, 443
MFREE(), 406
                                                                NOT, 139, 262, 354, 436, 442, 444, 460,
MID$(), 379, 380, 417, 530, 531
                                                                          667
MIN(), 409, 418

MKA$(), 215, 420                                                OBJ.DRAW(), 544

MKD$(), 216, 420                                                OBJC.ADD, 446, 447

MKDIR, 185, 419, 535                                            OBJC.DELETE, 446, 446

MKF$(), 216, 420                                                OBJC.DRAW(), 302, 305, 448, 449

MKI$(), 217, 243, 420                                           OBJC.FIND(), 448, 449, 450

MKL$(), 218, 420                                                OBJC.OFFSET(), 450

MKS$(), 218, 420                                                OCT$(), 161, 346, 451, 507

MOD, 421, 421                                                   ODD(), 269, 452



                                                            699




INDEX______________________________________________________________________________________________________________INDEX___________*
 *___



ON * GOSUB, 453                                                  POWM(), 484

ON * GOTO, 453                                                   PRBOX, 485, 513

ON BREAK, 454                                                    PRED(), 486, 606

ON ERROR, 454, 454, 527                                          PRG$(), 388, 488

ON ERROR GOSUB, 266                                              PRIMORIAL(), 404, 487

OPEN,  187,  195,  205,  261,  278,  308,                        PRINT,  152,  198,  298,  331,  362,  457,

            363, 370, 376, 456, 472, 517, 522,                             462, 489

            558, 622                                             PRINT  AT(),  201,  212,  349,  393,  489,

OPENW, 313, 429, 459, 582, 620, 640                                        490, 542

Operator: =, 607                                                 PRINT COLOR(), 489, 491

OR, 139, 442, 444, 460, 461, 667                                 PRINT SPC(), 489

OR(), 140, 461, 668                                              PRINT TAB(), 489

OUT, 360, 462, 501                                               PRINT TAB() SPC(), 491

OUT?(), 558                                                      PRINT USING, 493, 600, 642
                                                                 PROCEDURE, 315, 328, 494, 528, 646

PARAM$(), 464                                                    PROGRAM, 496

PAUSE, 234, 465, 588                                             PTST(), 497

PBOX, 164, 165, 226, 466, 485, 513                               PUBLISH, 168, 498, 605

PC, 467, 488, 589, 623                                           PUT, 207, 304, 320, 477, 499, 502, 566

PCIRCLE, 164, 191, 468, 470                                      PUT.BITMAP, 358, 500, 502, 595

PEEK(),  163,  243,  244,  400,  401,  469,                      PUTBACK, 501

            480, 648, 649
                                                                 QUIT, 255, 279, 504, 599
PELLIPSE, 250, 470

PI, 142, 471                                                     RAD(), 233, 506

PIPE, 472                                                        RADIX$(), 161, 346, 451, 507

PLAYSOUND, 473, 474, 588, 593, 657                               RAND(), 508, 597

PLAYSOUNDFILE, 474                                               RANDOM(), 509, 510, 536, 597

PLIST, 246, 388, 475                                             RANDOMIZE, 508, 509, 511, 512, 536,

PLOT, 245, 384, 476, 479, 497                                              597

PNGDECODE$(), 477, 478, 500                                      RBOX, 466, 513

PNGENCODE$(), 477, 478                                           READ, 220, 514, 525

POINT(), 476, 479, 497                                           REAL(), 143, 204, 353, 515

POKE,  163,  244,  400,  401,  469,  480,                        REALLOC, 516

            648, 649                                             REALLOC(), 406, 430

POLYFILL, 481, 482, 483                                          RECEIVE, 205, 517, 558

POLYLINE, 214, 481, 482, 483, 551                                REGEXP(), 327, 364, 408, 518

POLYMARK, 230, 481, 482, 483                                     RELSEEK, 520, 554



                                                            700




INDEX______________________________________________________________________________________________________________INDEX____



REM, 496                                                        SENSOR, 335~337, 559, 560, 561

REM ABBREV. ', 521                                              SENSOR(), 559, 560, 561

RENAME, 522                                                     SENSOR?, 334, 335, 559, 560, 561

REPEAT, 280, 523, 638                                           SETENV, 260, 562

REPLACE$(), 524, 624, 670                                       SETFONT, 331, 563, 617

RESTORE, 220, 514, 525                                          SETMOUSE, 428, 565

RESUME, 286, 455, 526, 528                                      SGET, 304, 320, 478, 549, 566, 595

RETURN, 256, 258, 279, 315, 328, 495,                           SGN(), 128, 567

           528                                                  SHELL, 276, 568

REVERSE$(), 529                                                 shell, 10

RIGHT$(), 379, 417, 530                                         SHL(), 537, 569, 577

RIGHTOF$(), 380, 531, 531                                       SHM.ATTACH(), 570, 571, 573

RINSTR(), 327, 364, 408, 519, 532                               SHM.DETACH, 570, 571

RLD$(), 533, 534                                                SHM.FREE, 570, 572, 573

RLE$(), 203, 533, 534                                           SHM.MALLOC(), 570~572, 573

RMDIR, 185, 376, 419, 535                                       SHOWK, 347, 574

RND(),  318,  508,  509,  511,  512,  536,                      SHOWM, 231, 348, 575

           597                                                  SHOWPAGE, 322, 576, 653

ROL(), 537, 540, 577                                            SHR(), 540, 569, 577

ROOT(), 539                                                     SIGN$(), 578, 652

ROOTWINDOW, 443, 459, 538, 640                                  SIN(), 150, 208, 317, 383, 471, 579, 580,

ROR(), 537, 540, 577                                                      614, 615

ROUND(), 190, 296, 306, 365, 541                                SINH(), 151, 580

ROWS, 152, 201, 490, 491, 542                                   SIZE(), 581

RPM, 5                                                          SIZEW, 313, 429, 459, 582

RSRC.FREE, 543, 544                                             SOLVE, 295

RSRC.LOAD, 543, 544                                             SOLVE(), 235, 366, 583

RUN, 184, 545, 669                                              SORT, 585

                                                                SOUND, 159, 473, 474, 587, 657

SAVE, 249, 547                                                  SP, 467, 589

SAVESCREEN, 548, 549                                            SPACE$(), 590, 601

SAVEWINDOW, 548, 549, 566                                       SPAWN, 300, 328, 591

SCOPE, 550                                                      SPC(), 152

SCREEN, 552                                                     SPEAK, 592

SEEK, 457, 520, 554                                             SPLIT, 327, 594, 662~664

SELECT, 181, 206, 225, 259, 555                                 SPUT, 304, 566, 595

SEND, 205, 517, 557                                             SQR(), 596



                                                            701




INDEX______________________________________________________________________________________________________________INDEX___________*
 *___



SQRT(), 182, 350, 539, 596                                       TRUE, 141, 142, 262, 285, 354, 627

SRAND(), 597                                                     TRUNC(), 190, 296, 306, 365, 541, 628

STEP, 242, 299                                                   TT?, 660

STIMER, 213, 598, 619                                            TYP?(), 629

STOP, 206, 255, 545, 599

STR$(), 346, 451, 493, 600, 642, 644                             UBOUND(), 148, 631

STRING$(), 590, 601                                              UCASE$(), 632, 639

SUB, 133, 240, 434, 602, 603                                     UNCOMPRESS$(), 203, 633

SUB(), 134, 240, 434, 602                                        UNIX, 10

SUBSCRIBE, 168, 498, 604                                         UNIX?, 141, 634, 660

SUCC(), 606                                                      UNIXDATE$(), 619, 635

Support, 9                                                       UNIXTIME$(), 618, 619, 635

SWAP, 607                                                        UNLINK, 387, 609, 636

SWAP(), 174, 180, 607, 661                                       UNMAP, 431, 637

SYM.ADR(), 387, 609                                              UNTIL, 523, 638

syntax highlighting, 20                                          UPPER$(), 399, 529, 632, 639, 670

SYSTEM, 276, 568, 610, 611                                       USEWINDOW, 459, 538, 640
                                                                 USING$(), 493, 600, 641
SYSTEM$(), 277, 610, 610

                                                                 VAL(), 600, 644, 645
TAB(), 152
                                                                 VAL?(), 644, 644
TALLY(), 613                                                     VAR, 130, 328, 646

TAN(), 579, 614, 615                                             VARIAT(), 202, 284, 647

TANH(), 614, 615                                                 VARLEN(), 648, 649

TERMINALNAME$, 616                                               VARPTR(), 130, 148, 648, 649

TERMINALNAME$(), 616                                             VERSION, 650

TEXT, 232, 331, 340, 402, 564, 617                               VGA-Version of X11-Basic, 553

TIME$, 221, 618, 619, 635                                        VOID ABBREV.  , 651

TIMER, 213, 512, 598, 618, 619, 635                              VRFY(), 578, 652

TITLEW, 356, 429, 459, 620                                       VSYNC, 576, 653

TO, 242                                                          VT100, 14

TOPW, 313, 621

TOUCH, 622                                                       WATCH, 290, 655

TRACE, 488                                                       WAVE, 588, 593, 656

TRACE$, 488, 623                                                 WEND, 658, 659

TRIM$(), 529, 624, 670                                           WHILE, 241, 280, 523, 658, 659

TROFF, 248, 623, 625, 626                                        WIN32?, 141, 634, 660

TRON, 248, 488, 623, 625, 626                                    WORD(), 174, 180, 608, 661



                                                            702




INDEX______________________________________________________________________________________________________________INDEX____



WORD$(), 594, 662

WORT.SEP, 138, 524, 594, 663

WORT.SEP(), 662, 663, 664


xb2c, 22

xbbc, 22, 24

xbc, 25

xbvm, 22

XLOAD, 291, 390, 666, 669

XOR, 139, 262, 354, 442, 460, 667, 668

XOR(), 668

XRUN, 291, 666, 669

XTRIM$(), 624, 670



                                                            703




INDEX______________________________________________________________________________________________________________INDEX___________*
 *___



                                                            704




Thanks to all people, who helped me to realize this package.

     Many thanks to the developers of GFA-Basic.  This basic made me start pro-

gramming in the 1980s.  Many ideas and most of the command syntax has been
X11-BasicAcknowledgements
taken from the ATARI ST implementation.

     Thanks to sourceforge.net for hosting this project on the web.

     I would like to thank every people who help me out with source code, patches,

program  examples,  bug  tracking,  help  and  documentation  writing,  onancial  sup-

port, judicious remarks, and so on...

     And here thanks to people, who helped me recently:

     in 2012: * Marcos Cruz (beta testing and bug oxing) * Bernhard Rosenkraenzer

(send me a patch for 64bit version)

     in 2013: * Matthias Vogl (va.copy patch for 64bit version) * Eckhard Kruse (for

permission to include ballerburg.bas in the samples) * Stewart C. Russell (helped

me ox some compilation bugs on Raspberry PI) * Marcos Cruz (beta testing and

bug oxing) * James V. Fields (beta testing and correcting the manual)

     in 2014:  * John Clemens, Slawomir Donocik, Izidor Cicnapuz, Christian Amler,

Marcos  Cruz,  Charles  Rayer,  Bill  Hoyt,  and  John  Sheales  (beta  testing  and  bug

oxing), Nic Warne and Duncan Roe for helpful patches for the linux target.

     in 2015:

     * Guillaume Tello, Wanderer, and John Sheales (beta testing and bug oxing)

     in 2016:  * John Sheales (beta testing and bug oxing) * bruno xxx (helping with

the compilation tutorial for Android)

     in 2017: * John Sheales (beta testing and bug oxing) * David Hall (bug oxing) *

Emil Schweikerdt (bug oxing)

     in 2018: * Alan (beta testing, bugox) * John Sheales (beta testing and bug oxing)

     in 2019: * Yet Another Troll (beta testing and bug oxing)

     X11-Basic is build on top of many free softwares,  and could not exist without

them.

     X11-Basic uses the Fast discrete Fourier and cosine transforms and inverses by

Monty !xiphmont@mit.edu? released to the public domain from THE OggSQUISH

SOFTWARE CODEC.

     X11-Basic  uses  functionallity  of  the  gmp  library,  the  GNU  multiple  precision

arithmetic library, Version 5.1.3.  Copyright 1991, 1993, 1994, 1995, 1996, 1997,

1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foun-



                                                            705




INDEX______________________________________________________________________________________________________________INDEX___________*
 *___



dation, Inc.

      For details, see: https://gmplib.org/

      X11-Basic also uses functionallity if the LAPACK library. LAPACK (Linear Alge-

bra Package) is a standard software library for numerical linear algebra.

      For details, see: http://www.netlib.org/lapack/

      X11-Basic uses the lodepng code for the PNG bitmap graphics support. Copy-

right (c) 2005-2013 Lode Vandevenne

      X11-Basic uses a md5 algorithm Copyright (c) 2001 by Alexander Peslyak (pub-

lic domain). X11-Basic uses a sha1 algorithm Copyright (C) 2001-2003 Christophe

Devine (GPLv2+)

      So I would like to thank every people involved in the following projects:

      Linux GCC and all of the GNU tools, of course.  The readline library.  The SDL

(Simple  Direct  Media)  library.   Creator  of  the  8x16  font  "spat.a".   The  Burrow-

Wheeler-Transform. And any other libraries used by X11-Basic.

      Some pieces of code of X11-Basic are based on third party software:

      The AES user interface routines are based on OpenGEM. The FloodFill algo-

rithm is based on xxxx.  Pictograms for mousecursers and oll patterns are based

on TOS / ATARI ST. The order-0 adaptive arithmetic decoding function contains the

source code from the 1987 CACM article by Witten, Neal, and Cleary.



                                                            706
4. FAQ frequently asked questions
=================================

Q: How do I leave the interpreter `gently'?
A: type quit or press ctrl-c (twice)

Q: Why do the graphics look funny?
A: Some X-Servers do not clean newly allocated Pixmaps. So rubbish is displayed 
   if the window is maped. Please do a clearw 1 as a first command.

Q: Is there a GUI-Designer for the graphical user unterface functions 
   of X11Basic ?
A: Well, so far nobody has made a real efford to write a real graphical 
   GUI_designer. But the program gui2bas may help creating GUI forms. The input
   is a very siple ASCII-File (*.gui) which defines the interface. So far 
   many GEM object types are supportet (and even Atart ST *.rsc-files may
   be converted to *.gui files with the rsc2gui program.) but support for 
   listboxes, popup-menues and Tooltips may be included in future.

Q: My old ANSI Basic Programs (with line-Numbers) produce lots of errors in the
   interpreter. How can I run classic (ANSI) Basic programs?
A: Classic Basic programs have to be converted before they can be run with 
   X11-Basic. With the bas2x11basic converter program most of this convertion
   will be done automatically. 

F: Kann ich meine alten Atari Programme "einfach" rberziehen oder mssen
   die noch irgendwie ( speziell Gem Programme ) angepasst werden?
A: Die mssen noch angepasst werden. Es gibt kleinere Unterschiede in der
   Syntax, Systemaufrufe (XBIOS,BIOS,VDISYS etc), Inline-Blcke gehen
   natrlich nicht, short int
   Variablen gibt es nicht etc. Also man muss nochmal mit der Hand
   drbergehen. Aber es gibt nichts, was nicht irgendwie auch geht.
   Bei kleinen Programmen (ca. 100 Zeilen) ist es ein Kinderspiel. Bei
   greren (mehere 1000 Zeilen) ist es schon was arbeit. 10000-Zeilen
   Programme habe ich noch nicht portiert. Es lohnt wahrscheinlich nicht.
   Fr Programme, an denen man nichts mehr machen will, empfehle ich dann
   doch lieber STonX oder sowas.

Q: Can I use X11-Basic as a shell ? 
A: Yes, simply copy the xbasic executable to /usr/bin .
   The basic programs then should have in their first line
   #!/usr/bin/xbasic 

Q: Can I use X11-Basic as an internet daemon ? 
A: Yes, start xbasic with the option -daemon .
   This feature is still experimental. So use it on your own risk since this 
   opens several security holes to your system.

Q: Can X11-Basic generate stand-alone programs, which may run 
   without the xbasic executable ?
A: Yes. This is done by the X11-Basic compiler (xbc).
   
Q: May I charge for my X11-Basic programs ?
A: Yes, you may. But you should state clearly, that xbasic itself is available 
   free of charge. Refer to the File COPYING for details.

Q: Where can I get the newest version of X11-Basic? 
A: Probably at 
   http://x11-basic.sourceforge.net/
   Don't bet on it though! :-) 

Q: What can I do to speed up the development of X11-Basic?
A: You can try to bribe me with any amount of money, any type of hardware or
   software (no pirated stuff please). Well cidding...
   A nice postcard might suffice too. :-)
   You can contribute to the official development of X11-Basic on codeberg 
   or github. Please visit the project pages here:
   Android Version:  https://codeberg.org/kollo/X11-Basic
   Example Programs: https://codeberg.org/kollo/X11-Basic_examples
   Main Repository:  https://codeberg.org/kollo/X11Basic
   And on github:    https://github.com/kollokollo/X11Basic

--------------------------------------------------------------------------------


Version history of X11-Basic
============================

In the beginning there were absurd plans, long sleepless nights, and incredible
boredom.

Very First Version (1990)
--------------------------
It was a Mailbox-Program with Basic features (only character-Graphics with
Vt100EMU) on my ATARI ST (!).

Version 0.1 First version with a version number    (1997)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Mailbox-Program was rewritten in c on my Linux-PC
- first X11-Commands

Version 0.2 Alpha (1998)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- improved X11-Basic for use at the physics institute in Bonn
- Fixed last Problems of the Parser (didn't like -1*(4-3) )
- Added more X-features (redraw)
- First portation to a HP-Workstation
- Readline library in use

Version 1.00 Beta (Mar 1999)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Makefile and configure script adapted from STonX
- True-color Displays
- X rootwindow, multiple windows
- INKEY$
- First GPL-Distribution
- FILESELECT,ALERT

Version 1.01 (Jun 1999)
~~~~~~~~~~~~~~~~~~~~~~
- POINT()

Version 1.02 (Jun 2000)
~~~~~~~~~~~~~~~~~~~~~~
- rsrc_load
- shell, daemon

Version 1.03 (Mar 2001)
~~~~~~~~~~~~~~~~~~~~~~~
- copyarea, sget, sput, get,put
- fill-Patterns
- drop down menues
- String-Variables may now contain nul-characters.
- POKE,DPOKE,LPOKE,EVEN(),ODD()
- LINK,UNLINK
- CVI(),CVD(),CVF(),CVL()
- MKI$(),MKD$(),MKL$(),MKF$()
- ON x GOSUB proc1,proc2,...
- ON x GOTO label1,label2,...
- INSTR(),RINSTR()

Version 1.04 (Apr. 2001)
~~~~~~~~~~~~~~~~~~~~~~~~
- splitted off shared library libx11basic.so (300kB)
- bug fixed which caused print a,b to segmentation fault
- DUMP "#"
- SYM_ADR()
- CALL, EXEC, EXEC()  with parameter list
- DUMP "K" DUMP "F"

Version 1.05 (Aug. 2001)
~~~~~~~~~~~~~~~~~~~~~~~~
- PRINT USING
- SYSTEM$()
- GLOB()
- RBOX, PRBOX
- EDIT, SAVE
- HELP
- new system errors
- started to translate everything into english

Version 1.06 (Jan. 2002)
~~~~~~~~~~~~~~~~~~~~~~~~

- included serial device support
- improved FILESELECT
- modified ALERT
- improved COLOR
- FORM_DIAL(), FORM_DO(), OBJC_DRAW()
- GPRINT

Version 1.07 (Aug. 2002)
~~~~~~~~~~~~~~~~~~~~~~~~
- Fehler mit Exponentialdarstellungen von Zahlen mit negativem Exponent
  ist nun endlich behoben !!!
- Anbindung an tine-Bibliothek und Kontrollsystem ist nun moeglich

Version 1.08 (Jan. 2003)
~~~~~~~~~~~~~~~~~~~~~~~~
- Support for tine-library
- a first MS-WINDOWS version is now available
- some new functions
- FIT and FIT_LINEAR
- SORT command
There was a bug introduced in the MENU command. Fixed it in release 1.08-4.

Version 1.09 (June 2003)
~~~~~~~~~~~~~~~~~~~~~~~~
- ANSI-Basic to X11-Basic converter included
- New example programs
- updated man-page and documentation
- new SOUND command
- EVAL, EVAL()
- modified serial line support
- modified the configure procedure
- some modifications for portability
- will now compile on FreeBSD and CYGWIN

Version 1.10 (Feb 2004)
~~~~~~~~~~~~~~~~~~~~~~~~
- new REPLACE$() function 
- improved speed 
- bug fixed in ROUND() function
- fixed bug in PUT_BITMAP
- fixed bug in serial device handling
- added sysvars COLS and ROWS
- new INODE/DEVICE/MODE/NLINK/SIZE file functions

Version 1.11 (Oct 2004)
~~~~~~~~~~~~~~~~~~~~~~~~
- Parser now accepts unique short commands
- fixed little bug in INPUT
- new chapters in manual
- new commands: TOPW, BOTTOMW, INFOW, FULLW, CLIP
- found bug in ON ERROR and ON BREAK
- new FILL command
- changed TAB treatement in sourcecode
- worked on TINE implementation
- worked on the ARRAY functions
- new SHL(), SHR() function

Version 1.12 (Mar 2005)
~~~~~~~~~~~~~~~~~~~~~~~~
- fixed bug with DEFMARK
- experimental LISTSELECT
- worked on MATRIX functions: SOLVE(),INV(),DET()
- OPEN "UU"  UDP-Sockets
- CONNECT, SEND, RECEIVE
- New String Functions: REVERSE$(), MTFE$(), MTFD$(), RLD$(), RLE$()
- CRC()
- New Code Engines: BETE$(), BWTD$(), COMPRESS$()

Version 1.13 (Feb 2006)
~~~~~~~~~~~~~~~~~~~~~~~~
- fixed bug in INPUT$()
- woked in the TINE implementation (TINELISTEN, TINEBROADCAST)
- new MKA$(), CVA()
- fixed bug in PAUSE/DELAY
- implemented ioctl() function

Version 1.14 (Apr 2007)
~~~~~~~~~~~~~~~~~~~~~~~~
- improved the init_program routines
- woked on the bytecode compiler
- new programs xbbc and xbvm  + man pages
- the bytecodecompiler and virtual machine are still full of bugs
- some sample programs can already be compiled to bytecode, 
  they run 4 to 10 times faster 
- Bug fixed which caused "Command  not allowed in interactive mode" errors
  This bug was introduced in Version 1.14 since release 1
- worked on the control system routines (DOOCS)
- fixed bug with fgetc
- crosscompiled it with arm-linux for embedded linux
- new CHDIR command
- new SPAWN command (does still not work as wanted)
- created doocsxbasic modification to use the FLASH control system at DESY


Release notes for Version 1.15 (Feb 2008)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- New command: PIPE
- New commands: GET_SCREENSIZE, GET_GEOMETRY
- Implemented BMP file format (for PUT)
- produced a framebuffer-graphics version of X11-basic


Release notes for Version 1.16 (Feb 2010)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Bugfix in SORT (Feb 2010)
- new function word$() June 2010
- Improved DATA/RESTORE handling Dez 2010
- Improved xbbc/bytecode/xbvm
- Fixed memory leak accuring in varptr()
- added xbbc and xbvm to windows distribution
- started xb2c project
- new psydocompiler for MS-WINDOWS, can produce standalone .exe files 
- Bug fixed: LINEINPUT and LINEINPUT$() now can read arbitrary long lines
- fixed bug with PBOX: now 2nd coordinate is inside the filled area.
- new commands WATCH/(UNWATCH)/FILEEVENT$
- fixed bug with bitmaps (PUT)
- added support for bitmaps with transparency/alpha channel
- fixed bug in DEFFILL
- fixed bug in objc_draw()

Release notes for Version 1.17 (May 2011)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Adapted windows version to use the SDL library (2011-04)
- added PLAYSOUND command (works only in SDL and WINDOWS version) 2011-05
- modifyed syntax of SOUND command 2011-05
- added ALSA sound support for SOUND command. 2011-05
- made syntax a bit more tolerant against extra blanks
- bugfix with BOX (confusion with curses library, segfault)
- worked on the xb2c compiler/translator 2011-08

Release notes for Version 1.18 (Sept 2011)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Reworked variable management
- Reworked xb2c compiler, produced code is now much(!) faster.
- interpreter is now 8% faster
- virtual machine is 20 times faster than interpreter
- compiled code is 30 times faster than interpreter
- improved detection of const expressions.
- improved detection of fieldindex too large (less segfaults now)
- fixed a memory leak
- updated the documentation
- changed DIM behavior: DIM a(10) means elements a(0) to a(9) are there.
- fixed some bugs. 
- New command: CURVE
- Implemented DEFFN
- Optimized Compiler: simple math functions and Square

Release notes for Version 1.19 (Mai 2012)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Android version
- virtual machine now included in library
- new GPS and SENSOR commands (for Android version)
- new SPEAK kommand (for Android version)
- improved framebuffer graphics routines
- new command: PLAYSOUNDFILE (for Android version)
- new command: GET_LOCATION
- BUGFIX: SOUND, WAVE, AND(), OR(), XOR(), NOT()
- BUGFIX: FOR with integer variable
- BUGFIX: SELECT CASE ENDSELECT
- NEW: "!" is now allowed at the beginning of a line
- BUGFIX: SELECT/CONTINUE
- some minor changes for 64bit version

Release notes for Version 1.20 (Dez 2012-Mar 2013)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- New command: SHELL (also for Android)
- bugfix: strcpy().
- Improved: Editor execution in Android version
- Fixed bug with desktop shortcuts under Android
- Bugfix in virtual machine (AND)
- included va_copy patch for 64 bit version by Matthias Vogl
- fixed bugs in compiler (ARRAY constants)
- fixed bugs in VARPTR() and ARRPTR()
- fixed bug in local variable handling
- fixed memory leak LOCAL/RETURN
- fixed bug/crash with MERGE
- new function: call android intents with EXEC
- fixed bug/crash in LIST command 
- fixed bug in SWAP command
- fixed bug/crash in CALL command 
- new commands: MKDIR, RMDIR, KILL, HIDEM, SHOWM
- new functions: LEFTOF$(), RIGHTOF$(), ENCLOSE$(), DECLOSE$(), TALLY()
- new functions: COLOR_RGB(), BYTE(), CARD(), WORD(), SWAP(), CINT(), VARIAT()
- new commands: RENAME, CHMOD, TOUCH


Release notes for Version 1.21 (Apr 2013-Nov 2013)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- fixed bug in GET_SCREENSIZE (Windows version)
- new: support for Android x86 platform
- new: (legal) FFT algorithm now included (by Paul N. Swarztrauber, public domain)
- new: using LAPACK for INV() and SOLVE() (linux only)
- removed support for numerical recipes routines
- new: FIT_POLY
- fixed bugs in SPUT, LOCATE, PRINT USING
- new function USING$()
- fixed memory leak with STRING variable assignment
- fixed bug in INPUT (Android version only, locate)
- fixed bug in RUN (close files)
- fixed bug in bytecode compiler (STEP -#)
- improved speed of string parser
- fixed small problem with LOAD (last line without EOL)
- fixed typos in the manual and offline help
- fixed screen rotation bug (Android)
- fixed bug in PUT scale (Android)
- fixed bugs in GET and PUT (Windows version)
- fixed bug in SPLIT
- fixed bug in GPS functions (Android)
- new function EVENT?()
- improved LINEINPUT
- fixed bug in Array const
- fixed bug in compiler (array operations)
- fixed bug in ELLIPSE, PELLIPE, RBOX and PRBOX (Android Version)

Release notes for Version 1.22 (Dec 2013-June 2014)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- improved crash reports (Android)
- Bugfix ARRAY (create, init)
- new: ABSOLUTE command
- new: VAR statement allows parameters "by reference"
- added UTF-8 (unicode) support for LTEXT
- added UTF-8 (unicode) support for console/terminal (Android)
- added unicode bitmap font for greek/kyrillic for console/terminal (Android)
- MENUDEF now compiles without error
- AFTER/EVERY works in bytecode now
- new functions: FSFIRST$(), FSNEXT$()
- new example program: stepdir.bas
- fixed bug in MOUSEK, MOUSE (Windows version)
- small bugfixes in CASE,PAUSE,INSTR(), SORT, USING$(), PRINT USING
- fixed bug in VAL?(), DET(), and GPRINT
- fixed bug in ON ERROR, ON BREAK and ON MENU
- fixed bug in String compare
- fixed bug in HEX constants "0x" (Android)
- new string function RADIX$()
- fixed bug in framebuffer version (linux) 
- fixed bugs in parser
- new statement: ENDPROCEDURE (optional)
- improved speed of bytecode
- bugfix in compiler, improved error messages
- fixed bug in DIM, VAL?(), PLIST

Release notes for Version 1.23 (July 2014 -- August 2015)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- New data type: complex numbers a#
- New data type: arbitrary precision integers a& (experimental)
- LAPACK functions (e.g. SOLVE(), INVERT() etc.) now work in Android version
- New functions LCM() and GCD()
- fixed bugs in compiler (PRINT)
- fixed bug in MID$()
- compiled an ATARI ST (MINT) version of X11-Basic
- Fixed bug in LOAD / Screen rotation
- Again modified MID$
- Crashfix: clear_variable
- Fixed unavail basedir in Android
- fixed bug in EVAL, HELP, RND(), SGET, GET, PLIST, RSRC_LOAD, OBJC_DRAW()
- increased speed of assignment in interpreter
- workaround for TTS crash (Android)
- new functions UBOUND() and DIR$()
- further crashfixes (bytecode)
- fixed bugs in WINDOWS version (RSRC_LOAD)
- improved GPRINT COLOR(), ALERT
- fixed bugs in bytecode compiler MIN(), MAX() and PRINT
- fixed bugs in BIN$(), OCT$(), HEX$(), RADIX$()
- new functions ROR() and ROL()
- improved EVENT and EVENT?() (Windows)
- SGET/GET/SAVEWINDOW/SAVESCREEN now produce BMP data also in UNIX/LINUX
- new functions PNGENCODE$() and PNGDECODE$()
- fixed bug in FREEFILE()
- fixed memory leak in virtual machine (less crashes now!)
- fixed bug in SIZEW (linux) introduced in V.1.23
- made tolerant for CRLF (DOS mode) .bas files
- added View Docu function in context menu (WINDOWS)
- added source box to PUT
- fixed SPEAK (Android)
- fixed crash (Android) on load while program is still running

Release notes for Version 1.24 (Sept 2015 -- Aug 2016)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- added source box to PUT
- fixed SPEAK (Android)
- fixed crash (Android) on load while program is still running
- Improved USB-Support (linux+WINDOWS)
- New Setup for WINDOWS version (by InnoSetup)
- Added spanish voice in SPEAK (Android)
- new feature: screen focus for Android
- fixed INKEY$ and INP(-2) (Windows)
- fixed PUT_BITMAP (Android + Windows)
- fixed bug in PUT (Android)
- added sqlite3 binary to Android Version (make sqldemo.bas work again)
- added gfalist binary to Android Version (see gfalist.bas)
- fixed subarry assignment
- improved DUMP, added DUMP c$,#n, also PLIST #n
- fixed Crash (SIGABRT) in Android version.
- fixed Crashhandler (Android)
- fixed bug in RADIX() and fixed bug in arbint/arbfloat evaluation
- fixed bug in FILL and ELLIPSE/PELLIPSE (for big screens)
- fixed power operator in compiler for integer operands
- little bugfix in compiler (PRINT #)
- improved FILESELECT
- little fixes in GLOB()
- improved the MAC-OSX version of X11-Basic
- improved 64bit version of X11-Basic
- fixed bug in CLEARW
- fixed missing pixel in BOX/HLINE (framebuffer versions)
- fixed bug in HELP

Release notes for Version 1.25 (Sept 2016 -- June 2018)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- HASH()/SHA1 and MD5 now work also without libgcrypt
- new Commands: HIDEK, SHOWK (Android)
- fixed bug in MERGE and FILESELECT
- new function VRFY()
- added raw keyboard support for framebuffer version (e.g. Raspberry pi + sense hat)
- fixed bug in EXIT (bytecode)
- added bluetooth support (linux)
- improved USB functions (linux)
- make use of fftw library when available
- improved memory handling in 64bit versions
- new parameter list types for CALL
- new functions CALLD() and CALL$()
- fixed Bug in XLOAD and TOUCH (Android)
- created a german version of the user manual (asciidoc,html)
- fixed bug with PBOX (Android)
- fixed bug with UNIXDATE$() and UNIXTIME$() on 64 bit

Release notes for Version 1.26 (June 2018 -- June 2019)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- New functions/commands GPIO (Raspberry)
- fixed bug in virtual-machine/compiler (RasPi, signed char)
- new shortcut compiler start ybasic
- fbxbasic included 
- added broadcast permission for UDP sockets
- new syntax highlighting file for nano/pico
- new commandline function --quitonend
- bugfix in FOR (compiler) and better error handling

--------------------------------------------------------------------------------
Release notes for Version 1.26 (June 2018 -- June 2019)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- New functions/commands GPIO (Raspberry)
- fixed bug in virtual-machine/compiler (RasPi, signed char)
- new shortcut compiler start ybasic
- fbxbasic included 
- added broadcast permission for UDP sockets
- new syntax highlighting file for nano/pico
- new commandline function --quitonend
- bugfix in FOR (compiler) and better error handling

Release notes for Version 1.27 (June 2019 -- 2020)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- removed VERSION and VERSION_DATE from library
- new function REGEXP() and MATCH()
- little fix for HELP, REM and DATA
- New feature: ANS variable (store result of simple calculation)
- New function VARLEN() 
- New function CRC16() 
- New mqtt commands BROKER, SUBSCRIBE, PUBLISH
          Last change to this file:  Mi 18. Nov 15:17:59 CET 2020
