There are two different moments when dealing with Zim Server Connectivity:

1) The preparation of client database: this step is done only once and creates data definitions to allow the client database to “see” what is defined in the other Zim database and it is obligatory;

2) The preparation of remote database: the other database must know the existence of some objects referenced by the client. This step is optional;

3) The interaction with another Zim database: this the real activity that connects, interacts and disconnects with the other database.

The Preparation of the Client Database

The client database needs to know what is the information that is going to be “seen” from the foreign database, that is, which entity-sets, relationships and documents are going to be visible by the client application. In other words, the client database must define these objects in its data dictionary (as it would define any other object) as they were defined in the foreign database with a certain degree of variation. For instance, a field originally defined in the foreign database does not need to be defined in the client database (for safety reasons or because this particular field is not needed) or even the format of the fields can be a little bit different like define a CHAR in the foreign database and define a VARCHAR in the client database, provided that the differences are not conflicting.

It is a good practice, though, to define all objects in the client database as they are defined elsewhere. Normally, definitions at the client database are obtained by exporting the definitions from the original database. In this way, all definitions in both sides will always be the same.

To export and import definitions from one database to another, use the Export Wizard and Import Wizard from DC.

There is another information needed to be provided to the client database. If objects are all defined the same way (that is, local objects or remote objects), a distinction has to be made so that the client session knows where the information has to be handled. This is told by the EntType, RelType and DocType fields in the definition of entity sets, relationships and documents respectively. Normally, these fields contain the value “ZIM” which tells the client session that the corresponding object is local. If these fields contain “zimserv”, then the client session will deal with these objects as being remote objects located in the other database.

There are two ways of changing the fields EntType, RelType or DocType:

1) Using DC:

when editing the corresponding object, there is a field called “Table Type” for Entity Sets and Relationships or a field called “Document Type” for Documents. Select “zimserv” in these fiedls. In this way, the Data Dictionary definition of object is changed and the object itself is recreated. Programs referencing this object must be recompiled;

2) Using the command SET TABLETYPE:

This command changes the internal state of the fields but does not change the Data Dictionary definition nor recreates the object. Existent compiled programs must be recompiled. Since this command is very practical but does not properly document the actions taken, it is only recommended when testing or briefly executing particular procedures. For additional information, refer to SET TABLETYPE command.

The Preparation of the Remote Database

This step is only required if the client requests for interaction specify objects only known by the client database. For example:

FIND Customers WHERE Code = 12345

The remote database can normally execute this command because the objects Customers, Code and 12345 are all known by the remote database (we are assuming that the client database defined Customers with the EntType equals to “zimserv”) because Customers is an entity set, Code is a field of this entity set and 12345 is a constant.

However, the command:

FIND Customers WHERE Code = MyForm

cannot be executed by the remote database because MyForm is not known there (we are assuming that MyForm is a form defined only in the client database). In this way, the object MyForm must be imported from the client database in order to be known in the remote database.

To export and import definitions from one database to another, use the Export Wizard and Import Wizard from DC.

The Interaction Between Databases

Once the client and remote databases have been prepared, the client application can connect to the remote database, retrieve and/or update data located there and then disconnect from the remote database.

In essence:

1) Establish the connection between the client and remote databases via the command CONNECT, passing parameters that identify which database is the remote database and where this database is located (some other parameters can be provided like the user and password);

2) Issue normal ZIM commands to process the information needed. Internally, the client session proceeds this way:

a) the command is parsed in the client which determines that some objects belong to a remote database (EntType, for instance, provides this information);

b) in this case, the command syntax is sent to the remote database where is parsed and executed. Along with the command, are also sent values needed for form fields, variables, parameter to procedures, etc.;

c) all variables, forms, form fields and sets that were sent to the server in the previous step are returned to the Zim application with any updated values. Commands that generate output, such as LIST or REPORT, return their output to the Zim application that writes it to the current output document as if the command had been executed locally. System variables such as $setcount are updated in the Zim application to indicate the result of executing the command on the server.

3) Destroy the connection whenever is no longer needed via the command DISCONNECT. This step is optional because the connection is automatically destroyed whenever the client session is terminated.

When the command is parsed (as in item 2a), a special situation might happen when a Zim command references a mixture of local and remote objects as in the following example:

FIND Customers Issue Orders

where Customers is a remote entity set and Orders is a local entity set. In this case, the client session cannot send the statement as it is because Orders does not have data in the remote database but rather the client sends a sequence of SQL statements to retrieve values from Customers and then relate them to Orders. Efficiency, in this case, can be very compromised.

The Zim Database Agent Functionality

In many respects, the Zim Database Agent operates like any other client session as it reads a database dictionary, reads the same configuration options file, parses and executes commands, etc. There are some differences though:

. It is automatically spawned by Zim Server when a CONNECT statement is executed by the client session and cannot be started manually by a user;

. It is automatically killed by the DISCONNECT statement executed by the client session or upon the termination of the client session;

. Because it always runs in background, it does not process any user interface commands. Commands like FORM DISPLAY are ignored;

. Upon its initialization, it executes the SERVPROF file instead of the ZIMPROF file;

. Upon its termination, it executes the SERVBYE file instead of the ZIMBYE file;

Database Object Definitions

Certain rules apply to the definition of objects that are common to the client and the remote database:

• If an entity set or relationship in an application belongs to a Zim directory other than ZIM, then it must belong to a directory with the same name on the remote database or make use of the Remote Naming Feature (below). Also, the corresponding Zim directory must be accessed when the Zim Database Agent starts (see SERVPROF);

• A document, an entity set or relationships must have the same name on the remote database or make use of the Remote Naming Feature (below);
• At the remote database, you can define entity sets, documents and relationships that have no corresponding definition at the client. For example, such objects might be defined for use by local Zim applications only.
• Fields defined in the application must also exist in the corresponding object on the remote database; the names of entity set or relationship fields must be the same on the server or make use of the Remote Naming Feature (below). However, the order of fields and their types do not need to match (although, if different types are used, conversion errors might occur depending on the actual data values).

Remote Naming Feature

Normally, data dictionary definitions at the client side are the same as those at the remote database.

There are circumstances where names must be different in which case the definition at the client side can use the RemoteName or RemoteOwnerName. These two fields are defined in DC when the object is also defined and tell which name and Zim directory are the real names at the remote database.

For example, at the client side, an entity set is defined with the name MyCustomers belonging to Zim directory MyZimDir in order to access, at a remote database, an entity set called Customers defined in Zim directory called ZimDir. In this case, the definition of RemoteName or RemoteOwnerName at the client side must be:

EntName: “MyCustomers”

DirName: “MyZimDir”

RemoteName: “Customers”

RemoteOwnerName: “ZimDir”