geutebruck/geutebruck-api/specs/002-geviset-file-format/database-vs-setfile-comparison.md

# Database vs .SET File Structure Comparison

**Date:** 2025-12-12
**Purpose:** Document differences between GeViSoft Database and .SET configuration file

## Executive Summary

GeViSoft uses **TWO distinct storage systems**:

1. **GeViDB.mdb** (Access Database) - Stores runtime event logs
2. **.set File** (Binary Format) - Stores configuration and action mapping rules

They serve different purposes and have different structures.

---

## GeViSoft Database (GeViDB.mdb)

### Access Method

**Option 1: .NET SDK Wrapper** (Recommended)
```csharp
var db = new GeViDatabase();
db.Create("localhost", "sysadmin", "plainTextPassword");  // No encoding needed!
db.RegisterCallback();
var result = db.Connect();

// Query actions
db.SendQuery(new GeViDBQ_CreateActionQuery(0), out GeViMessage answer);
```

**Password Encoding:**
✅ **NOT REQUIRED** - The .NET wrapper (`GeViProcAPINET_4_0.dll`) handles password encoding internally.
The `Create()` method signature explicitly says `plainTextPassword`.

**Option 2: Direct OleDB Access**
```csharp
string connectionString = "Provider=Microsoft.ACE.OLEDB.12.0;Data Source=C:\GEVISOFT\DATABASE\GeViDB.mdb;Mode=Read;";
// Direct SQL queries to Alarms, Actions tables
```

### Database Structure

**Tables:**
- `Alarms` - Alarm definitions
- `Actions` - Runtime action event log
- (Other configuration tables)

**Actions Table Content:**
| PK | Action Data | Purpose |
|----|-------------|---------|
| 1 | `DataBaseReady()` | System initialization event |
| 4 | `SystemError(0,1000,203,"GEVISERVER: dongle not found")` | System error log |
| 5 | `SystemWarning(0,1000,206,"DEMO MODE GRANTED...")` | System warning |
| 15 | `UserLogin(1,"sysadmin","","127.0.0.1")` | User authentication log |

**Key Characteristics:**
- Stores **runtime events** and **logs**
- **NOT** action mapping configuration
- Grows over time as events occur
- Query-able with SQL or SDK queries

---

## .SET File (Binary Configuration)

### Access Method

**SetupClient API:**
```csharp
// PASSWORD ENCODING REQUIRED for native API!
var encodedPassword = new StringBuilder(256);
GeViAPI_EncodeString(encodedPassword, password, 256);

GeViAPI_SetupClient_Create(out handle, alias, address, username,
    encodedPassword.ToString(), "", "");
GeViAPI_SetupClient_Connect(handle, out result, 10000);
GeViAPI_SetupClient_ReadSetup(handle, out buffer, out size, 60000);
```

**Password Encoding:**
❌ **REQUIRED** for `SetupClient` native API!
Must call `GeViAPI_EncodeString()` before passing password.

### Binary Format Structure

```
.set File (281,714 bytes)
├── Header: "GeViSoft Parameters" (length-prefixed)
├── Sections (multiple)
│   ├── Alarms
│   ├── Cameras
│   ├── GeViIO
│   ├── Clients
│   └── Action Mapping Rules
│       ├── "Rules" marker (05 52 75 6C 65 73)
│       ├── Trigger Conditions
│       └── Action Strings
│           ├── Format: 07 01 40 <len_2bytes_LE> <data>
│           └── Examples:
│               • "GSC ViewerConnectLive V <- C"
│               • "GNG PanLeft_101027"
│               • "GSC warning: demo mode for 100 min"
```

**Action Mappings Extracted:** 64 rules with 107 action strings

**Examples:**
```json
{
  "id": 1,
  "fileOffset": 253894,
  "actions": [
    "GSC ViewerConnectLive V <- C",
    "GNG ViewerConnectLive V <- C_101027"
  ]
}
```

**Key Characteristics:**
- Stores **configuration** and **rules**
- Defines trigger → action mappings
- Static configuration (doesn't grow)
- Can be exported/imported with GeViSet application
- Binary format requires parsing

---

## Comparison Table

| Aspect | Database (GeViDB.mdb) | .SET File |
|--------|----------------------|-----------|
| **Purpose** | Runtime event logging | Configuration storage |
| **Content** | System events, user logins, errors | Action mapping rules, system config |
| **Password Encoding** | ❌ NOT needed (.NET wrapper) | ✅ REQUIRED (native SetupClient API) |
| **Access Method** | GeViDatabase + SendQuery | SetupClient_ReadSetup |
| **Data Type** | Event logs (dynamic) | Configuration rules (static) |
| **Size** | Grows over time | Fixed per configuration |
| **Format** | MS Access Database | Proprietary binary |
| **Queryable** | SQL / SDK queries | Binary parsing only |
| **Example Content** | `UserLogin(1,"sysadmin"...)` | `"GSC ViewerConnectLive V <- C"` |

---

## Password Encoding Summary

### When Encoding IS Required

**SetupClient Native API:**
```cpp
// C/C++ or P/Invoke
GeViAPI_EncodeString(encodedPassword, plainPassword, 256);
GeViAPI_SetupClient_Create(..., encodedPassword, ...);
```

**Why:** The native `GeViProcAPI.dll` requires pre-encoded passwords.

### When Encoding is NOT Required

**.NET SDK Wrapper:**
```csharp
// C# using .NET wrapper
var db = new GeViDatabase();
db.Create(server, username, plainTextPassword);  // Handles encoding internally
```

**Why:** The .NET wrapper (`GeViProcAPINET_4_0.dll`) calls `GeViAPI_EncodeString` internally.

---

## Use Cases

### Use Database When:
- Querying recent system events
- Checking user login history
- Monitoring system errors/warnings
- Real-time event tracking

### Use .SET File When:
- Exporting/importing configuration
- Backing up action mapping rules
- Bulk editing action mappings
- Understanding configured rules (not events)

---

## Tools Developed

### 1. QueryGeViDatabase
**Purpose:** Query database for runtime events
**Method:** .NET SDK wrapper
**Password:** Plain text (wrapper handles encoding)

```bash
QueryGeViDatabase.exe localhost sysadmin masterkey
```

**Output:**
- System events
- User logins
- Errors/warnings
- 100+ action event logs

### 2. DiagnoseSetupClient + GeViSetEditor
**Purpose:** Read/parse .set configuration file
**Method:** Native SetupClient API
**Password:** Manually encoded with `GeViAPI_EncodeString`

```bash
GeViSetEditor.exe to-json setup_config.dat output.json
```

**Output:**
- 64 action mapping rules
- 107 action strings
- Complete configuration in JSON

---

## Findings

1. **Database does NOT contain action mapping configuration**
   - Only stores runtime event logs
   - Cannot use database queries to read action mapping rules

2. **.SET file is the ONLY source for action mapping configuration**
   - Must use SetupClient API
   - Must parse binary format
   - Contains all 64 action mapping rules

3. **Password encoding depends on API layer:**
   - .NET wrapper: No encoding needed
   - Native API: Encoding required
   - Both work, different use cases

4. **Two distinct data flows:**
   ```
   Configuration Flow:
   GeViSet App → .SET File → SetupClient API → Binary Parser → JSON

   Events Flow:
   GeViServer → Database → SendQuery → Event Logs
   ```

---

## Recommendations

1. **For Action Mapping Management:**
   - Use SetupClient API to read .set files
   - Parse binary format to extract mappings
   - Export to JSON/Excel for editing
   - Rebuild .set file and write back

2. **For Event Monitoring:**
   - Use GeViDatabase queries
   - No binary parsing needed
   - Direct SQL or SDK queries

3. **Password Handling:**
   - Use .NET wrapper when possible (simpler)
   - Only use native API when .NET wrapper doesn't support the operation
   - Always encode passwords for native SetupClient API

---

## Next Steps

1. ✅ **Completed:**
   - Database connection (both methods)
   - SetupClient connection with password encoding
   - Binary parser for .set files
   - JSON export of action mappings

2. **In Progress:**
   - Excel export for user-friendly editing
   - Enhanced parser for trigger conditions

3. **Future:**
   - Add/modify/delete action mappings
   - Binary writer for modifications
   - Web UI for configuration management

---

## References

- SetupClient API: `C:\GEVISOFT\Examples\VS2010CPP\GeViSoftSDK\Include\GeViProcAPI.h`
- .NET Wrapper: `C:\GEVISOFT\GeViProcAPINET_4_0.dll`
- Database: `C:\GEVISOFT\DATABASE\GeViDB.mdb`
- Research Notes: `geutebruck-api/specs/002-geviset-file-format/research.md`