Execution Error Conditions
The execution environment of a Zim client-server application involves products from more than one vendor. This can introduce the potential for additional error situations. For example, if the parameters to the connect command are not specified correctly for the particular installation of the SQL server being used, then the connect command fails and returns an error code. If the initialization or execution environment requirements of a specific SAM have not been properly established, errors can be generated. The following topics address the types of error conditions that can occur and how they are handled.
The Deadlock Error Condition
Because Zim Client-Server applications are implicitly multi-user, the deadlock error condition can occur in an otherwise properly executing application. Each Server Access Module (SAM) detects the deadlock error condition from the SQL server it supports and translates the error into a Zim deadlock “$ ErrCode” value 2010. Accordingly the “ON DEADLOCK” exception handler can be used to handle deadlock conditions in a manner appropriate to the requirements of the application.
For more information, see Multiple Locking.
Errors from SQL Servers
Some SQL servers generate return codes distinguishing between error and warning conditions. If a server supports this distinction, then the “$ErrCode” reflected to the Zim Client-Server application also distinguishes between errors and warnings. Hence, the Zim “ON ERROR” and “ON WARNING” exception handlers can be used.
If the server does not support such a differentiation, then a Zim error condition is generated into “$ErrCode”.
In either case, $SQLErrCode contains the actual SQL server error code and $SQLErrMsg contains the SQL server error message.
SAM Errors
SAMs have their own error codes. These error codes are in the -100000 range and are very rare. Some, however, are reported by Zim; the most likely ones are as follows:
| -100012 | The control file cannot be found. Ensure the SQLCPI environment variable points to the proper directory. |
| -100013 | Ensure the SQLCPI environment variable is pointing to the correct directory. Â Ensure the control file (i.e., odbc2m.cpi) contains the appropriate record. |
| -100023 | Attempts by Zim to access the SAM have failed. Lack of memory is the likely cause. |
| -100037 | Connect has failed. Check the CONNECT parameters. |
| -100047 | Incompatible version numbers have been detected. Check that your SQLCPI variable is pointing to the correct directory, as it could accessing an out-of-date SAM. |
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.
The application is compiled using the “compilemode” option “sqlmode” and conversion to a Zim Client-Server application is complete.
If the application is to be developed for execution against a pre-existing SQL server database, then the Zim application should be compiled using the “compilemode” option “zimmode” to test the application for functionality and performance. Then the application can be compiled using the “compilemode” option “sqlmode”. If the application is being compiled in the default “sqlmode” with the sqlcompile setting “on”, then you must be connected to the SQL server.
In order to access relational databases, Zim client-server generates SQL statements. You can see the statements generated by setting SQLTRACE on. Statements are generated when Zim statements containing references to SQL tables are parsed, compiled, or executed interpretively. Previewing the SQL statements generated provides an insight into the type or amount of work the database is going to be doing. This option is set using the command:
set sqltrace [on | off]
The default setting for SQLTRACE is OFF.
Zim is capable of executing database commands in either of these three modes:
| SQLMODE | SQL mode |
| SERVERMODE | Zim Integrated Server mode |
| ZIMMODE | Standard Zim mode |
The default mode of operation is SERVERMODE. For all database servers except Zim Integrated Server, SERVERMODE and SQLMODE behave identically. In SERVERMODE, a Zim client accessing tables on Zim Integrated Server sends Zim commands to the server instead of SQL commands which greatly improves performance. In SQLMODE, the ZIM client determines the optimal SQL syntax to send to the server by inspecting the values for “EntType” or “RelType” in the Object Dictionary for the tables specified in the command.
The mode in which Zim operates may be set by the command:
SET EXECUTEMODE [ SERVERMODE | SQLMODE | ZIMMODE ]
where SERVERMODE is the default setting. For example, if the command:
set executemode zimmode
were executed, then Zim would revert to executing standard Zim code. If the program had been compiled in SQLMODE, it would revert to interpreting the program source file but issue error and warning messages.
Zim generates SQL statements to access entity sets and relationships that are stored in relational databases. To execute these statements (i.e. your application), you must be connected to the relational database. In order to support “off-line” development Zim enables you to turn off SQL statement generation, in effect generating standard Zim code. Zim ignores “EntType” and “RelType” and considers everything to be under Zim’s control. This enables you to develop and maintain applications without connecting to the database. In fact, development can proceed independent of the particular database vendor.
A dynamic configuration setting called "block factor" can be used to tune performance. This factor is the number of records retrieved by Zim each time it fetches records from the database. The larger the number, the fewer times Zim has to query the database, and the more time it takes to retrieve a block. So, the number must be adjusted to an appropriate value and not one that is arbitrarily large.
Continue reading “Block Fetching”
The “SET SQLCOMPILE” Command
Zim is designed to take advantage of many characteristics of a given SQL server. Many SQL servers provide compile time facilities to increase performance at runtime. A compile time option enables you to control when the database server does certain compilation functions such as statement parsing. If SQLCOMPILE is OFF, then these functions are performed at Zim’s runtime. If SQLCOMPILE is ON, these function are performed as Zim compiles the application, if possible. This option is set using the command:
SET SQLCOMPILE [ ON | OFF ]
The default setting for SQLCOMPILE is OFF.
In order to take advantage of these facilities, you must be connected to the SQL server at compile time. If this option is turned off, all work is done at run time and you do not have to be connected at compile time.
Different applications being compiled against the same SQL server database can have programs with the same name (i.e. “MAIN”). To avoid conflicts that can arise when compiling several applications against the same SQL server database, each application should be flagged with a unique identifier. The “config.zim” entry is
SQL DATABASE NAME xxx
where “xxx” is a three-character ID. Zim makes use of this ID when compiling. It should be noted that SQLCOMPILE can be turned on or off for a single statement if desired.
English 
Portuguese