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.

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())...

Although Zim Technology has always made the best efforts to keep compatibility between versions, technical evolution is inevitable which leads to building bridges between one existing version to the next introduced version.

A brief history of Zim Technology and its migration possibilities:

1. Zim versions up to Zim 9.00: these versions may include Zim 4.x, Zim 7.x, Zim 8.20, Zim 8.50, and Zim 9.00. They are distributed by another company and are solely based on 32-bits platforms. According to its proper documentation, old versions can be migrated to newer versions using their own migration tools. If no technical evolution is required, such Zim databases can stay in Zim 9.00 for the time needed or until Zim 9.00 is available;
2. Zim 9.10 and Zim 9.50 (and upward): these versions are far more modern releases using a true 64-bit platform being produced and distributed by Zim-X Corporation, for Windows, Linux INTEL, Linux ARM, and Androids. The migration from Zim 9.10 to Zim 9.50 is transparent and automatic which only requires running the latest version on top of the previous one. However, the migration to Zim 9.50 from earlier versions like Zim 9.00 does require a more detailed step-by-step process, described below, due to their binary incompatibility and due to the more evolved capabilities of Zim 9.50.

Conventions

. OLD DATABASE: it’s the existing Zim database requiring migration;

. NEW DATABASE: it’s a Zim 9.50 ready to accept the migration from the old database or the one after such migration.

Warning

A) Migrate your Old Database to at Least Zim 8.50

If your database is not in versions Zim 8.50 or Zim 9.00, you will need to migrate to one of them (whichever is available to you), preferably Zim 9.00. This is a requirement because the differences between very old versions of Zim and Zim 8.5 or Zim 9.00 are big, big enough to make the conversion to Zim 9.50 impossible.

To perform this migration, you will need to follow the instructions provided by these Zim versions and the documentation provided by the distributor.

B) Export Data and Database Definitions From the Old Database

Once your old database is running either Zim 8.50 or Zim 9.00, you will export all database definitions and all data from the old database using the tools and utilities from the corresponding Zim version:

1. Start ZimServer;
2. Start a ZimQTC session to get the Zim prompt;
3. From the prompt, run “ZOMENABLE” to access the ZOM tools;
4. From the prompt, run “ZOMEXPORT *” to export all database definitions;
5. From the prompt, run “ZOMDATASAVE *” to export all existing data;
6. Kill ZimServer using the option “-k”.

To be on the safe side, back up your old database again to guarantee that files created in this process are saved.

C) Clean the Old Database

Certain files need to be deleted (removed) from the old database to make room for the new one:

1. Remove all files with the name “ZIMxxxx” where “xxxx” ranges from “0000” to “9999”;
2. Remove the operating system directories identified by “ZIMxxxx.WS”;
3. Remove the operating system directories identified by “yyyyy” where “yyyyy” ranges from “00001” to “99999”;
4. Remove the operating system directories named “DCRT” and “DPSRT”.

D) Install ZIM 9.50

Using the ZIM:X Full Installer, perform its installation on your computer following the installer guidelines.

E) Start ZimServer

After Zim 9.50 was installed, start ZimServer.

F) Create the New Database

Using the administrative tool ZimAdmin, you are going to create (initialize) the new database. From this point on, this database is going to be referred to as the “New Database”.

1. Run ZimAdmin;
2. Right-click on “Zim Servers”, select “Add Server…” and then click OK on the Add Server dialog box;
3. Click on the just added server (usually “localhost:6002”) and click OK on the Login Form. A (+) will appear on the left of the server;
4. Expand the (+) and right-click on “Databases” to “Create a Database”;
5. Provide a database name, a database path (it MUST be one you just cleaned), and a database number. Click “Create”;
6. Once you get a confirmation message, you are ready to go to the next step.

G) Import the New Database Definitions

This step will import all database definitions to the new database:

1. Start ZIMQTC on the new database;
2. Run “ZOMENABLE”;
3. Run “ZOMIMPORT” to import all database definitions.

Should errors arise during the import, carefully inspect these errors and decide:

1. The errors need to be corrected immediately: In this case, you will have to restore the database backup, correct the errors and then repeat steps B, C, E, F, G, and H;
2. If the errors are minor or could be ignored for the moment, proceed to the next step.

H) Import all Database Data

Run the following steps after importing the database definitions:

1. Copy (save) the operating system directory “ZOMSAVING” to “ZOMSAVING.SAVE” which is located in the database. This copy is important; otherwise, the database data will not be imported;
2. Run “ZOMDATASAVE *” to create the structure to load the data. It will process zero records for all entity sets;
3. Remove the operating system directory “ZOMSAVING”;
4. Copy back the saved directory “ZOMSAVING.SAVE” to “ZOMSAVING”;
5. Run “ZOMDATALOAD *” to import the database data.

Warning: Zim versions up to Zim 9.00 weren’t able to correctly export data. In particular, the presence of new lines in the middle of text fields would produce errors and omissions. These errors need to be investigated and, probably, the new lines fixed before exporting the data in step E.

Another potential error is the inability to recognize entity sets per user which leads to import errors. There is no sense in exporting and exporting data from entity sets per user and these errors can be ignored safely.

I) Final Checks

The migration process to ZIM 9.50 is now completed. You may still perform the following tasks:

1. Stop ZIMSERVER with the option -k;
2. Make a backup of your new database;
3. Start ZIMSERVER again along with ZIMQTC;
4. Compile your ZIM programs if applicable;
5. Check your data and your database definitions;
6. Run your application.

Zim provides DDE services for applications through the function $DDEFunction. These DDE services include the ability to send data to another application, retrieve data from another application, and pass commands to another application. While you can write your own implementation of $DDEFunction, Zim provides a standard implementation in the form of a Dynamic Link Library (DLL) and several Zim programs that provide an easy-to-use interface to the services of the DLL.

Using the DDE Services Provided by ZIM
The actual name of the DLL accessed by $DDEFunction is defined by the DDEFUNC entry in the registry. If you do not have a DDEFUNC entry, the name of the DLL is assumed to be z32dde.dll and the file is assumed to be in the same directory in which your Zim software was installed. Upon Zim installation, the registry value of DDEFUNC is not set because Zim automatically assumes the required values on its absence.

Using Special DDE Services Provided by the User

If you want to use your own special DDE services support, you must build a DLL that follows the same standards as any $UserFunction and set the DDEFUNC registry like this example before starting your Zim for Windows session:

DDEFUNC=C:\MYCODE\MYDDE.DLL

Invoking the DDE Services
The standard DDE services provided by Zim can be accessed in two ways:

through the set of Zim programs that provide an interface to the DDE DLL (z32dde.dll)
by calling $DDEFunction directly (always referencing z32dde.dll)
These two ways distinguish from each other from the fact that the Zim programs are easier to deal with because they provide all error handling and parameter checking and converting. On the other side, the $DDEFunction usage can provide more flexibility but requires more attention from the programmer.

Invoking the DDE Services

Invoking the DDE Services Through the Zim Interface Programs
Your Zim installation provides a set of Zim programs as a means of an easy interface to DDE services. These programs are located in the $DeployServices directory that must be accessed via the command prior to any reference to these programs:

access $DeployServices

The programs are all compiled, but the corresponding source code is located in the operating system directory “dpserv/dpsdocs”. They implement five different operations against the DDE services as follows:

DDEConnect, which connects to the desired service;

DDEExecute, which executes a specific operation on the service;

DDEPeek, which gets some value from the service;

DDEPoke, which sets any values to the service;

DDEDisconnect, which disconnects and ends to conversation to the service.

Please refer to the corresponding documentation of each of these commands for more details.

Syntax

Invoking the DDE Services Directly Through $DDEFunction
The DDE services can be accessed by invoking the Zim function $DDEFunction directly. $DDEFunction is invoked with the syntax

$DDEFunction ( p1, p2, p3, ... )

where p1, p2, and so on, indicate the desired DDE service and the data required by that service. Specifically, p2 passes the desired operation to be performed against the DDE services. The operations are exactly the same as those provided by the Zim Interface Programs.

See Also

$DDEFunction

Preparing the Database for ODBC Access

Start up the Development Center (DC) and click Tools -> Remote Access -> Prepare Database.

This action runs a script that populates the metadata entities that are used by non-Zim applications to acquire EntitySet information.

In addition to installing Zim and modifying your UNIX operating environment to accommodate the Zim software, you must also set the environment variable “SQLCPI” to represent the directory for SAM files.

To define SQLCPI, enter the following command if you are running the Bourne or Korn shells:

SQLCPI=/usr/zim; export SQLCPI

where zim is the directory where you installed the Zim SAM.

If you are running the C-shell, enter the following command:

setenv SQLCPI /usr/zim

Before you run Zim, ensure that the location of the Zim software is included in the UNIX PATH environment variable. If you are running the SQLDif utility, ensure that the location of the SQLCPI import and export utilities are included in the UNIX PATH environment variable as well.

Note:This topic assumes that your current PATH includes the directories /bin and /usr/bin.

To add /usr/zim to your PATH in the Bourne or Korn shells, enter

PATH=/bin:/usr/bin:/usr/zim

In the C-shell, enter

set path = ( /bin /usr/bin /usr/zim)

You can also add these commands to your login script so that they are automatically executed each time you log in to your system.

ZIIAdmin servlet is ZimWeb‘s administration tool. It can be used to manage ZimWeb either from the web or from a command line or script, which can be scheduled.

Web Administration

If you invoke the ZIIAdmin servlet from a web browser, you will see a page with various parts under different headings:-

Command line or scripted administration

The ZIIAdmin servlet can also be invoked from the command line or by a script. The servlet itself requires two parameters:

✓ action – set to indicate what query or action the servlet is to perform. Permitted actions include:

  ✓ conn-status – return the status of the Zim Database Agent connections.

  ✓ conn-start – attempt to start the Zim Database Agent connections.

  ✓ conn-stop – attempt to stop the Zim Database Agent connections.

  ✓ debug-status – return the debug capability status.

  ✓ debug-enable – enable the debug capability.

  ✓ debug-disable – disable the debug capability.

  ✓ clear-style-cache – clear the XSLT stylesheet cache.

  ✓ clear-page-template-cache – clear the page template cache.

  ✓ reset-xslfo-driver-pool – reset the XSL/FO driver pool.

✓ content – set to text so that the servlet will return plain text instead of HTML.

CallURL utility

To enable the ZIIAdmin servlet to be called from the command line or a script, ZimWeb includes the CallURL utility to enable calls to a URL, with BASIC authentication details, if necessary.

The full syntax for CallURL is:

java -cp /zii.jar biz.zim.util.CallURL [ ]
to invoke the URL , optionally with BASIC authentication for user and password .

For example: To start the database connections on a local running ZimWeb installation or a default Tomcat installation, if the ZimWeb file zii.jar is in the current directory, and the ZIIAdmin servlet has security requiring the username admin and password friend, you could use the command:
java -cp zii.jar http://localhost:8080/ZII/servlet/ZIIAdmin?action=conn-start&content=text admin friend

If you are using Tomcat, and have installed the ZimWeb in the manner described in the installation instructions, then the servlet configuration (servlet initialisation parameters) will be in the web.xml file in the [TOMCAT_ROOT]/webapps/ZII/WEB-INF directory. If you are using a different servlet engine, then you will have to consult its documentation to see how to configure it.

Here are the configuration parameters, organized by function type:

Configuration File Extensions