Category: ZIM User Documentation

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.

Installation

After the full ZIM installation, copy the file zimapi.cs from the ZIM directory to wherever directory is needed to start developing your C-Sharp application.

Globals

TOP = indicate the first tuple (row or record) from a set of records
BOTTOM = indicate the last tuple (row or record) from a set of records
UTF8 = indicate a UTF8 Zim database
ANSI = indicate a ANSI Zim database
NO_ERROR = No errors

Constructors

using ZimConnection;

ZimAPI Conn = new ZimAPI();
Conn.Connect(dataBase, hostName, portNum, userName, passwd);               
System.Console(ZimAPI.State);
Conn.Close();

Alternatively:

using ZimConnection;

ZimAPI Conn = new ZimAPI(Database Name, Host Name, Port Number, User Name, Password);               
System.Console(ZimAPI.State);
Conn.Close();

The DATABASE NAME is obligatory.

The HOST NAME 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.

The USER NAME defaults to “ZIM”, if omitted.

The PASSWORD defaults to “”, if omitted.

Properties

int State;

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

Methods

int Conn.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 Conn.Execute("DELETE 1 Customers WHERE CustCode = 1") == 0
    System.Console("Executed successfully.");
else:
    System.Console("Error executing statement. Error Code is = " + str(zim.state) + ".");

int Conn.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.

int Conn.Commit();

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

int Conn.Rollback();

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

string Result[] = Conn.Callproc(procedure name);

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:

Result = zim.callproc(“MyProc(\"12\", 7, \"?\", \"?\")”);
System.Console(Result[1] + Result[2]);

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

int Conn.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).

int Conn.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).

string Conn.ErrorMessage();

Returns the last error message found by Zim.

int Conn.ErrorCode();

Returns the last Zim error code found by Zim.

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:

ZimAPI.ZimCursor.MyCursor = Conn.Cursor([ZIM command or SQL command]);

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

MyCursor = Conn.Cursor("FIND 5 Customers");

or

MyCursor = Conn.Cursor();
MyCursor.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.

int MyCursor.Close();

Closes the created cursor.

int MyCursor.RowCount();

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

string MyCursor.FetchOne();

The current member of the set pointed by the cursor is fetched and made available for further processing. The member number indicator is automatically set to the next member of the set.

int MyCursor.RowNumber();

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

string MyCursor.ValueOf(field name);

Gets the value of the FIELD NAME as defined in the database repository. This value corresponds to the record (tuple or row) retrieved by the last FetchOne method.

string MyCursor.ValueOf(field index number);

Gets the value of the FIELD INDEX NUMBER as defined in the database repository. This value corresponds to the record retrieved by the last FetchOne method.

string MyCursor.GetName(field index number);

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

int MyCursor.FieldCount();

Provides the number of fields existing in the current record.

int MyCursor.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.

MyCursor = Conn.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:

MyCursor.Execute("DELETE 1 FROM sCustomers");

Which will delete the first row from the set called sCustomers.

ZIM’s Auxiliary Relationships are predefined relationships to associate Data Dictionary objects thus speeding Zim applications development.

The Predefined Relationships

Remarks

When a new Zim database is first created, the above auxiliary relationships are also automatically created to be used in Zim development.

Example

To find all fields belonging to the entity sets “Customers” and “Invoices”:

find Ents EntFields Fields where Ents.EntName in ("Customers", "Invoices") -> sMySet

Check whether there are any relationships with fields:

find Rels RelFields Fields
if $SetCount = 0
    out "No Relationships with Fields"
endif

Indicates whether errors raised during a Zim session have to be written to the corresponding error trace file or not.

error trace yes/no

where yes indicates that all errors must be written to the error trace file up to the limit specified by the Maximum Error Trace Size configuration option.

Remarks

Although it may save some disk space, avoiding error printing may lead to undetected error situations. Errors and warnings are raised for a reason and well-behaved Zim applications would seldom raise errors. Therefore, it’s a wise recommendation to leave this option as yes (the default setting) and to check the error files from time to time for existing errors or warnings.

Valid Settings

The default value for all operating environments is yes.

A numeric code indicating the “class” (field or widget type) of the associated form field.

Valid Values

WdgType = {30 where FT = “0”, 31 where FT = “1”,

A numeric value ranging from 1 to the maximum available widgets according to the table below:

Differences from Zim:X distributed by The SmartCone Technologies Inc. and all Zim versions up to Zim 9.00 distributed by Zim Databases Inc.:

Introducing the JSON processing via the functions $GetJSON and $FindJSON.

Zim:X is full threaded 64 bits in all available platforms.

The commands WINDOW OPEN, WINDOW MOVE, WINDOW SIZE now refer the position and size in pixels.

In the entity set Forms:

• Removed the no longer used TUI attributes Wdth, Hght, HMargin and VMargin;

• Removed the currently not used attributes (they will be implemented in the future) WdgHMargin and WdgVMargin;

• Removed invisible indexes NullDirName and NullObjectKey.

In the entity set Displays (Disps):

• Removed the no longer used TUI attributes Wdth, Hght, HMargin and VMargin;

• Removed the currently not used attributes (they will be implemented in the future) WdgHMargin and WdgVMargin;

• Removed invisible indexes NullDirName and NullObjectKey.

In the entity set DisplayForms (DFS):

• Removed the no longer used TUI attributes Wdth, Hght, HMargin and VMargin;

• Removed the currently not used attributes (they will be implemented in the future) MenuType, WdgClass, WdgSubClass, WdgStyle, WdgRow, WdgCol, BC, FC, WdgBackground and all 6 references to RGB colors;

• Removed invisible indexes NullDirName and NullObjectKey;

• Added the attribute WdgCSS to accept ad hoc information as they become available.

In the entity set Menus:

• Removed the no longer used TUI attributes Row and Col;

• Removed the currently not used attributes (they will be implemented in the future) MenuType, WdgClass, WdgSubClass, WdgStyle, WdgRow, WdgCol, BC, FC, WdgBackground and all 6 references to RGB colors;

• Removed invisible indexes NullDirName and NullObjectKey;

• Added the attribute WdgCSS to accept ad hoc information as they become available.

In the entity set FormFields (FFS):

• Removed the no longer used TUI attributes Row, Col, Wdth, Hght, Fill, HMargin and VMargin;

• Combined the fields FC, BC and all 6 references to RGB colors to two attributes called WdgFCColor and WdgBCColor;

• Combined the attributes IT, TE, WdgModified, WdgClick, WdgDblClick into an attribute called WdgCallbacks;

• The attribute FT (FieldType) was converted from a CHAR(1) to INT and renamed to WdgType because FT could no longer hold new widget types;

• The attributes WdgOnValue, WdgOffValue, WdgNullValue, WdgOnImage, WdgOffImage, WdgNullImage, MinValue, MaxValue, WdgLargeIncrement and WdgSmallIncrement were removed as separate attributes and placed into WdgCSS when they appear in some widget types;

• Removed the currently not used attributes (they will be implemented in the future) WdgDragMode, WdgDropTarget, WdgPointerStyle, WdgHMargin and WdgVMargin;

• Removed invisible indexes NullDirName and NullObjectKey;

• Added the attribute WdgCSS to accept ad hoc information as they become available.

#pip3 -> python 3.9
# - Instalar com pip3
#pip3 install JayDeBeApi --user
#pip3 install JPype1==0.6.3 --user

import jaydebeapi

#variables to connect to zimjdbc8.jar


jclassname='zim.jdbc.ZJ_Driver'
jdbc_driver_loc = r'C:\Users\xxx\Documents\p01\zimjdbc8.jar'
jdbc_driver_name = 'zim.jdbc.ZJ_Driver'
host='localhost:6002'
#url and login variables
url='jdbc:zim://' + host + '/zimdb01'
login="ZIM"
psw=""

#sql to be executed at the Zim's side.
sql = "SELECT codie, name from test"

#connection to the JDBC driver
conn = jaydebeapi.connect(jclassname=jdbc_driver_name,
url=url, 
driver_args=[login, psw],
jars=jdbc_driver_loc)
#open the cursor
cur = conn.cursor()
#execute the SQL statement
cur.execute(sql)
#print the result 
print(cur.fetchall())...

The callback events an object can raise.

Valid Values

An integer code combining the following values:

Remarks

Only resizable windows can have menus.

Example: If the object has to raise a GotFocus event and a Click event, the WdgCallbacks would contain (2 + 64) = 66.

Provides extra information about the object being used.

Valid Values

A character string, up to 512 characters long either blank or in JSON format.

Remarks

The WdgCSS values for the objects involved present either a blank value or a free-format JSON syntax containing additional information about the object. This extra information may be Data Dictionary fields valid only to the particular object or implemented for future use.

Example

{"icon": "c:/images/zx.ico", "smallincrement":30}

ZIM:X allows JSON data format to be retrieved by the means of the $FindJSON function if the above value would be stored in FFs.WdgCSS:

LIST FFs FORMAT $FindJSON(WdgCSS, "smallincrement")
30

See Also

$FindJSON

The “appearance” of an object.

Valid Values

An integer code combining the following values:

Remarks

Only resizable windows can have menus.

Example: If the window has a caption, is resizable and has a close button, the value would be (1 + 2 + 16384) = 16387.