🔌 ZimAPI Developer Guide (Python Edition)

🚀 What Is ZimAPI?

ZimAPI is a Python interface that connects directly to the ZIM database engine. It allows developers to execute ZIM and SQL commands, manage transactions, transfer files, and interact with persistent data sets—all from Python.

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 Python 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:

1. Locate zimapi.py in your ZIM installation directory.
2. Copy it to the directory where your Python scripts will run.

✅ Tip: Keep zimapi.py in a shared utilities folder if you’re working across multiple projects.

🔗 Connecting to ZIM

Basic Setup

import zimapi
import os

zim = zimapi.Zimapi()
zim = zim.connect(
    dbname="your_database_name",
    host="localhost",       # Optional
    port=6002,              # Optional
    user="ZIM",             # Optional
    password=""             # Optional
)

print(zim.state)
zim.close()

Inline Connection

zim = zimapi.Zimapi(
    dbname="your_database_name",
    host="localhost",
    port=6002,
    user="ZIM",
    password=""
)
print(zim.state)
zim.close()

Note:

• dbname is required.
• host defaults to "localhost"
• port defaults to 6002 (must match zimconfig.srv if changed)

🧩 Core Methods

zim.execute(command)

Executes a ZIM or SQL command.

if zim.execute("DELETE 1 Customers WHERE CustCode = 1") == 0:
    print("Executed successfully.")
elseif zim.state == 1001:
    print("Record not found.")
else:
    print("Error executing statement. Error Code =", zim.state)
endif

zim.transaction(), zim.commit(), zim.rollback()

Control explicit transactions for atomic operations.

zim.transaction()
zim.execute("UPDATE Customers SET Status = 'Active' WHERE CustCode = 1")
zim.commit()

Or roll back if needed:

zim.rollback()

zim.callproc(procedure_name, arguments)

Call a ZIM procedure with input/output parameters.

args = ("12", 7, "?", "?")
res = zim.callproc("MyProc", args)

if res[1] and res[2]:
    print("Result:", res[1], res[2])
else:
    print("Procedure returned no output.")
endif

zim.putfile(source, destination, format)

Upload a file from your local machine to the server.

zim.putfile("local.txt", "/server/data.txt", "/A")  # Text file

zim.getfile(source, destination, format)

Download a file from the server to your local machine.

zim.getfile("/server/data.txt", "local_copy.txt", "/A")  # Text file

🧵 Cursors & Sets: ZIM’s Secret Weapon

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

cur = zim.cursor("FIND 5 Customers")

while cur.rowcount() > 0:
    row = cur.fetchone()
    print(row)
endwhile

Or:

cur = zim.cursor()
cur.execute("FIND 5 Customers")

Cursor Utilities

📦 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

cur = zim.cursor("FIND 5 Customers -> sCustomers")

Manipulate the Set

zim.execute("DELETE 1 FROM sCustomers")

Use sets to:

• Cache filtered data
• Perform batch operations
• Share views across procedures

🧪 Real-World Use Cases

🔄 1. Transactional Integrity

Wrap multiple operations in a transaction to ensure atomicity.

📞 2. Business Logic via Procedures

Trigger backend logic stored in ZIM procedures—like calculating discounts or validating credentials.

📁 3. Secure File Sync

Automate secure file transfers between client and server for compliance logs or audit trails.

📊 4. Dashboard Integration

Pull live data from ZIM into a Python-based dashboard using cursors and sets.

🧭 Summary

ZimAPI for Python is a powerful and developer-friendly interface that brings ZIM’s integrated database and automatic data set creation into your Python 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.