🔌 ZimAPI Developer Guide (C# Edition)
🚀 What Is ZimAPI?
ZimAPI for C# is a powerful interface that connects your .NET applications directly to the ZIM database engine. It enables developers to execute ZIM and SQL commands, manage transactions, transfer files, and interact with persistent data sets—all within a C# environment.
But ZimAPI is more than just a connector. It’s a gateway to ZIM’s integrated database, which offers a unique and developer-friendly feature: automatic data set creation and session-based persistence.
🧠 Why ZIM Is Different
Unlike traditional SQL databases like MySQL or PostgreSQL, ZIM automatically creates a data set every time a query is executed. These data sets behave like dynamic views and remain available for the entire session—no need to define or manage them manually.
In other systems, a developer must explicitly request a view or cache query results. In ZIM, this happens automatically:
FIND 5 Customers -> sCustomers
This creates a set named sCustomers containing up to 5 customer records. You can interact with this set throughout the session:
DELETE 1 FROM sCustomers
Once the API session ends, ZIM automatically drops the data set. When a new session begins, a fresh set is created based on the new query context.
🛠️ Installation
After completing the full ZIM installation:
- Locate
zimapi.cs in your ZIM installation directory. - Copy it to the directory where your C# application will be developed.
- Reference the compiled
ZimAPI.dll in your project.
🌐 Globals
ZimAPI provides several global constants for convenience:
| Constant | Description |
|---|
TOP | Indicates the first record in a set |
BOTTOM | Indicates the last record in a set |
UTF8 | Indicates a UTF-8 encoded ZIM database |
ANSI | Indicates an ANSI encoded ZIM database |
NO_ERROR | Indicates no error occurred |
🔗 Connecting to ZIM
Basic Setup
using ZimConnection;
ZimAPI Conn = new ZimAPI();
Conn.Connect("DatabaseName", "localhost", 6002, "ZIM", "");
System.Console.WriteLine(Conn.State);
Conn.Close();
Inline Constructor
using ZimConnection;
ZimAPI Conn = new ZimAPI("DatabaseName", "localhost", 6002, "ZIM", "");
System.Console.WriteLine(Conn.State);
Conn.Close();
Note:
DatabaseName is required.HostName defaults to "localhost"PortNumber defaults to 6002 (must match zimconfig.srv if changed)UserName defaults to "ZIM"Password defaults to ""
🧩 Core Methods
Conn.Execute(command)
Executes a ZIM or SQL command.
if Conn.Execute("DELETE 1 Customers WHERE CustCode = 1") == 0
System.Console("Executed successfully.")
elseif Conn.State = 1001
System.Console("Record not found.")
else
System.Console("Error executing statement. Error Code is = " + Conn.State + ".")
endif
Conn.Transaction(), Conn.Commit(), Conn.Rollback()
Control explicit transactions for atomic operations.
Conn.Transaction();
Conn.Execute("UPDATE Customers SET Status = 'Active' WHERE CustCode = 1");
Conn.Commit();
Or roll back if needed:
Conn.Rollback();
Conn.Callproc(procedure)
Call a ZIM procedure with input/output parameters.
string[] Result = Conn.Callproc("MyProc(\"12\", 7, \"?\", \"?\")");
if Result[1] != null and Result[2] != null
System.Console("Result: " + Result[1] + ", " + Result[2])
else
System.Console("Procedure returned no output.")
endif
Conn.Putfile() / Conn.Getfile()
Transfer files between client and server.
Conn.Putfile("local.txt", "/server/data.txt", "/A"); // Upload text file
Conn.Getfile("/server/data.txt", "local_copy.txt", "/A"); // Download it back
Conn.ErrorMessage() / Conn.ErrorCode()
Retrieve the last error message or code.
System.Console("Error: " + Conn.ErrorMessage());
System.Console("Code: " + Conn.ErrorCode());
ZIM’s automatic data sets are one of its most powerful features. These sets persist for the duration of the session and behave like dynamic views.
Create and Use a Cursor
ZimAPI.ZimCursor MyCursor = Conn.Cursor("FIND 5 Customers");
while MyCursor.RowCount() > 0
string row = MyCursor.FetchOne();
System.Console(row);
endwhile
Or:
ZimAPI.ZimCursor MyCursor = Conn.Cursor();
MyCursor.Execute("FIND 5 Customers");
Cursor Utilities
| Method | Description |
|---|
MyCursor.Close() | Closes the cursor. |
MyCursor.RowCount() | Number of rows available. |
MyCursor.FetchOne() | Fetches the next row. |
MyCursor.RowNumber() | Current row number. |
MyCursor.ValueOf(name) | Gets field value by name. |
MyCursor.ValueOf(index) | Gets field value by index. |
MyCursor.GetName(index) | Gets field name by index. |
MyCursor.FieldCount() | Number of fields in the record. |
MyCursor.Scroll(amount) | Scrolls cursor by rows or to TOP / BOTTOM. |
📦 Sets: Persistent Views of Data
Sets are logical collections of rows that persist across the session. They behave like views and can be reused across multiple operations.
Create a Set
ZimAPI.ZimCursor MyCursor = Conn.Cursor("FIND 5 Customers -> sCustomers");
Manipulate the Set
MyCursor.Execute("DELETE 1 FROM sCustomers");
Use sets to:
- Cache filtered data
- Perform batch operations
- Share views across procedures
🧪 Real-World Use Cases
Use ZimAPI to dynamically change UI elements based on backend data.
🔄 2. Transactional Integrity
Wrap multiple operations in a transaction to ensure atomicity.
📞 3. Business Logic via Procedures
Trigger backend logic stored in ZIM procedures—like calculating discounts or validating credentials.
📁 4. Secure File Sync
Automate secure file transfers between client and server for compliance logs or audit trails.
📊 5. Dashboard Integration
Pull live data from ZIM into a C#-based dashboard using cursors and sets.
🧭 Summary
ZimAPI for C# is a powerful and developer-friendly interface that brings ZIM’s integrated database and automatic data set creation into your .NET applications. It simplifies data access, enhances performance, and reduces boilerplate code—making it ideal for enterprise automation, smart dashboards, and intelligent safety systems.
Whether you’re modernizing legacy infrastructure or building new solutions, ZimAPI gives you the tools to do it efficiently and elegantly.
English 
Portuguese