Installation

After the full ZIM installation, copy the file zimapi.py from the ZIM directory to wherever directory is needed to run Python.

Globals

No globals available for Python at this point.

Constructors

import zimapi
import os

zim = zimapi.Zimapi()
zim = zim.connect(dbname="database name"[, host="host address"][,port=port number][, user="ZIM"][, password = ""])
print(zim.state)
zim.close()

Alternatively:

import zimapi
import os

zim = zimapi.Zimapi(dbname="database name"[, host="host address"][, port=port number][, user="ZIM"][, password = ""])
print(zim.state)
zim.close()

The DATABASE NAME is obligatory.

The HOST defaults to “localhost” if omitted.

The PORT number is 6002 by default; if changed, it also requires changing a configuration option in the file zimconfig.srv located in the ZIM directory.

In the above code, the name ZIM is a generic name for the connection instance that is going to be used throughout this documentation.

Properties

state

The status of the last ZimAPI process executed. If zero, it was correct.

Methods

zim.execute(ZIM or SQL command)

Executes a ZIM or SQL command against the connected database, returning only the status of the execution. If zero, the command was executed successfully.

Example:

if zim.execute("DELETE 1 Customers WHERE CustCode = 1") == 0:
    print("Executed successfully.")
else:
    print("Error executing statement. Error Code is = " + str(zim.state) + ".")

zim.transaction()

Starts an explicit transaction against the connect database. Any statements executed afterward will be within the scope of an atomic transaction until a COMMIT or ROLLBACK is executed. In ZIM, all statements are executed with an implicit transaction (that is, an automatic transaction is started, the statement is executed and then the transaction is automatically committed or rolled back in case of an error), unless an explicit transaction would be started.

zim.commit()

Commits all updates occurred in the database while an explicit transaction was active and closes the transaction.

zim.rollback()

Rolls back all updates occurred in the database while an explicit transaction was active and closes the transaction.

result = zim.callproc(procedure name, arguments)

Invokes and executes a ZIM procedure passing parameters to it. If a parameter is a “?”, that indicates an output parameter, that is, the called procedure should return a value there.

Example:

args = ("12", 7, "?", "?")
res = zim.callproc(“MyProc”, args)
print(res[1] + res[2])

RES[1] and RES[2] indicate the first and second output parameters.

zim.putfile(source, destination, format)

Copies the SOURCE file located in your workstation to the DESTINATION place located in the server side using the proper FORMAT (either “/A” for text files or “/B” for binary files).

zim.getfile(source, destination, format)

Gets a file from the SOURCE location on the server machine and place it in the DESTINATION place locally with the specified FORMAT (either “/A” for text files or “/B” for binary files).

Cursors

ZimAPI cursors allow the retrieval of records from sets created by the execution of ZIM or SQL statements through a defined cursor (see the definition of SETS below).

A cursor can be directly or indirectly created:

cur = zim.cursor(ZIM command or SQL command)

The cursor is immediately created and is ready to be used. Example:

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

or

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

The cursor created by the above examples produce exactly the same results, that is, a set of up to 5 records (members) from the table (Entity Set) called CUSTOMERS.

cur.close()

Closes the created cursor.

cur.rowcount()

Indicates how many members the indicated cursor has available for retrieval.

row = cur.fetchone()

The first member of the set pointed by the cursor is fetched and place in ROW. The member number indicator is automatically set to the next member of the set so that a subsequent FETCHONE would fetch the second member and so on.

cur.rownumber()

Indicates the member number (the row number) currently available to be fetched.

cur.getname(index)

Get the name of the attribute referenced by the field index number.

cur.describe(field name)

Describes the field attributes of the referenced field name.

cur.scroll(amount)

Scrolls the set pointed the cursor in the AMOUNT of members (rows) which can be positive or negative, or the constants “TOP” or “BOTTOM” to move the current member to the beginning of the set or to the bottom of the set.

Sets

One of the most powerful features of Zim are the sets, or a logical collection of rows (records) from one or more tables. Sets are “views” of rows and persist during the whole connection or until recreated.

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

This statement creates a cursor over a set of maximum 5 rows from Customers and label this set as sCustomers. You can work on this cursor and close it but the sCustomers remain available for other operations like:

zim.execute("DELETE 1 FROM sCustomers")

Which will delete the first row from the sCustomers.