Category: ZIM User Documentation

Zim Client-Server uses the SQLCPI variable to find the SAM module and the utilities used to import and export objects. Under Windows, the SQLCPI variable is set in the Windows registry and is set to the directory where the SAM software is installed.

When running Zim on Windows, ensure that the registry variable SQLCPI  is set properly.

Verify that the SQLCPI registry variable has been set properly from within Zim by outputting the $SQLPath system variable, as shown below:

> output $SQLPath
c:Zim

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.

The Import/Export functions of the Zim Development Center application provides support for the import/export and translation of database object definitions between the Zim and SQL server environments. In particular, Zim EntitySet and data relationship definitions can be exported to the SQL server to create corresponding tables and indexes. Additionally, SQL table definitions can be extracted from the server’s catalog tables, translated, and delivered into the Zim environment as members of the “Fields” EntitySet which is part of the Zim Data Dictionary.

While you are using the import or export facility of the development center, do not be explicitly connected to the SQL Server. Both facilities connect and disconnect from the SQL Server as needed.

This option is used to import table definitions from the SQL server and to translate them into equivalent Zim definitions. To import SQL definitions into Zim, select the Tools/Import/Objects/From SQL option from the development center main menu.

The SQL Definition Import window appears. On this window, choose the ODBC Server as the server from which to import. Next click the “Fetch Def’n” button.  The Server Parameters window appears. The connection parameters are identical to parameters 2 through 7 of the “CONNECT” command. The SAM uses these to access the correct database. Refer to Connecting to SQL Servers for information on how to supply the correct values for these items. (Note that while these utilities connect to the SQL database, they do not connect Zim to the database.) The “Table Owner Name” field can be used to denote the owner of the tables which Import retrieves definitions. Note that the column definitions for all tables owned by “Table Owner Name” are retrieved. If the table owner name field is left blank, Import retrieves all table definitions which are available to the user.

If the check box to the left of the table name is selected when the “Import” button is selected, that table’s column (field) definitions are imported into Zim. By default all tables are flagged for import. Use the “Deselect All” button to clear all check boxes. The “Select All” button selects all check boxes. If more than 30 table definitions are retrieved, you can scroll forwards and backwards through the table name. SQL table definitions that you select to import are added by ZOM. All tables are added as EntitySets with the enttype set to the name of the selected SAM. Imported SQL table definitions do not have any index information. The “index” field for all imported SQL fields always has the value ‘NO’. You have to modify the imported fields to indicate any indices that you wish Zim to maintain.

The export facility is used to translate Zim definitions for entity sets and/or data relationships and create them on the designated SQL server. The definitions of the resulting tables (with associated indexes) correspond to each exported Zim EntitySet or data relationship definition. The Zim definitions to be exported are selected from the EntitySets and Relationships and their associated Fields that are in your database. The selected objects to be exported are grouped according to their Remote Owner Name field in EntitySets and Relationships and a complete export cycle is accomplished for each different Remote Owner Name.

In a Zim Client-Server application, all EntitySets and data relationships should have at least one unique index defined on a field or virtual field. Limitations of SQL require that if the unique index is on a virtual field, then the field expression must be

$concat(field1,field2,…)

where “field1”, “field2” are the names of real fields only. They cannot be expressions or other virtual field names. An error occurs during the export process if an attempt is made to export an indexed virtual field whose expression does not abide by this rule. See Exporting Zim Table Definitions for more information on this subject.

To export Zim table definitions to the server, choose the Tools/Export/Objects/To SQL option from the main menu of DC. The SQL Export Definiton window appears. Choose the server to which you wish to export the definitions by selecting it from the “Export selected items to” list box. The names of the EntitySets and data relationships in your Zim database are listed. (If more than 30 table definitions exist, you can scroll forwards and backwards through the table names.) To the left of each table name is a check box. Clear the check box if you do not wish to export the definition to the server. Selecting the “Deselect All” button clears all check boxes and selecting the “Select All” button selects all boxes. Initially, all entries have their check boxes selected.

Also appearing on this window is the Replace Existing Table check box. If this box is selected, Zim attempts to DROP each table on the server before it creates it. Hence, selecting this box unconditionally replaces each existing table definition. By clearing this check box, the server generates an error if the table already exists and no new table is created. Therefore to guard against the accidental replacement of a table definition, clear this box. If the box is selected and the table does not exist, the server generates a benign error.

By clearing this check box, the server generates an error if the table already exists and no new table is created. Therefore to guard against the accidental replacement of a table definition, clear this box. If the box is selected and the table does not exist, the server generates a benign error.

The “CREATE TABLE” syntax for a specific SQL server can optionally include additional syntax which relates to the physical storage characteristics of the created table. This syntax varies widely from server to server. If the specification of some or all of the optional physical table characteristic parameters is desired, enter the appropriate syntax in the field “Physical Table Characteristics Syntax:“. The syntax specified is appended to the “CREATE TABLE” statement for each name entered in the form. For example, entering “TABLESPACE ts_account” ensures that the table is created in the “ts_account” tablespace.

Another way to change characteristics is to check the “Modify SQL Definitions” check box. This options brings the resulting SQL definitions through the default text  editor for editing. Edit the definitions you want to apply and save the text. The export then proceeds.

To export those EntitySets and/or data relationships selected, click the “Export” button. The table definitions are translated to the appropriate “CREATE TABLE” syntax for the selected SAM and the output is written to a file. Next, the server parameter dialog box appears. Values for these items are required so that the utility program “SQLEXEC” (which the DC invokes) can access the appropriate database in the SQL server in which to create the tables. SQLEXEC in turn invokes the “Server Interface Module” of the selected SAM. These items are identical to parameters 2 through 7 of the “CONNECT” command. Refer to the Connecting to SQL Servers topic for information on how to supply the correct values for these items. Although these values are used to connect to the SQL database, Zim itself does not need to be connected to the database.

With the appropriate values supplied for these items, the export process proceeds to execute a general purpose SQL statement executor program “SQLEXEC”. SQLEXEC traces the SQL statements that it is executing as well as any error conditions that are detected. It does not stop executing on an error condition. In general, the only error condition that is acceptable is an error from the “DROP TABLE” statement when the table does not already exist. All other error conditions should be investigated. A common error is attempting to create an SQL table with a name beginning with the underscore (“_”) character. This is legal in Zim, but generally not legal in SQL.

DB2 provides support for three levels of multiple user concurrency control. These isolation levels select the extent to which database operations performed by one user are isolated from concurrent operations performed by other users.

“Repeatable Read” isolation level means that locks are held on all rows read or updated by a user for the duration of the current transaction (or logical unit of work). At this isolation level, if a row is read at some time and at a later time during the same transaction is re-read, the row still contains the same data values. That is, within a transaction, a read of a row is “repeatable” with identical results.

“Cursor Stability” isolation level means that within a transaction, locks are held only on the most recently read row or rows. Were a row that had been previously read within a transaction to be re-read, there is no guarantee that it returns the same column values as previously as another user could have updated the row in the meantime.

“Uncommited Read” isolation level means that within a transaction, rows that have been updated by one user can be read by another user and the reading user sees the updated values. The updating user may later decide to cancel the transaction, in which case the reading user would have retrieved (and possibly made decisions based on) data that is no longer stored in the database.

In general, the cursor stability isolation level is appropriate. However, in cases where updates are being performed on tables that are being related to themselves (reflexive relationships), the repeatable read isolation level should be selected, as it is highly probable that previously read rows will be re-read.

Zim can manipulate and retrieve data from third-party data sources as well as from a Zim database. Client applications for SQL database servers are designed and developed as complete Zim application systems. The objective of the Zim product is 100 percent source code portability of applications including seamless access to databases being managed by SQL relational database management systems (SQL servers) supplied by independent vendors. In fact, a Zim Client-Server database application can consist of an arbitrary mixture of tables managed by an SQL server and entity sets and relationships managed by Zim.

As an architectural model, client-server architecture consists of two components: a server process and a client process. A server process provides services to client processes, whereas a client process requests services from a server process.

A database management system is a server process that provides database access and update services to application programs (client processes). Any application program that issues database requests to a database management system is a client-server database application. The database server can be on the same machine as the application program, it can be a database server on a local area network; or it can be on a host machine with access through a gateway. In all cases, the application program is acting as a client and the database management system is acting as a server.

In order to use the client-server capabilities of Zim, two software components are required:

Zim software

The JDBC SAM (Server Access Module) which makes a “bridge” between the Zim application and the specific SQL database server in use. Any SQL database servers available in the market allow the JDBC connection, both in 32 or 64 bits.

A Zim Client-Server application can be developed as a stand-alone standard Zim application on any supported platform. Once developed, the application can be moved easily to another platform and configured to access remote data sources. Because of this capability, Zim enables you to separate your application from the ultimate data source, enabling development to be done independently of the target database management system or platform. Zim lets you perform application development and testing off-line on a stand-alone PC, a portable, or a workstation and then implement the production application on a Zim database, an SQL database, or a combination of both. This reduces the demands on your environment, including your SQL database. This portability lets you perform your development and testing on one hardware platform and implement as a client application on a completely different platform.

Zim applications can process data stored in more than one location. Database servers often become performance bottlenecks because data is located in one area and the server cannot handle the processing load for that data. Zim avoids this bottleneck by letting you distribute or partition data elements across both the database server and the Zim databases. This gives you the power to balance the load on your network. By off-loading data from your server, Zim boosts performance by lowering server demand.

Client-Server database application development with Zim provides application portability to database servers. An application written for a particular server can be migrated to another server without changes to the application. Zim portability lets you adopt new technologies as they emerge.

Zim lets clients on different platforms run the same application against the same database server concurrently. Clients can be moved to other platforms.  The client platforms for an application can be mixed and matched, as required.

Zim provides a universal interface to database servers. Zim still enables you to access the unique features and strengths inherent in any database server by taking advantage of proprietary extensions of the SQL dialect. Zim syntax supports any SQL database in an optimal way.

Zim enables you to test your applications interpretively, without compiling first.

The return value of $DDEFunction is one of the following. A negative result indicates failure.

Windows

Zim Server can be started manually from the Start menu, or the Startup folder.

You can also start the process from the command prompt:

start zsvserv.exe [-p <port number> | -s <service>]

This command starts Zim Server in its own console window. The -p option sets the port number on which the server is listening. The -s option does the same thing, but here you enter a service name. The server uses this name to retrieve the port number from the services file.

Linux/UNIX

The Zim Server process can be started manually or it can be invoked from a system start-up script. This process is started by the command zimserver, that is installed in the directory pointed to by the ZIM environment variable. You should start the process with the command line:

nohup zimserver [-p <port number> | -s <service>] &

Note: The same command line could be placed in a system start-up script.

Using NOHUP means that you can log off from the current session and the Zim Server process continues to run. Using ‘&’, means that the Zim Server process runs in the background and that you can continue to enter commands at your terminal. Output from ZIMSERVER and the Database Agent process that would normally go to the terminal are rerouted by NOHUP to a file called nohup.out in the current directory. This file normally contains lines showing that the Zim Server process has begun and ended. It also contains any terminal output from a Database Agent processes started by the Zim Server. It is not necessary to retain the contents of this file and you should occasionally check the size of nohup.out and delete it if necessary.

The -p option sets the port number on which the server is listening. The -s option performs the same function, but using the -s option requires that you enter a service. The server uses this name to retrieve the port number from the services file.