GNU-APL - It Seems to Work Well! - For production-grade data-bashing, we use an old Manugisitcs APL - but an associate mentioned he was using GNU-APL, and it has the advantage of crazy-large workspaces (ie. measured in gigabytes) and also uses SQL-Lite as the back-end database.   This fellow is capturing all daily trading from a particular exchange, and this results in roughly 1 gigabyte of data each day - and so running an SQL query might generate a 100,000 row table, with a fair bit of data for each row.

So, I was intrigued by this, and found and downloaded the GNU-APL last night, and compiled it and got it running on one of the CentOS-7 boxes.  

The current details about GNU-APL should be here:

https://www.gnu.org//software/apl/

Damn thing seems to work pretty good.  I had to hack around with the keyboard stuff for a while, as the first configuration I tried - using Linux "xmodmap" to configure the ALT-whatever key to create the APL characters, caused the loss of all the ALT-function features needed to control the XTERM Linux sessions - and even switch contexts between X-Windows in GNOME (and this managed to blow up the Firefox session, and wipe out a bunch of webpage sessions, of course).

To use "Xmodmap", you can just run:

         xmodmap ./support-files/old-Keyboard/apl.xmodmap

But maybe don't use this.  The loss of "Alt-TAB" (to switch between Xterm window sessions in Gnome) is lethal to Firefox, and will also prevent ALT-F1, ALT-F2 ... etc. from switching between sessions outside of GNOME.  So this approach (which works fine for generating APL characters in Xterm) is no good.  (Note! On older Fedora boxes, I have to use this method.)

But what does work, is this trick (on the latest CentOS Linux boxes:)

        xkbcomp ./support-files/old-Keyboard/apl.xkb :0 -w 0

and this works great. (The ":0" is your X-session, "-w 0"  means suppress warnings.)  On my Fedora/CentOS-7 Linux box, it sets up ONLY the right-side ALT key on the keyboard, to be the ALT key for generating APL characters.  The left-side ALT key still works as it is supposed to, so that ALT-TAB can switch between running Windows in GNOME.  

Using the right-side ALT key, allows APL chars to be generated and displayed correctly.  For example,  ALT(right)-R creates the "rho" character, ALT(right)-i creates the "iota", and ALT(right)-[ will create the left-arrow for APL assignment operator, ALT(right)-] is the right-arrow, for APL branching, etc.  This is the same as the ALT-xx operation of the various GEMESYS APL apps on Android (using the Android "Hacker's Keyboard"), and yet it still allow the ALT(left-side) key to operate as is required by Xterm and GNOME and Linux.  (eg: ALT-CTRL-F7 lets you jump right out of GNOME/X-windows into regular command-line Linux sessions, and ALT-<Fsession#> lets you jump back into Xwindows/GNOME session.  ALT(leftside)-TAB is needed to just switch between Windows - and restore minimized Xwindows/GNOME sessions.)

The GNU-APL has several other methods of creating the APL keyboard, which I have not tried yet.  But the method described here is quite satisfactory, and lets all the APL characters be displayed correctly..

Also, to start APL, in a normal, standard APL interactive workspace session, you run "apl" with the option "--noColor", which makes the interactive APL session behave in a sane way, like any standard interactive APL.

Eg:  - To start GNU-APL after it has been installed:

                 [Your-System-Prompt-in-Xterm-Window]$ apl --noColor

and you will get a working APL with a big workspace (up to gigabytes, it looks like, if you need this much...).  On my CentOS-7 box, if you start without "--noColor" option, you get an awful video mess, and cannot even see the APL interpreter results.   Just enter ")off" to exit APL, an then enter "reset" and to fix your borked X-term session (it might be blank, no video chars visible!), and the virtual terminal will reset correctly.  But if you enter "--noColor", it works fine.  Note there are "two" dashes for this critical parameter, not one.

How to Install GNU-APL:

    [ I am running an old gcc (GCC) 4.8.5 20150623 (Red-Hat 4.8.5-28) with all the associated  development utilities need to build anything now on Linux... ]  So, to build GNU-APL:

      - download the APL-1.7 gunzipped tarball from the GNU-APL ftp site.  Note that this can be seriously slow  sometimes:

         Download apl-1.7.tar.gz from site:  https://ftp.nluug.nl/pub/gnu/apl/

         Create directory in /home     (ie.  become root, cd /home, mkdir gnuapl, cd gnuapl)

         cp /home//Downloads/apl-1.7.tar.gz .     (copy file to build directory)

         gunzip apl-1.7.tar.gz    (create .tar file, ie. removes the .gz compression)

         tar -xvf      (untar the package)

         cd apl-1.7    (connect to build directory where you will compile source)

         ./configure   (if running a modern Linux, this should just work, and setup build defaults)

         make           ( run the Makefile to do the compile of the c++ source)

           (Check the apl executable...    cd src,  ./apl  --noColor   (to run the GNU APL)

                (Try something like 234+3, press return, and confirm you see: 237 as the response)

                (If the exectuable runs ok, you may as well just install it and experiment with it...)

         make install    ( if the compile ran without errors, you can just install the apl executable)

For now, I am running the APL-1.7.   I will try the 1.8 version tonite on a different machine and see if it works.  My associate who has been working on this says that the 1.7 (circa 2017) is very stable, but he could not get APL 1.8 to run without getting segfaults.

Initial experiments with the GNU APL 1.7 look quite promising.  Very promising, actually.

Coda:  How to check the GNU APL signature file (or any GNU project Signature)

   1) ensure you have gpg on your machine.  If a modern Linux (ie. since 2008!) it should be there.

   2) Assume you put the files APL source and .sig files in /home//Downloads

       cd /home//Downloads

       Go to your broweser, and download the keyring signature file for GNU projects.  Just cllck this link:...

             https://ftp.gnu.org/gnu/gnu-keyring.gpg

      This gets the file gnu-keyring.gpg file into Downloads directory.  Run a gpg with --verify to check that the .sig file matches what was signed on the .tar.gz file:

        gpg --verify --keyring ./gnu-keyring.gpg  apl-1.7.tar.gz.sig  apl-1.7.tar.gz

     This command says "Look in gnu-keyring.gpg to confirm the .sig is a real sig file, and verify that the apl-1.7.tar.gz file was signed with this signature.  You should get a "Good Signature from..." response, in this case: "Jurgen Sauermann (Programmer) <juergen.sauermann@t-online.de>".  Note that you also get a WARNING saying there is no certainty that this key is actually a trusted key (you have to fiddle with GPG stuff more to get a "web-of-trust" thing setup, and that is another thing..)

   Also, you can run the MD5 hash against the apl-1.7.tar.gz file, and I get this value, when I run it against mine:

      gpg --print-md md5 apl-1.7.tar.gz

      (should respond with:)

       A0 64 56 F4 AA 9E 34 97   00 DA 51 C8 EF D1 41 50

   (BLah blah blah - MD5 is not the most secure message digest - blah blah blah blah.)

    and for MD5 hash check (message digest check) for "apl-1.8.tar,gz",

      gpg  --print-md md5 apl-1.8.tar.gz

      B1 8E 71 FF 2D 30 7C F2    26 80 67 DE ED 50 26 EC

   I like MD5 becuase it is simple and fast and is better than no security at all, guys.

And this GNU-APL seems to work good.  

Update: To get the APL Libraries in wslib3, wslib4 and wslib5 to be visible to the interpreter, I had to create a local "preferences" file in ~/.gnu-apl directory, and remove the references that are in the default build-preferences file (see build-directory "gnu-apl.d" for the standard default preferences file, and just copy it to your local .gnu-apl directory).  Replace the @GNU_APL_LIBS@ strings in each of the LIBREF-n statemetns with "." to point to your local directory, and then create local directory copies of each of the subdirs wslib3, wslib4, wslib5 that are in the GNU-AP build directory.

Just cd to build directory (in my case, I used:  /home/gnuapl), and then copy the directories for each of the APL libraries to your local user directory:

      cd  /home/gnuapl      (connect to your build directory...)

      cp ./wslib3  /home//  -v  -R       (make local copies of each of the APL Library directories, 3, 4 and 5. ) 

Then, when you start GNU-APL, and enter ")libs" you should see that your three APL Libraries show up a "present" instead of "missing",

 

GNU-APL - Latest SVN Version

Note:  It is a good idea to install the latest SVN version.  You need to install (or already have, like most Linux installations do), the SVN code version management tool.

If SVN is installed on your local machine, you can get all the code with this command below.  Just create a new directory (I used "mkdir /home/gnuapl" to create a directory under the "/home" top level Linux directory.)  Then, "cd /home/gnuapl", and with that as your default directory, just run this:

svn co http://svn.savannah.gnu.org/svn/apl/trunk

and that above command will create a directory "trunk" with the very latest GNU-APL code in it, and you can just "cd trunk" and try the "./configure".  If it runs ok, run "make", and if that works, you can just run: "make install", as described above.

If there are errors or problems you will have to resolve them.

Good luck!

 

Decided I had to get the GNU-APL working with the latest SVN version.   First got it working right on the Linux boxes, and then on the MacBook.  The Linux boxes were easier, as the trick was to run the ./configure with a "--without-gtk3" option, which disabled the buggy Gtk-3 graphics stuff, and tells GNU-APL to use the "xcb" / X11 library routines for charting purposes.   Linux was easly, Apple Macbook was more difficult  (big surprise - not)...  

But after some extensive hacking around, I finally got the GNU-APL 1.8a to build - WITH THE ⎕PLOT Graphics CAPABILITY - on the MacBook.  This is a big deal, as this allows quality graphics to be generated in real-time, under program control, and with actionable data.

The technical details for the Macbook involve: 

  -  having the XQuartz (X11) utilities installed

  -  you need all the command-line build utilities and Xcode 7 or better gcc compatible c++ compiler and tools

  -  you will need to get the "xcb" library routines, which GNU-APL uses to talk to X11, and build these from source  (get xcb 1.12, run tar -xvf,  and then just run ./configure, make, make install to build and install the xcb libraries for X11.

  -  when building the GNU-APL, you need to use:  " ./configure  --without-gtk3"    (since the Gtk routines are not part of MacOSX), and then "make" and "make install" to install the GNU-APL with xcb graphics support for the ⎕PLOT system function.

  -  and for the GNU-APL ./configure, you also need to set the LDFLAGS to where-ever your X11 libraries are, in my case it was:

       export LDFLAGS="-L/usr/X11/lib"

  -   also have to make sure you xcb routines and xcb-proto.pc(the /usr/X11/lib/pkgconfig file) are the  same version as the X11 library routines  and xproto headers).  I had to download xcb_1.12 version as a tar.gz file, and [ ./configure, make, make install ] to build the xcb routines.

The xcb code is old, and works well.  If you have XQuartz installed (for MacOSx X11 support), the whole thing works pretty good.  The xcb stuff is how ⎕PLOT talks to X11 and gets it to fling up graphics windows containing the plots.  Note that the GNU-APL surface plots are configured using a 3-d matrix (a "cube" or "block" of data-values).   If the rho,rho of the data equals 3,  (ie. data is a 3-dimension block of numbers) then this tells ⎕PLOT that is should make a surface plot, and not a table full of lines, as the chart.

 

Example of GNU-APL to Produce Plot

I just discovered the ⎕PLOT function in GNU-APL.  It does not work on the MacBook, but it DOES work on the Linux boxes.  (Plus, it looks like I can render APL chars in this webpage editor!)...  Here is a simple graphic, 2000 random numbers, 1 to 1000:

      ∇RAN_PLOT[⎕]∇
    ∇
[0]   RAN_PLOT
[1]  ⍝ --- Plot 2000 Random Numbers.  Note, this fn uses global var: Attr
[2]  ⍝ --- Attr is a nested array of "attrib: value" (eg: "line_width-1: 1 pixel") passed to ⎕PLOT as left argument
[3]  ⍝ --- This function simply displays a PLOT of 2000 random numbers, in the range of 1 to 1000.
[4]   Attr ⎕PLOT ,(1000?1000),,(1000?1000)
    ∇

The left argument to ⎕PLOT is a nested array of "parameter:  value" strings, - basically just an encapsulated table.  You can display it with the "disclose" operator, on the "Attr" variable: (viz.)

      ⊃Attr
legend_name-1:  Random Numbers        
caption: A Plot of Many Random Numbers
line_width-1: 1 pixel                 
pa_border_L: 60 pixel                 
point_size-1: 3 pixel                 
canvas_color: #2C2C2C                 
pa_width: 1100                        
pa_height: 700                        
      
What this does, is pretty self-explanatory,

 

The GNU-APL can be used to access SQL-Lite Databases. An example is shown below.


Available function numbers for GNU-APL to Access SQL-Lite Database:
-------------------------------------------------------------------

type  ⎕SQL[1] file      - open a database file, return reference ID for it
      ⎕SQL[2] ref       - close database
query ⎕SQL[3,db] params - send SQL query
query ⎕SQL[4,db] params - send SQL update
      ⎕SQL[5] ref       - begin a transaction
      ⎕SQL[6] ref       - commit current transaction
      ⎕SQL[7] ref       - rollback current transaction
      ⎕SQL[8] ref       - list tables
ref   ⎕SQL[9] table     - list columns for table


  Example of Using SQL-Lite (Version 3) "sqlite3" with GNU-APL
  ============================================================

The weirdly curious lack of "How-To's" and "Examples" on modern documentation
is rather unfortunate.  Everyone who writes, assumes that everyone is already
a domain-level expert.   This is a profoundly incorrect assumption, of course.

Here is a simple example of creating an SQLITE database and putting some
records in it, and then reading these records from within a GNU-APL workspace.

Hope this is useful for non-experts who are curious and want/need to do some
real work using their Linux-boxes!

- Mark Langdon,
  Owner & Developer,
  GEMESYS Ltd.
  December 8th, 2020


======== Example Of Creating SQLite3 Database and Reading it in GNU-APL =====

             Create a Tiny Example SQLite3 Database
             ======================================

Here, we are at command-level, in an X-Term window in the user directory.
We will create a tiny two-column database table, and put two records in it.

First, we just start "sqlite3" and confirm we can successfully exit it.
This confirms it is installed by default on our CentOS-7 Linux box, which
runs the default GNOME Windowing environment, which is similar to Windows-10.


( ---- Let's start SQLite3 at Linux Command-Line Level... )

[mcl@l2-centos74 ~]$ sqlite3

SQLite version 3.7.17 2013-05-20 00:56:22
Enter ".help" for instructions
Enter SQL statements terminated with a ";"
sqlite> .quit


( ---- Now, we will create a tiny database in a file called:  mclnote.db )


[mcl@l2-centos74 ~]$ sqlite3 mclnote.db
SQLite version 3.7.17 2013-05-20 00:56:22
Enter ".help" for instructions
Enter SQL statements terminated with a ";"


( ---- The database has been created, and we can now use CREATE and INSERT verbs )
( ---- in SQL to create a datatable, which will be called "notes" and will have  )
( ---- a line of text, and an integer number, which we will call "date".         )


sqlite> create table notes(text,date INTEGER);


( ---- We put two rows in the table, using INSERT verb.  This is just standard SQL. )
( ---- Note that SQL commands are terminated with semi-colons...                    )


sqlite> insert into  notes values('This is the first test note.', 20201205);
sqlite> insert into notes values('This is the second test note.', 20201205);


( ---- Now, lets see if the data is actually in the table.  We use the SELECT    )
( ---- verb to query the table and display it's contents.                        )


sqlite> select * from notes;
This is the first test note.|20201205
This is the second test note.|20201205


( ---- Ok, lets quit SQLite3... )


sqlite> .quit;
Error: unknown command or invalid arguments:  "quit;". Enter ".help" for help

( ---- Didn't work, did it...   )

sqlite> .quit


( ---- Ok, that worked.  We have a file in the user directory called "mclnote.db". )
( ---- We can confirm it exists, using the Linux "ls" command that lists files...  )


[mcl@l2-centos74 ~]$ ls *.db -l
-rw-r--r--. 1 mcl mcl 2048 Dec  5 18:04 mclnote.db


( ---- This is our sample tiny database example, which we will read in GNU-APL. )


      Read an SQL database table created with SQLite3 from within GNU-APL
      ===================================================================

( ---- Start GNU-APL...  )

[mcl@l2-centos74 ~]$ apl -noColor
unknown option '-noColor'
usage: apl [options]
    options:
    -h, --help           print this help
    -d                   run in the background (i.e. as daemon)
    -f file              read APL input from file
    --id proc            use processor ID proc (default: first unused > 1000)
    --cfg                show ./configure options used and exit
    --noCIN              do not echo input (for scripting)
    --echoCIN            echo (final) input to COUT
    --rawCIN             do not emit escape sequences
    --[no]Color          start with ]XTERM ON [OFF])
    --noCONT             do not )LOAD CONTINUE or SETUP workspace on startup
    --emacs              run in (classical) emacs mode
    --emacs_arg arg      run in emacs mode with argument arg
    --gpl                show license (GPL) and exit
    -L wsname            )LOAD wsname (and not SETUP or CONTINUE) on startup
    --LX expr            execute APL expression expr first
    -p N                 use profile N in preferences files
    --par proc           use processor parent ID proc (default: no parent)
    --PW value           initial value of ⎕PW
    -q, --silent         do not print the welcome banner
    -s, --script         same as --silent --noCIN --noCONT --noColor
    --safe               safe mode (no shared vars, no native functions)
    --show_bin_dir       show binary directory and exit
    --show_doc_dir       show documentation directory and exit
    --show_etc_dir       show system configuration directory and exit
    --show_lib_dir       show library directory and exit
    --show_src_dir       show source directory and exit
    --show_all_dirs      show all directories above and exit
    --[no]SV             [do not] start APnnn (a shared variable server)
    -T testcases ...     run testcases
    --TM mode            test mode (for -T files):
                         0:   (default) exit after last testcase
                         1:   exit after last testcase if no error
                         2:   continue (don't exit) after last testcase
                         3:   stop testcases after first error (don't exit)
                         4:   exit after first error
    --TR                 randomize order of testfiles
    --TS                 append to (rather than override) summary.log
    -v, --version        show version information and exit
    -w milli             wait milli milliseconds at startup
    --                   end of options for apl


( ---- Ok, the attempt to start APL with the "--noColor" option didn't work, because  )
( ---- I entered "-noColor" with a single dash, not the required "--" (double dash).  )
( ---- If you try to start GNU-APL without "--noColor", on my CentOS-7 Linux box, I   )
( ---- get some scrambled video which requires an ")off" and then a "reset" to be     )
( ---- entered, to restore operation of the X-Term window. (This is some problem with )
( ---- the emacs editor front-end for APL, which does not work on my system.)         )
( ---- If I start APL with "--noColor", everything works fine.                        )


[mcl@l2-centos74 ~]$ apl --noColor
                                       
                    ______ _   __ __  __    ___     ____   __
                   / ____// | / // / / /   /   |   / __ \ / /
                  / / __ /  |/ // / / /   / /| |  / /_/ // /  
                 / /_/ // /|  // /_/ /   / ___ | / ____// /___
                 \____//_/ |_/ \____/   /_/  |_|/_/    /_____/
                                       
            Welcome to GNU APL version 1.7 / Unversioned directory
                                       
                Copyright (C) 2008-2016  Dr. Jürgen Sauermann
                       Banner by FIGlet: www.figlet.org
                                       
                This program comes with ABSOLUTELY NO WARRANTY;
                          for details run: apl --gpl.
                                       
     This program is free software, and you are welcome to redistribute it
         according to the GNU Public License (GPL) version 3 or later.
                                       
          
      
      )help

( ---- Enter ")help" causes all GNU-APL commands to be shown... )

APL Commands:
      )CHECK
      )CLEAR
      )CONTINUE
      )COPY [lib] wsname [object ...]
      )DROP [[lib] wsname]
      )ERASE symbol ...
      )DUMP-HTML [[lib] wsname]
      )DUMPV [[lib] wsname]
      )DUMP [[lib] wsname]
      )FNS [from-to]
      )HELP
      )HIST [CLEAR]
      )HOST command
      )IN filename [object ...]
      )LIBS [[lib] path]
      )LIB [lib|path]
      )LOAD [lib] wsname
      )MORE
      )NMS [from-to]
      )OFF
      )OPS [from-to]
      )OUT filename [object ...]
      )PCOPY [lib] wsname [object ...]
      )PIN filename [object ...]
      )QLOAD [lib] wsname
      )RESET
      )SAVE [[lib] wsname]
      )SIC
      )SINL
      )SIS
      )SI
      )SYMBOLS [count]
      )VALUES
      )VARS [from-to]
      )WSID [wsname]
      ]BOXING [OFF|2|3|4|7|8|9]
      ]COLOR [ON|OFF]
      ]NEXTFILE
      ]EXPECT error_count
      ]HELP
      ]KEYB
      ]LIB [lib|path]
      ]LOG [facility [ON|OFF]]
      ]OWNERS
      ]PSTAT [CLEAR|SAVE]
      ]SIS
      ]SI
      ]SVARS
      ]SYMBOL symbol
      ]USERCMD [ ]ucmd APL_fun [mode]
               | ]ucmd { ... }
               | REMOVE ]ucmd
               | REMOVE-ALL
               ]
      ]XTERM [ON|OFF]

System variables:
      ⎕AI     Account Information
      ⎕ARG    command line ARGuments of the interpreter
      ⎕AV     Atomic Vector
      ⎕CT     Comparison Tolerance
      ⎕EM     Event Message
      ⎕ET     Event Type
      ⎕FC     Format Control
      ⎕IO     Index Origin
      ⎕L      Left Argument
      ⎕LC     Line Counters
      ⎕LX     Latent Expression
      ⎕PP     Printing Precision
      ⎕PR     Prompt Replacement
      ⎕PS     Print Style
      ⎕PW     Print Width
      ⎕R      Right Argment
      ⎕RL     Random Link
      ⎕SVE    Shared Variable Event
      ⎕SYL    SYstem Limits
      ⎕TC     Terminal Control characters
      ⎕TS     Time Stamp
      ⎕TZ     Time Zone
      ⎕UL     User Load
      ⎕X      aXis Argument
      ⎕WA     Workspace Available
      λ       { ... } result
      ⍺       { ... } left value argument
      ⍵       { ... } right value argument
      χ       { ... } axis argument
      ⍶       { ... } left function argument
      ⍹       { ... } right function argument

System functions:
      ⎕AF     Atomic Function
      ⎕AT     Attributes
      ⎕CR     Character Representation
      ⎕DL     Delay
      ⎕DLX    D. Knuth's - Dancing Links
      ⎕EA     Execute Alternate
      ⎕EB     Execute Both
      ⎕EC     Execute Controlled
      ⎕ENV    ENvironment Variables
      ⎕ES     Event Simulate
      ⎕EX     EXpunge
      ⎕FIO    File I/O
      ⎕FX     FiX
      ⎕INP    INPut from script
      ⎕NA     Name Association
      ⎕NC     Name Class
      ⎕NL     Name List
      ⎕SI     State Indicator
      ⎕SQL    SQL functions
      ⎕SVC    Shared Variable Control
      ⎕SVO    Shared Variable Offer
      ⎕SVQ    Shared Variable Query
      ⎕SVR    Shared Variable Retraction
      ⎕SVS    Shared Variable State
      ⎕STOP   STOP vector
      ⎕TF     Transfer Form
      ⎕TRACE  TRACE vector
      ⎕UCS    Universal Character Set (aka. Unicode)
       

      Bad UTF8 sequence start at LineInput.cc:987
Bad UTF8 sequence start at LineInput.cc:987

( ---- If you enter an incorrect ALT-key sequence, you might get the  )
( ---- above error message.  Don't worry about it, just carry on...   )


      ⎕SQL 'sfsfs'

( --- Above, if you enter a bogus command to Quad-SQL, you get the SQL help...)

Available function numbers:
type  ⎕SQL[1] file      - open a database file, return reference ID for it
      ⎕SQL[2] ref       - close database
query ⎕SQL[3,db] params - send SQL query
query ⎕SQL[4,db] params - send SQL update
      ⎕SQL[5] ref       - begin a transaction
      ⎕SQL[6] ref       - commit current transaction
      ⎕SQL[7] ref       - rollback current transaction
      ⎕SQL[8] ref       - list tables
ref   ⎕SQL[9] table     - list columns for table


( ---- Ok, so now, I try to open the SQLite3 database I just created... )
( ---- All this below is wrong... :)  -------------------------------   )

      ⎕SQL[1] mclnotes.db
VALUE ERROR
      ⎕SQL[1]mclnotes.db
                      ^
      ⎕SQL[1] 'mclnotes.db'
DOMAIN ERROR+
      ⎕SQL[1]'mclnotes.db'
      ^     ^
       1 ⎕SQL[1] 'mclnotes.db'
VALUE ERROR+
      1 ⎕SQL[1]'mclnotes.db'
      ^
        
        ⎕SQL[1] './mclnotes.db'
DOMAIN ERROR+
      ⎕SQL[1]'./mclnotes.db'
      ^     ^
      
      ⎕SQL[1] 'mclnote.db'
DOMAIN ERROR+
      ⎕SQL[1]'mclnote.db'
      ^     ^
      ⎕SQL[1] './mclnote.db'
DOMAIN ERROR+
      ⎕SQL[1]'./mclnote.db'
      ^     ^
      'sqlite3' ⎕SQL[1] './mclnote.db'
VALUE ERROR+
      'sqlite3' ⎕SQL[1]'./mclnote.db'
      ^

( ---- end of my wrong stuff that did not work!  Don't be discouraged...          )
( ---- you have to tell Quad-SQL command the type of database you want to open... )
( ---- once you open the database correctly, it will return a "reference number"  )
( ---- which the documentation carefully indicates as "ref" :) ...                )  


      'sqlite' ⎕SQL[1] './mclnote.db'
0

( ---- Ok, Success!  The database in local user directory has been opened ...)
( ---- Your reference handle to the database is "0" or the number zero ...   )
( ---- This command below Quad-SQL[8] displays the tables in the database ...)
( ---- You use the "reference number" to tell the Quad-SQL command which     )
( ---- database to refer to ...                                              )

      ⎕SQL[8] 0
 notes

( ---- Now, we can select all the contents of the "notes" table ... )


      'select * from notes' ⎕SQL[3,0]
SYNTAX ERROR
      'select * from notes' ⎕SQL[3,0]
      ^                         ^
      
( ---- What went wrong?  We forgot to include some paramter number.     )
( ---- When we include a parameter number, the SELECT statement works.  )


      'select * from notes' ⎕SQL[3,0] 0
 This is the first test note.  20201205
 This is the second test note. 20201205
      
( ---- Experimentation, confirms that this parameter number can be anything...)

      'select * from notes' ⎕SQL[3] 0
RANK ERROR+
      'select * from notes' ⎕SQL[3]0
      ^                           ^
      'select * from notes' ⎕SQL[3,1] 0
DOMAIN ERROR+
      'select * from notes' ⎕SQL[3,1]0
      ^                             ^

( ---- The database reference number is the second element of the Quad-SQL[3] )
( ---- system command vector, which is very curious, but such is life..       )

      'select * from notes' ⎕SQL[3,0] 1
 This is the first test note.  20201205
 This is the second test note. 20201205

( ---- The parameter to the Quad-SQL[3,dbrefnum] command can be anything ...  )
( ---- Below, we make it '234', and the command works.                        )

      'select * from notes' ⎕SQL[3,0] 234
 This is the first test note.  20201205
 This is the second test note. 20201205


( ---- But, if we fail to include this parameter number, then the command fails... )

      'select * from notes' ⎕SQL[3,0]    
SYNTAX ERROR
      'select * from notes' ⎕SQL[3,0]
      ^                         ^

( ---- Here, we make it '4564435', and the SELECT statement works correctly...  )

      'select * from notes' ⎕SQL[3,0] 4564435
 This is the first test note.  20201205
 This is the second test note. 20201205

( ---- We can make the parameter here iota-zero, which is NULL.  Still works... )

      'select * from notes' ⎕SQL[3,0] ⍳0     
 This is the first test note.  20201205
 This is the second test note. 20201205
      

( ---- Ok, so now we close the SQL database, using Quad-SQL[2], dbrefnum=0 ...  )


      ⎕SQL[2] 0


( ---- Since we closed the SQL database, any attempt to SELECT from it fails... )


      'select * from notes' ⎕SQL[3,0] ⍳0
DOMAIN ERROR+
      'select * from notes' ⎕SQL[3,0]⍳0
      ^                              ^

( ---- Ok, so lets re-open the database....    )

      
      'sqlite' ⎕SQL[1] './mclnote.db'
0

( ---- The Quad-SQL[1] command opens the database "mclnote.db" in local directory...)
( ---- And below, we run the SELECT against "notes" again, to get all the data ...  )

      'select * from notes' ⎕SQL[3,0] ⍳0
 This is the first test note.  20201205
 This is the second test note. 20201205

( ---- Now, lets put the data from the SQL database, into an APL variable, so we   )
( ---- can chop it up and/or scan out data elements from within the raw data  ...  )


      data ← 'select * from notes' ⎕SQL[3,0] ⍳0

( ---- We created an APL workspace variable called "data", and we can check the    )
( ---- dimensions of that variable, using the APL "rho" operator ...               )

      ⍴data
2 2

( ---- APL says the variable "data" is a 2 by 2 matrix ...   )
( ---- This APL uses nested arrays, which works as follows: The first row and the    )
( ---- element of the "data" variable is the first data-element of the "notes" table.)

      data[1;1]
 This is the first test note.

( ---- So, data[1;1], is just the first text string   ...                        )
( ---- We can use the "rho" operator to query the dimensions of this element ... )


      ⍴data[1;1]

( ---- Oops, no we can't.  This "nested-array" stuff requires that we "disclose" first.)
( ---- checking the rho (dimensions) of first row, first column of "data" returns as a )
( ---- scalar, which has no dimensions.  Checking the dimensions of a single number,   )
( ---- just returns a NULL result.  )

      ⍴data[1;1]

( ---- To actually get at the string of text, you have to "disclose" the stuff that  )
( ---- is "nested" inside row 1, column 1 of APL variable "data" ...                 )
( ---- The disclose operator, "⊃" is a symbol from "set theory", and you can make it )
( ---- on the APL keyboard with ALT(right)-x.                                        )

      ⍴ ⊃data[1;1]
28

( ---- Now, the "rho" operator (which is ALT(right)-r), gives the dimensions of the  )
( ---- text string in the first row of the "notes" table.                            )
( ---  And now we can chop up and/or search this text string.

      ⍴ ⊃data[1;1]
28
       7↑ (⊃data[1;1])
This is

( ---- In the above example, we extracted the first seven characters from the
( ---- first row in the SQL datatable "notes", which is a variable called "data"
( ---- in our APL workspace.  Note the workspace is not named yet.  We can name
( ---- the workspace and save it... )

      )wsid
IS CLEAR WS
      
( ---- We use ")vars" to query workspace variables, and ")fns" to list names of )
( ---- workspace functions (programs), but there are none here (yet...)         )

      )vars
data
      
      )fns
      
      data
 This is the first test note.  20201205
 This is the second test note. 20201205
      
      )wsid SQLEXAMPLE
WAS CLEAR WS
      )wsid
IS SQLEXAMPLE
      )save

( ---- Trying to SAVE the APL workspace failed, probably some default permission )
( ---- on the "workspace" subdirectory is wrong. So, just save it explicitly to  )
( ---- the user-directory on the Linux-box...                                    )

Unable to )SAVE workspace 'SQLEXAMPLE'. Permission denied
      
      )wsid /home/mcl/SQLEXAMPLE
WAS SQLEXAMPLE
      
      )wsid
IS /home/mcl/SQLEXAMPLE
      )save
2020-12-08  05:57:05 (GMT-5) /home/mcl/SQLEXAMPLE

( ---- now, the ")save" command worked.  )
( ---- Let's close the SQL database...   )

( ---- We check status of the SQL database, with ⎕SQL[8] and db-reference number.   )
( ---- This ⎕SQL command will display the data tables in the database ...           )
 

       ⎕SQL[8] 0
 notes

( ---- The Quad-SQL[9] command lists the column names in the "notes" table ... )       

      0 ⎕SQL[9] 'notes'
 text         
 date INTEGER
      
( ---- And the ⎕SQL[2] command, with the database reference number as parameter, )
( ---- will close the SQLite database   ...                                      )

      ⎕SQL[2] 0

( ---- Exit the GNU-APL with ")off" APL command ... )

      )off

Goodbye.

( ---- Return to Linux command-line, and confirm the APL workspace file was created...)

[mcl@l2-centos74 ~]$ ls SQL* -v
SQLEXAMPLE  SQLEXAMPLE.bak


( ---- We can also confirm the database file is present and accounted for...  :)     )

[mcl@l2-centos74 ~]$ ls mclnote* -l
-rw-r--r--. 1 mcl mcl 2048 Dec  5 18:04 mclnote.db
[mcl@l2-centos74 ~]$
[mcl@l2-centos74 ~]$
 

--------- End of Example GNU-APL Session Showing Example Query of SQL database ------- 

(More Notes to follow here...)

 

I will try to provide more examples of using GNU-APL, in the next while.