kz80_db 0.1.1

dBASE II clone for Z80 - Retro database on the RetroShield
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# kz80_db

A dBASE II clone for the Z80 RetroShield.

This project generates a Z80 ROM that implements a subset of dBASE II, the classic database management system from 1981. It runs on the RetroShield Z80 with SD card storage emulation.

## Features

- Authentic dBASE II file format compatibility
- Interactive command-line interface
- SD card storage via I/O port emulation

## Commands

| Command | Description |
|---------|-------------|
| `USE <file>` | Open a database file |
| `LIST` | Display all records |
| `DISPLAY` | Show current record in detail |
| `GO <n>` | Navigate to record n |
| `SKIP` | Move to next record |
| `DELETE [n]` | Mark record as deleted |
| `RECALL [n]` | Unmark deleted record |
| `PACK` | Permanently remove deleted records |
| `REPLACE` | Update a field value |
| `LOCATE` | Search for a record |
| `COUNT` | Count total records |
| `CREATE` | Create a new database |
| `APPEND` | Add a new record |
| `QUIT` | Exit the program |

## Startup File

Like the original dBASE II, kz80_db supports automatic command execution at startup. If a file named `STARTUP.CMD` exists in the storage directory, its contents will be executed as commands when the program starts.

Example `STARTUP.CMD`:
```
USE MYDB
COUNT
```

This will automatically open the MYDB database and display the record count.

## File Extensions

The `.DBF` extension is automatically appended to database filenames if no extension is provided, matching original dBASE II behavior:
- `USE MYDB` opens `MYDB.DBF`
- `USE MYDB.DBF` also opens `MYDB.DBF`

## Building

```bash
cargo build --release
./target/release/kz80_db
```

This generates `db.bin`, a Z80 ROM image.

## Running

Use with the RetroShield emulator:

```bash
../emulator/retroshield db.bin
```

## Testing

```bash
cargo test
```

Runs both unit tests and integration tests (requires the emulator).

## dBASE II File Format

The implementation uses the authentic dBASE II format:

**Header (8 bytes):**
- Byte 0: Version (0x02)
- Bytes 1-2: Record count (16-bit LE)
- Bytes 3-6: Last update date
- Byte 7: Record length

**Field Descriptors (16 bytes each):**
- Bytes 0-10: Field name
- Byte 11: Type (C=Character, N=Numeric)
- Byte 12: Field length
- Terminated by 0x0D

**Records:**
- First byte: Delete flag (space=active, *=deleted)
- Remaining bytes: Field data (space-padded)

## License

BSD 3-Clause. See [LICENSE](LICENSE).