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.

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

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.

The benefit of $serverfunction is the ability to code server functions that Zim does not support. Often there are similar functions in Zim and the server, but the mapping is not exact. As a result, the function is not present in the .sql file, forcing Zim to retrieve the entire table and evaluate the where clause on the client side. Sometimes functions are missing from the .sql file.

Users can code the equivalent server function instead of waiting for updates to the .sql file.

If $ServerFunction() is executed against a Zim table or with ExecuteMode set to ZimMode, the value returned by $ServerFunction is the value of the first argument.

ZimWeb Connection Architecture

Web applications can be implemented in Zim, using a Java Servlet program called ZIIServlet, provided as part of ZimWeb. A Java Servlet must be executed on a Java Servlet Container, such as Apache’s Jakarta Tomcat.

ZIIServlet works together with Zim Server to process requests from the client, whose interaction with the end user occurs through a web browser. In particular, request parameters (e.g. HTML form field values) are passed as parameters to a Zim program that is executed on Zim Server. That program is responsible for processing the request and constructing the response. Although the response can be sent directly back to the client, ZimWeb includes a variety of options for processing it.

ZimWeb communicates with Zim Server using TCP/IP. Zim Server and ZimWeb, can run on the same or different systems, provided that there is a network connection between the them.

The following diagram shows the basic components of a Web application using ZimWeb:

ZimWeb Components

ZimWeb is composed of four components: the ZIIServlet, the Java Servlet Container, the Zim Database Agent and a web browser.

Java Servlet Container

Also known as a Java Servlet Engine. An environment in which Java Servlets can be executed. Tests were done with Apache’s Tomcat, which is the official reference platform for Java Servlet Containers. A Java Servlet Container can be run independently, or it can be integrated with a Web Server. The ZimWeb Reference Platform includes Tomcat, but a variety of alternatives are available.

ZIIServlet

ZIIServlet is a Java Servlet. It can be loaded automatically by the Java Servlet Container when the first request is received, or alternatively it can be loaded in advance so that it is ready beforehand.

Zim Database Agent

The Zim Database Agent is part of Zim Server. It is a process that runs on a specific machine and accesses a specific database. ZimWeb can communicate with any number of databases on any number of database machines. However, a Zim Database Agent is always connected to a specific database.

Web Browser

Typical web browsers include Microsoft Internet Explorer on Windows, Safari on MacOSX and iOS, Chrome, Firefox and Opera on serveral platforms, from desktops to tablets and smartphones. The web browser is not supplied with ZimWeb. End users will connect to ZimWeb using any available web browser in their machines

XML Technologies

The following books will be particularly useful in explaining the XML technologies that are crucial to using the ZimWeb effectively:

• XML By Example (2nd Edition) and
  Applied XML Solutions by
  Benoit Marchal – these will give you a good overview of the XML landscape.
• XSLT Programmer’s Reference 2nd Edition by
  Michael Kay – this is the reference book for XSLT, though it is a bit “heavy” to get you started –
  XML By Example (2nd Edition) is a much gentler introduction. But he knows his stuff – he wrote the
  Saxon XSLT processor.
• XSLT by
  Doug Tidwell – he’s a “technology evangelist” from IBM.
• XSLT Cookbook by
  Sal Mangano
• XSL-FO by
  Dave Pawson.

Java

If you want to learn about Java then take a look at these books:

General Java programming

• Learning Java, 2nd Edition by Patrick Niemeyer and Jonathan Knudsen – a great introduction to the Java language.
• Java in a Nutshell, 4th Edition by David Flanagan, and Java Enterprise in a Nutshell, 2nd Edition by William Crawford, Jim Farley and David Flanagan – together, these provide a useful reference for the Java language.

Server-side Java programming

• Java Servlet Programming, 2nd Edition by Jason Hunter with William Crawford – this is a very clear exposition of server-side Java programming.
• Professional Apache Tomcat by lots of authors. This recently-published book is really helpful in trying to get the best out of the Tomcat servlet engine.

ML Processing with Java

• Java & XML, 2nd Edition by Brett McLaughlin – this is an excellent explanation of this topic.
• Java and XSLT by Eric M. Burke – another excellent O’Reilly book.

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