# Internet SQL 1.24

A maintenance release over 1.23. It reads a 1.22 or 1.23 database unchanged;
no on-disk format or C API has changed.

The headline is that the command line is now the same in every program. Four
of the five shells also did not work correctly before this release, in ways
that were easy to miss because they still printed a prompt.

---

## Breaking change: `isqlsh -p` now means the password

In 1.23, `isqlsh -p` was the **port**. It is now the **password**, matching
every other program in the drop; the port is `-port`.

```
1.23:  isqlsh -s 127.0.0.1 -p 1973 -l kamranga,manager -f q.sql
1.24:  isqlsh -ip 127.0.0.1 -port 1973 -u kamranga -pwd manager -cmd q.sql
```

**A 1.23 script that says `-p 1973` will now send `1973` as a password** and be
refused by the server. `-s`, `-h`, `-f` and `-l` still work as aliases, so that
one option is the only edit a 1.23 script needs.

The reason for accepting a breaking change in a minor release: a parser can
tell `-p` from `-port` exactly, but a person cannot. Leaving `-p` as the port in
one program out of seven meant that anyone carrying the habit across programs
would type their password into a port number, or the reverse, and only find out
from a failure much later.

---

## New: one command line for all seven programs

`-dbhome`, `-ip`, `-port`, `-u`, `-pwd`, `-cmd`, `-version` and `-?` now work
in `shell`, `shelldev`, `locshell`, `shellonlib`, `isqlsh`, `isqlserver` and
`isqlserverd`. They are case-insensitive and take either `-` or `/`. Aliases:
`-h` for `-dbhome`, `-s` for `-ip`, `-user` for `-u`, `-p` for `-pwd`, `-f` for
`-cmd`. (`isqlserverd` predates the shared parser and reads `-h` as help.)

They come from one shared parser, `h/isqlopts.h`, rather than seven
hand-written ones, so they cannot drift apart in meaning.

**`-cmd <file>`** runs a file of statements and exits — the batch equivalent of
the Run-Script dialog the windowed shells have always had. Statements end with
`;` and may span lines, `--` and `#` start comments, and a UTF-8 byte-order mark
is skipped so files written by Notepad or PowerShell work unchanged.

```
shell.exe -dbhome C:\isqlhome -cmd schema.sql
isqlsh.exe -q -e -dbhome C:\isqlhome -cmd schema.sql   && echo OK
```

**`-ip` and `-port` in a local tool are reported, not ignored in silence:**

```
shell: -ip/-port ignored - this tool runs the engine in-process, not over a network
```

That message exists because of the defect below: a shell that silently reaches
nothing looks exactly like a shell that is working.

**`-dbhome` and `-port` in the two servers write into `KAMRANGA.CFG`**, keeping
the previous file as `KAMRANGA.CFG.bak`, and only inside the `entry…end` block.
They have to. The engine reads the config itself, and a value in that file beats
one passed to the engine — measured both ways:

| | result |
|---|---|
| no config file, home passed to the engine | the passed home is used |
| config file names a home | **the config wins, silently** |

A server always has a `[DatabaseHome]`, so a `-dbhome` merely handed to the
engine would have been discarded every single time.

---

## Fixed

**The shells were reaching no database home at all.** `NoNetworkMode` was
commented out in `ShellOnLib`, and `shell.exe` never called
`CreateInternetSqlInstance`. They started, printed a banner, showed a prompt,
and answered statements — against nothing. Fixed in all four, and each now
reports the home it started on, so the failure cannot recur unnoticed.

**`locshell.exe` crashed on startup**, not on window close as 1.23's release
notes stated: it wrote `IsqlInstance->window_console = 1` before the instance
existed. The known-limitation entry is withdrawn.

**`isqlsh -ip` no longer hangs when nothing is listening.** `StartInternetSql`
has no connect timeout; pointed at a dead port it blocked inside the engine and
the shell had to be killed. `isqlsh` now probes the port itself first:

```
isqlsh: nothing is listening on 127.0.0.1:1973 (waited 5000 ms)
        start isqlserverd, or check [ServerPortNo]; use -t to wait longer
```

About two seconds instead of never, exit code 2. `-t <ms>` sets the wait.

**A relative `-cmd` path failed in `locshell` and `shellonlib`.** The engine
changes directory into the database home as it starts, so a shell that opened
the file afterwards resolved the name against the home instead of against the
directory the user typed the command in — the same flag with the same file
worked in `shell.exe` and failed in `locshell.exe`. `-cmd` is now resolved to a
full path during argument parsing, before the engine starts, in all seven
programs; the "could not open it" message names the full path it tried.

**`ISQL_DeleteInstance` crashed** with an access violation: a NULL dereference
in `StoptLog` and a second `fclose` of an already-closed log handle. Both fixed.

**Only one engine could run per machine.** A second process calling
`CreateInternetSqlInstance` got 0 back, with `GetLastError` 5. The config layer
kept a kernel HANDLE and heap pointers in a `#pragma data_seg("shared")`
section linked `RWS` — values that are meaningless in another process's address
space. They are ordinary per-process globals now, and concurrent shells,
servers and clients coexist.

---

## New: `docs/isql-help-version.txt`

One reference covering all 39 SQL commands, the vector-table commands, the full
command line of every program, and the configuration file.

Its command section is generated from the engine's own help table rather than
written by hand, so it lists what the binaries really answer to.

It also documents, from measurement, something no previous document stated:
**the `DISTANCE` column returned by `VECTOR` is cosine distance.** The scale is
therefore 0 to 2 — 0 same direction, 1 at right angles, 2 opposite — and
magnitude is ignored, so `'5,0,0'` sits at distance 0 from `'1,0,0'` and there
is no need to normalise before inserting. Choosing a `maxdistance` as though
the scale ran 0 to 1 quietly returns most of the table.

---

## In this drop

`bin\` now carries all seven programs. 1.23 shipped four.

| | |
|---|---|
| `isqlsh.exe` | scriptable shell, embedded or remote |
| `shell.exe`, `shelldev.exe` | local shells, DLL family |
| `locshell.exe`, `shellonlib.exe` | local shells, statically linked |
| `isqlserverd.exe` | headless server |
| `isqlserver.exe` | windowed server |

---

## Known limitations

- **VLR record format is not implemented.** `create table … recordformat=vlr`
  returns `Unexpected symbol: 'recordformat'`.
- **The PHP interface does not exist as a binary.** `php/php_isql.c` targets the
  PHP 4 Zend API and has never been built.
- **`INSERT` returns the row it inserted**, as a result set, so it contributes a
  line to `isqlsh -q` output exactly as a `SELECT` does. Engine behaviour, not
  the shell's; a script that counts lines should account for it.
