# isqlsh and isqlserverd — user manual

Internet SQL 1.23, x64. Covers the command-line shell (`isqlsh.exe`) and the
headless server (`isqlserverd.exe`), both in `bin\`.

---

## 1. Which program do I want?

ISQL runs in two quite different ways, and picking the wrong one accounts for
most first-hour confusion.

| You want | Use | Server needed? |
|---|---|---|
| One program reading/writing a database directly | `isqlsh -h <home>` | No — the engine runs *inside* `isqlsh` |
| Several programs or machines sharing one database | `isqlserverd`, then `isqlsh -s <ip>` | Yes |
| To run a `.sql` file from a build or batch script | `isqlsh -q -e -f file.sql` | Either |

The first is called **embedded** (or in-process): there is no network, no
service, and nothing to start beforehand. The second is **remote**: a server
process owns the database and clients reach it over TCP.

`bin\` also contains `shell.exe`. Despite the name it is **not** a network
client — it is a windowed local shell, and it reports `SQL engine did not start
yet` when it cannot find a database home. For scripting and for talking to a
server, use `isqlsh`.

---

## 2. A database home

Both modes need a *home*: a directory containing a `db` subdirectory.

```
C:\isqlhome\
    db\            <- must exist; the engine creates everything inside it
```

Create one by making the two directories. Nothing else is required — the engine
populates `db\` on first use.

If the home is missing or has no `db\`, you get
`cannot start the engine on '<path>'`.

---

## 3. isqlsh — the command-line shell

### 3.1 Synopsis

```
isqlsh [options] [home]
```

**Embedded**

| Option | Meaning |
|---|---|
| `-dbhome <dir>` | database home directory (`-h`, or a bare argument, also work) |

**Remote**

| Option | Meaning |
|---|---|
| `-ip <addr>` | server address; no local home is needed (`-s` also works) |
| `-port <n>` | server port (default `1973`) |
| `-u <user>` `-pwd <pass>` | user name and password |
| `-l user,pass` | the same login in one argument, e.g. `-l kamranga,manager` |
| `-t <ms>` | how long to wait for the port before giving up (default 5000) |

**Both**

| Option | Meaning |
|---|---|
| `-config F` | read `DatabaseHome` / `ServerIpAddress` / `ServerPortNo` / `UseNetwork` from file `F` |
| `-cmd <file>` | run statements from a file instead of stdin (`-f` also works) |
| `-d <db>` | database to `use` after connecting (default `default`) |
| `-q` | quiet — values only, no banner, prompt or row counts |
| `-e` | stop at the first failing statement |
| `-v` | echo each statement before running it |
| `-version` | print the version and exit |
| `-?` | help |

> **Changed in 1.24 — `-p` now means the password, not the port.** In 1.23
> `-p` was the port. It is the one option name that a person cannot tell from
> `-port` at a glance, and every other program in the drop uses `-p` for the
> password, so `isqlsh` was brought into line. **A 1.23 script that says
> `-p 1973` will now send `1973` as a password.** Change it to `-port 1973`.

The same six options — `-dbhome`, `-ip`, `-port`, `-u`, `-pwd`, `-cmd` — now
work in all seven programs; the local-only ones say so rather than silently
ignoring `-ip`/`-port`. `docs/isql-help-version.txt` is the full reference,
covering every SQL command as well.

If no home is given, `ISQL_DB_HOME` is used.

### 3.2 Interactive

```
bin\isqlsh.exe -h C:\isqlhome
```

```
Internet SQL 1.23 shell   home: C:\isqlhome   database: default
Statements end with ';'.  'quit' to leave.
iSql> select * from customers;
CUSTID | NAME | CITY
-----+------+-----
1 | Ada | London
(1 row)
iSql> quit
```

### 3.3 Running a file

```
bin\isqlsh.exe -h C:\isqlhome -f setup.sql
```

Statements end with `;` and may span lines. A `;` inside quotes does not end a
statement. Lines beginning with `--` or `#` are comments.

```sql
-- create the schema
create table staff(id number(5), name char(20), dept char(14));

insert into staff values(1,'Ada','Engineering');

# a statement over several lines
select id, name
  from staff
 where dept = 'Engineering';
```

A UTF-8 byte-order mark at the start of the file is ignored, so scripts saved by
Notepad or by PowerShell's `Set-Content` work unchanged.

### 3.4 Talking to a server

```
bin\isqlsh.exe -ip 127.0.0.1 -port 1973 -u kamranga -pwd manager -cmd report.sql
```

A remote session is a real multi-user session, so it needs `-l`. (The embedded
shortcut used in-process is not available over a socket.) Without it the server
will generally refuse statements.

No `-h` is needed remotely — the data lives on the server.

### 3.5 Using it from a script

`-q` prints values only and `-e` stops at the first failure. **The exit code is
0 only if every statement succeeded**, so it drops straight into a build:

```bat
bin\isqlsh.exe -q -e -h C:\isqlhome -f schema.sql
if errorlevel 1 echo SCHEMA FAILED & exit /b 1
```

| Exit code | Meaning |
|---|---|
| 0 | every statement succeeded |
| 1 | at least one statement failed |
| 2 | could not connect, or could not open `-f` / `-config` |

---

## 4. isqlserverd — the headless server

### 4.1 Synopsis

```
isqlserverd [-dll DIR] [-name SERVERNAME] [-config FILE]
```

| Option | Meaning |
|---|---|
| `-dll DIR` | where to find `isqldll.dll` (default: the exe's own directory, then the current one) |
| `-name NAME` | server name for the network agent (default `Kamranga`) |
| `-config FILE` | run on `FILE` instead of the `KAMRANGA.CFG` already here |
| `-version` | print the version and exit |
| `-h`, `-?` | help |

`isqlserver.exe` is the same server with a window. `isqlserverd.exe` is the one
to run headless or as a service.

### 4.2 Starting it

**The server does not take the database home on the command line.** It reads it
from `KAMRANGA.CFG` in the working directory. `isqlserverd.exe C:\isqlhome` is
rejected with `unknown argument`.

Edit `bin\KAMRANGA.CFG` so `[DatabaseHome]` points at a real home, then:

```
cd bin
isqlserverd.exe
```

```
isqlserverd - Internet SQL 1.23 server (console build)
  engine library loaded from '...\bin'
  instance = 2937325486256
  startid  = 2937325486256
  engine started
  server name 'Kamranga'
isqlserverd: listening - press Ctrl+C to stop
```

Ctrl+C stops it cleanly.

| Exit code | Meaning |
|---|---|
| 0 | clean shutdown |
| 1 | startup failure (usually `[DatabaseHome]`) |
| 2 | `isqldll.dll` not found |
| 3 | `-config` could not be applied |

---

## 5. Configuration files

### 5.1 Format

```
Anything out here is prose and is ignored.

entry
[DatabaseHome] C:\isqlhome
[ServerPortNo] 1973
[ServerName]   localhost
end
```

**Only the `entry … end` block is read.** Text outside it is comment. This
matters: the shipped `KAMRANGA.CFG` explains itself with a sentence containing
`[DatabaseHome] MUST point at …`, and that sentence is a comment, not a setting.

| Key | Used by | Meaning |
|---|---|---|
| `[DatabaseHome]` | server, `isqlsh -config` | database home directory |
| `[ServerPortNo]` | server, `isqlsh -config` | port the server listens on / client connects to |
| `[ServerName]` | server | server name |
| `[ServerIpAddress]` | `isqlsh -config` | server address for a client |
| `[UseNetwork]` | `isqlsh -config` | `1` to connect remotely, `0` for embedded |
| `[ParallelServerPortNo]`, `[MutexServerPortNo]` | server | auxiliary ports |

The engine itself reads `kamranga.cfg` when running as a server and `isql.cfg`
otherwise, always from the working directory. It cannot be told to read any
other filename — which is why `-config` exists, and why it works differently in
the two programs.

### 5.2 `-config` in the server: replaces

```
isqlserverd.exe -config C:\configs\reporting.cfg
```

Installs that file as the working directory's `KAMRANGA.CFG` and starts. It
must replace it, because that is the only path the engine will read.

- the previous `KAMRANGA.CFG` is kept as `KAMRANGA.CFG.bak`
- naming the file already in place is a no-op
- an unreadable file stops the server before it loads anything (exit 3)

### 5.3 `-config` in the shell: reads only

```
bin\isqlsh.exe -config C:\configs\reporting.cfg -l kamranga,manager -f report.sql
```

**Writes nothing.** The values are applied as if typed as arguments, so an
existing `isql.cfg` or `KAMRANGA.CFG` is untouched. Anything given explicitly on
the command line wins — `-h` beats the file's `[DatabaseHome]`.

With `[UseNetwork] 1` plus `[ServerIpAddress]` and `[ServerPortNo]`, one
`-config` is enough to point the shell at a server.

---

## 6. A worked example

Seed a database in-process, serve it, and query it over TCP.

```bat
rem 1. make a home and seed it - no server involved
mkdir C:\isqlhome\db
echo create table customers(custid number(5), name char(20), city char(20)); > seed.sql
echo insert into customers values(1,'Ada','London');                        >> seed.sql
bin\isqlsh.exe -q -h C:\isqlhome -f seed.sql

rem 2. point the server at that home, then start it
rem    (edit [DatabaseHome] in bin\KAMRANGA.CFG to C:\isqlhome)
cd bin
start isqlserverd.exe

rem 3. query it as a client
isqlsh.exe -ip 127.0.0.1 -port 1973 -u kamranga -pwd manager -cmd query.sql
```

Concurrent processes are fine: a client on the same machine as the server, or
two shells at once.

---

## 7. Troubleshooting

| Symptom | Cause |
|---|---|
| `cannot start SQL engine` (server) | `[DatabaseHome]` missing, wrong, or has no `db\` subdirectory. The commonest failure on a fresh install. |
| `isqlserverd: unknown argument 'C:\...'` | The server takes no positional home — put it in `KAMRANGA.CFG`, or use `-config`. |
| `cannot start the engine on '<path>'` (shell) | Home does not exist or has no `db\`. |
| `nothing is listening on <host>:<port>` | The server is not running, or `[ServerPortNo]` differs. `isqlsh` probes the port before connecting and gives up after `-t` milliseconds (default 5000) rather than hanging. |
| Remote statements rejected | Missing `-l user,pass`. A remote session needs a login. |
| `SQL engine did not start yet` from `shell.exe` | `shell.exe` is a windowed *local* shell, not a network client. Use `isqlsh -s`. |
| First statement of a `.sql` file fails, the rest work | Historically a UTF-8 BOM; current `isqlsh` strips it. If you see this, the shell is an old build. |
| A config setting seems ignored | It is outside the `entry … end` block, so it is being read as prose. |

---

## 8. Version

Both programs report their version and exit:

```
bin\isqlsh.exe -version        ->  isqlsh 1.25
bin\isqlserverd.exe -version   ->  isqlserverd 1.25
```

All seven programs answer `-version`, not just these two.

The version is defined once, in `h/isqlversion.h`, and the same string is kept
in the plain-text `VERSION` file for build scripts and packaging.
`tests\lib\checkversion.ps1` fails if the header, the `VERSION` file and what
the binaries actually print ever disagree.

Numbering is MAJOR.MINOR. MAJOR changes when the on-disk format or the C API
breaks compatibility; MINOR when a release adds capability or fixes defects and
an existing home and application keep working. 1.25 is a MINOR release over
1.24 and reads a 1.22 database unchanged.

---

## 9. 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.
