Category: ZIM-X Database Connectivity

In Client-Server applications, you do not have to do anything special to access or manipulate data stored in the SQL database.

Using Per User Entity Sets

Even though per user entity sets are private and only seen by the user that created them, they can still be available to an ODBC Driver connection by means of the Dynamic Creation of a Data Source, which informs the work path that contains the per user entity sets. When the third party software connects to the corresponding Zim database, the per user entity sets are handled in the proper way as though they were local to this connection.

In order for the ODBC Driver connection to properly “see” the data in the per user entity sets, the third party software must be invoked within the Zim session that created the per user entity sets and their corresponding data.

Invalid results will be achieved if the ODBC Driver connection is established:

. before starting the Zim session that will create the data and the proper connection;

. before creating the data, but within the Zim session;

. after ending the Zim session that created the data and the connection.

 

Page Templates

fbarbosafbarbosa112003-01-24T16:51:00Z2003-01-24T16:53:00Z32711549ZIM Technologies12319029.3821

Page Templates

ZimWeb includes page template support. This allows you to combine parameters from Zim with the page (web page, etc.) delivered to the client.

Template file format

A page template is just a regular page (HTML etc.), with parameter placeholders to indicate where each parameter to be supplied by the Zim application is to be placed. This template can be designed easily with your normal web page design tool.

 

The parameters placeholders are formatted like HTML comments (e.g. so for a parameter named company you would use a parameter placeholder ).

 

Note: the parameter and the parameter placeholder must be in the same case.

 

The page template processor will substitute the value of the parameter for the parameter placeholder. If the value of a parameter in a placeholder is not supplied, its value will be assumed to be blank. You can use the same parameter placeholder more than once in a given template.

Sample template customer.htm


 
  

Customer Details

  

   

    

    

   

   

    

    

   

  

Customer Code
Customer Name

 

Parameter XML format

The Zim application supplies the values of parameters in an XML format.

The root element can have any name. The parameter names are the names of the elements which are children of the root element. The character content of each of the children of the root element is the value of the parameter.

 

An easy way to demonstrate this is by the following example:

Sample XML data



 1007
 

 

Note the use of the CDATA section in the above to allow the company parameter to include any characters. Alternatively the “&” character could have been replaced by its corresponding entity &.


  

ZimWeb Commands

The output from the Zim Server agent is sent to ZimWeb and then to the client (web browser, cellphone, tablet, etc.). However, there are various commands that can be used to control how the Zim application output is processed, and how ZimWeb behaves.

ZimWeb expects that the Zim application will output a series of ZimWeb commands (one per line), a blank line, and then the actual content.

To send HTML to a web browser, the beginning of the application’s output should be:

 

content-type:text/html

 

etc…

 

N.B. The blank line between the content-type: line and the start of the content is very important!

Commands are not case sensitive. In case you are wondering about the content-type line, it is not send directly to the web browser.

Commands Organized by Function Type

Content processing
content-type:Sets the response content type to .
You do not need to set this if you are applying an XSLT stylesheet with the apply-xslt: command and the ZimWeb is configured to use the output type specified in the stylesheet’s output method.
If this is specified, and a stylesheet is being applied, then the content type specified will override the stylesheet’s output method.
If the ZimWeb cannot determine the content type, it will assume it is text/html, except if the client requests no styling (parameter STYLE=none), then, if there is no content-type: command, the content will be assumed to be XML (mime type text/xml), since you can only style XML.
If that all sounds rather complicated, it’s just trying to express explicitly some fairly reasonable and benign assumptions.
apply-xslt:Apply XSLT stylesheet to the Zim agent output.
The parameter is a file path relative to the base path of the ZII application. If you have installed the ZimWeb in the manner described in the installation instructions then specifying the as /styles/cool.xsl will refer to the file [TOMCAT_ROOT]/zii/styles/cool.xsl.
The parameter can be overridden by the input parameter STYLE.
The ZimWeb automatically compiles and caches XSLT stylesheets in memory for maximum performance.
N.B. The ZII does not accept a URI for the stylesheet as running a stylesheet not under your control could be a security hazard.
apply-page-template:Apply the page template to the Zim agent output.
The parameter is a file path relative to the base path of the ZimWeb application, just like the parameter above.
The parameter can be overridden by the input parameter PAGETEMPLATE.
The ZimWeb automatically compiles and caches page templates in memory for maximum performance.
Read more about using page templates.

N.B. ZimWeb does not accept a URI for the form template since this could be a security hazard.

apply-xslfo:Treat the Zim agent output, or the result of the other content processing (typically XSLT, though it could be a page template), as XSL Formatting Objects and render it with the specifed .
The two rendering options currently available are PDF (Adobe Portable Document Format), for which you would specify apply-xslfo:pdf, or alternatively RTF (Rich Text Format), for which you would specify apply-xslfo:rtf.
Note that rendering to PDF is much more accurate than rendering to RTF.
HTTP session parameter management
set-session-parm:=Sets the session parameter to the value .
If the parameter already exisits, then its value is changed to .
Once set, the parameter will be available for inclusion in the TEMPLATE parameter.
Session parameters remain set until they are cleared, or the session times out or is invalidated.
Session parameters are not sent to the client – they are managed by the ZII servlet.
N.B. Cookies should be enabled on the client’s browser in order that http session parameters function correctly.
If the same parameter exists in several places then the form parameters have priority over the session parameters, and these have priority over the cookie parameters.
clear-session-parm:Clears the session parameter .
invalidate-sessionTerminates the client session and starts a new one.
This will cause all session parameters to be discarded.
session-timeout:Sets the session timeout to seconds.
If not specified, the session timeout defaults to the value specified in the Configuring ZimWeb .
N.B. It only changes the timeout for this session, not any other session, and it does not change the default session timeout.
Cookie parameter management
set-cookie-parm:=Sets the cookie parameter to the value .
If the parameter already exisits, then its value is changed to .
Once set, the parameter will be available for inclusion in the TEMPLATE parameter.
Cookie parameters remain set until they are cleared, or the cookie reaches its expiry time.
To work, using cookie parameters requires that the client has cookies enabled.
N.B. Cookies should be enabled on the client’s browser in order that cookie parameters function correctly.
If the same parameter exists in several places then the form parameters have priority over the session parameters, and these have priority over the cookie parameters.
clear-cookie-parm:Clears the cookie parameter .
N.B. This will not clear the JSESSIONID cookie which is required for session management.
clear-all-cookiesClears all the cookies set by the ZimWeb .
N.B. This will not clear the JSESSIONID cookie which is required for session management.
cookie-timeout:Sets the cookie timeout to seconds, as opposed to the default cookie timeout, for cookies set after it in the ZimWeb commands.
A negative timeout indicates that the cookie will expire when the user exits the client. However, I would suggest you use a session parameter instead in that case.
N.B. It does not change the default cookie timeout.
Persistent Zim session management
start-zim-sessionStart a persistent Zim session. Key points to note about this are:-

  • This is the Zim application requesting that the Zim session is to persist, not a request by the client.
  • If the persistent Zim session is being managed by a SESSIONID parameter in the form parameters then the Zim procedure must include the SESSIONID parameter in its TEMPLATE in order that it can continue using that Zim session.
  • Unlike the ZimCGI, all Zim database agent requests have a SESSIONID; but of course Zim sessions that are not to persist are ended at the end of the request in which they were started.
end-zim-sessionEnds the current persistent Zim session.
cancel-zim-sessionEnds the current persistent Zim session without sending any response to client.
Status and error codes
set-status:Set an HTTP status code (without a message – sending a message with a status code is depricated) to the client.
send-error:[:]Send an HTTP error code, with or without a message, to the client.
Authentication
request-authentication:Send a BASIC authentication request for a given realm to the client.
Miscellaneous
redirect:Redirect the client to a new URL.
set-cache-time:Set the caching time for a response in seconds (normally the responses indicate that they cannot be cached).
set-header:=Set a string HTTP header to a given value.
set-int-header:=Set an integer HTTP header to a given value.
set-date-header:=Set a date HTTP header to a given value. N.B. Dates are in milliseconds since the epoch (midnight on January 1, 1970).

 

ZimWeb Features

ZimWeb requires a TEMPLATE parameter. It is not optional (see Parameter Template can be Specified for this Procedure).

Ability to Handle POST and GET Requests

ZimWeb can accept parameters via either a POST request or a GET request (with the parameters in the URL, which means you can bookmark a ZimWeb request or add a hyperlink).

Debug Information

If you supply the parameter DEBUG in the request, you can see all sorts of useful details about the parameters, the http headers, etc., which can be very useful for debugging.

Note: Since exposing the debugging information to any client may pose a security hazard, the ability to debug a request can be enabled and disabled by the application administrator.

HTTP Session and Cookie Parameter Management

Note: When we refer to a client session, we are referring to the HTTP session, not the Zim Database Agent session.

ZimWeb allows you to control and access client session and cookie parameters.

For example, your ZimWeb application could set the client session parameter PASSWORD to indicate a password that the user had supplied when they logged in. From that point, the parameter PASSWORD, if referenced in the TEMPLATE, would be supplied with that value, until the user exited their browser, the session timed out (which the application can control), or your application cleared the parameter or invalidated the session (i.e. they logged out from your Zim application).

Client session parameters do not cause the Zim Database Agent session to remain open, so your Zim Dabase Agents remain available between processing client requests.

Also, client session parameters are managed by ZimWeb and are not sent to the browser, which can be good from a security standpoint.

Similarly, your application could set a cookie parameter USERNAME to the user’s name if, say, they check a “Remember me” box. Your application will then receive the USERNAME parameter, which can be a reference in the TEMPLATE, until the cookie expires (which the application can control) or the parameter is cleared.

In addition, ZimWeb allows you to specify that particular parameters which only comes from the HTTP session or cookies, by prefixing their names with the session or cookie respectively.

Access to Key Information About the Request

ZimWeb exposes key information about the request as parameters which can be included in your TEMPLATE, these include:

  • The PathInfo of the request is placed in the PATHINFO parameter. For example, say the ZimWeb servlet (ZII) is at the URL http:www.mycorp.com/ZII/servlet/ZII – if it receives a request for a URL relative to that e.g. http:www.mycorp.com/ZII/servlet/ZII/one/two, then the PATHINFO parameter would be set to /one/two.
  • The URL of the request entered by the client (including any Pathinfo, but excluding any parameters) is placed in the REQUESTURL parameter.
  • If the client HTTP session is being tracked through a cookie (which it must be for HTTP sessions to function correctly), the parameter SESSIONFROMCOOKIE is set to 1, otherwise 0.

Support for Client Authentication by Different methods

ZimWeb provides support for client authentication in various different ways:

  • If the client has been authenticated by the web server or servlet engine, their user name is placed in the AUTHUSERNAME parameter, and the authentication method (usually BASIC) is placed in the AUTHTYPE parameter.
  • The Zim application can force the client to authenticate itself using the request-authentication: command, and discover the (unauthenticated) user name and password of the client through the CLIENTUSERNAME and CLIENTPASSWORD parameters.
  • The Zim application can record the client’s authentication status in HTTP session parameters.

Control Over the Response

ZimWeb gives the Zim application control over the response sent back to the client, including the ability to:

  • Redirect the client to a particular URL.
  • Set how long the response can be cached by the client.
  • Set the HTTP status or error code and message.
  • Set arbitrary HTTP headers.

Improved Zim Session Control

ZimWeb includes options to improve the security of, and to simplify the use of, persistent Zim sessions:

  • Improved security by preventing clients from starting sessions when the Zim application is not expecting this – this could be used to deny service by committing all the Zim Database Agents.
  • Zim sessions can be placed under the exclusive control of the Zim application through the start-zim-session, end-zim-session and cancel-zim-session commands, coupled with disabling the input parameters previously used to control Zim sessions.
  • New or rewritten applications can manage Zim sessions through the HTTP session, eliminating the need to pass the SESSIONID parameter back and forth.

XML and XSLT Support

If your Zim application generates XML output, then it can request that an XSLT style sheet is applied to that XML to generate what is sent to the client (web browser, cellphone, etc.).

Also, the web request can indicate that a particular style sheet is required, overriding the style sheet specified by the Zim application. It can even request that no style sheet is used, returning instead the raw XML.

XSLT stylesheets are automatically compiled and cached in memory for maximum performance. The web-based administration tool allows you to see which XSLT stylesheets are cached, and also enables you to clear the cache, forcing the stylesheets to be reloaded, which is useful if you have changed the stylesheets.

There is no upper limit on the XSLT stylesheet cache size – if you run out of memory through caching stylesheets then you haven’t got enough memory to run your application efficiently.

Page Template Support

Some pages, particularly those designed by graphic artists etc., may not be convenient to turn into XSLT stylesheets (see XML and XSLT support).

ZimWeb includes page template support. A page template is just a regular page (HTML or XML), with parameter placeholders to indicate where each parameter to be supplied by the Zim application is to be placed. This template can be designed easily with your normal web page design tool.

The Zim application can then supply the parameters in an XML format. These parameters are combined with the template, with the result page being delivered to the client.

Just as with the XSLT processing, the templates are compiled into memory for maximum performance, and the request can specify an alternative, or even no page template.

XSL-FO Support

ZimWeb includes XSL-FO support – this allows the Zim application to render XSL-FO (Formatting Objects) – usually the result of XSLT processing, though it can be from a page template or even the unprocessed Zim agent output – into Adobe Portable Document Format (PDF) or Rich Text Format (RTF), so the application can deliver typeset output directly to the client’s browser.

Parameter Template can be Specified for the Procedure

When specifying which procedures can be run for a given connection, you can also specify the parameter template, eliminating the need the supply a TEMPLATE parameter with the request.

Improved Zim Session Control

The Zim application can directly control the termination of a Zim session – i.e. whether a Zim Database Agent is dedicated to a particular client, or is released when a request has been processed. This is very useful in preventing “denial-of-service” to the Zim web application by holding open every available Zim database agent.

Of course, the ZII’s HTTP Session and Cookie Parameter Management eliminates much of the need to hold open the Zim session.

Ability to Start ZimWeb Automatically When Java Servlet Engine Starts

By setting “load-on-startup” for the ZimWeb servlet configuration (the file web.xml if you are using Tomcat), ZimWeb will automatically start, and create all the Zim Database Agent sessions, when the Java Servlet Engine starts.

Note: If the Zim Server is not available, the ZimWeb will start anyway, and you can start the Zim Database Agent sessions when Zim Server does become available with the web-based administration tool.

Administration Tools

ZimWeb has a web-based administration tool, which enables you to:

  • Monitor, start and stop the Zim Database Agent sessions e.g. if you want to prevent access to the Zim application for maintenance purposes.
  • Enable or disable client request debugging.
  • See the value of the startup parameters.
  • Monitor and clear the XSLT style sheet and page template caches (e.g. if you update your style sheets or page templates, they will not be read if the style sheet or page template is already cached in memory.)

In addition, ZimWeb includes a utility which enables you to perform these functions from the command line or automatically in scripts, scheduled tasks, etc.

Installing and Configuring ZimWeb

Installation

Here are some additional details about installing ZimWeb.

The ZimWeb package

ZimWeb is packaged as a WAR (Web Application Archive) file containing the following files:

PackageContents
example/index.htmHome page for the ZimWeb Example Application.
WEB-INF/example/template/*.htmPage templates for the ZimWeb Example Application.
WEB-INF/example/xslt/*.xslXSLT style sheets for the ZimWeb Example Application.
WEB-INF/web.xml/Configuration for the ZII servlets.
WEB-INF/lib/avalon-framework-xxx.jarApache Avalon Framework (required by Apache FOP).
WEB-INF/lib/batik-xxx.jarApache Batik SVG processor (required by Apache FOP).
WEB-INF/lib/fop-xxx.jarApache FOP XSL-FO processor.
WEB-INF/lib/jimi-xxx.jarSun JIMI (required by Apache FOP).
WEB-INF/lib/jfor-xxx.jarJFOR XSL-FO processor for RTF.
WEB-INF/lib/avalon-framework-xxx.jarApache Avalon Framework (required by Apache FOP).
WEB-INF/lib/zii.jarZimWeb itself.
WEB-INF/lib/jaxp/xalan-xxx.jarApache Xalan XSLT processor (in case this is not part of your Java or servlet engine environment).
WEB-INF/lib/jaxp/xercesImpl-xxx.jarApache Xerces XML parser (in case this is not part of your Java or servlet engine environment).
WEB-INF/lib/jaxp/xml-apis-xxx.jarXML APIs for XML parsing and XSLT processing from Apache Xalan-Java (in case this is not part of your Java or servlet engine environment).

The ZimWeb file zii.jar contains classes in the following Java packages:

FileDescription
zim.CGIServerThe original ZimCGI, with a few modifications
zim.jdbcZim JDBC Driver
biz.zim.ziiThe main ZimWeb classes
biz.zim.utilUtility classes for ZimWeb

There are two servlets in ZimWeb which you can invoke:

ServletDescription
biz.zim.zii.ZIIServletThe ZimWeb itself.
This is the servlet that you invoke to service a request to a Zim web application instead of the zimcgic.exe (or whatever) of the ZimCGI.
You will probably want to alias to something shorter. The ZimWeb sample configuration file web.xml for Tomcat shortens it to ZII, so if, say, you installed it with Tomcat‘s default parameters (servicing port number 8080), you would invoke it with a URL like http://:8080/ZII/servlet/ZII.
biz.zim.zii.ZIIAdminServletThe ZimWeb Administration servlet allows you to administer ZimWeb. including checking its configuration parameters, starting and stopping Zim Server agent connections, and checking and clearing the XSLT style sheet cache.
Read more about ZimWeb administration.
N.B. In a production environment, you want to secure access to this servlet – you can shut down your Zim web application with a single click! To find out more information on this topic please read below or check out your Java Servlet Engine.

The ZimWeb jar file also contains the ZimCGI Server – equivalent to the zimcgis.jar file. You may wish to use the zii.jar for both purposes to avoid problems with multiple versions on your Java CLASSPATH.

Example: Installing the ZimWeb on Tomcat V4.1.x

Before installing ZimWeb . make sure you have a working Tomcat installation, consisting of, say, Java 1.4.x plus Tomcat V4.1.x LE. N.B. You choose a Tomcat LE version with Java 1.4.x because Java 1.4 includes XML processing facilities which would otherwise be duplicated in Tomcat.

One way of installing the ZII on Tomcat V4.1.x is as follows:

  1. Place the ZimWeb WAR package file ZII.war in the directory [TOMCAT_ROOT]/webapps.
  2. Remove any directory [TOMCAT_ROOT]/webapps/ZII if it already exists e.g. if you have installed a previous version of ZimWeb .
  3. Start Tomcat. This automatically unpacks the contents of the file ZII.war into the directory [TOMCAT_ROOT]/webapps/ZII. It most likely won’t connect successfully to any Zim database because the ZimWeb configuration file requires adjustment.
  4. Stop Tomcat.
  5. Adjust the ZimWeb configuration file [TOMCAT_ROOT]/webapps/ZII/web.xml as appropriate. In particular, you should ensure that the config-file and log-file parameters are set correctly. Note also that it secures the ZimWeb Administration servlet so that it can only be accessed by users in the role ZimWeb .dmin – see the next step for how to add such a user.
  6. Adjust the Tomcat configuration file [TOMCAT_ROOT]/conf/tomcat-users.xml to add a user in the role ziiadmin that can administer ZimWeb e.g. to add a user ZimWeb .dmin with password ZimWeb you could do this by adding lines such as these into it:

    …

    …

    …

  1. Adjust the Tomcat configuration file [TOMCAT_ROOT]/conf/server.xml so that the ZimWeb application is logged separately from other applications into [TOMCAT_ROOT]/logs/localhost_ZII_log..txt. You can do this by adding the following context:

…

        …

        

                 reloadable=”true” crossContext=”true”>

                     prefix=”localhost_ZimWeb_log.” suffix=”.txt”

          timestamp=”true”/>

        …

…

  1. Important! You must ensure that ZimWeb‘s enviroment includes XML parsing and XSLT facilities, and that there are no conflicts amongst the XML processing facilities which may be supplied with your Java and Tomcat environments and ZimWeb. For example:
  • If you are running a Tomcat LE version using Java 1.4 or higher, then the Java environment already includes XML parsing and XSLT facilities, and no action is required.
  • If you are running Tomcat non-LE version using a Java version prior to 1.4, then you will have to copy the files supplied with ZimWeb in the WEB-INF/lib/jaxp directory (xalan-xxx.jar, xercesImpl-xxx.jar and xml-apis-xxx.jar) into the [TOMCAT_ROOT]/common/endorsed directory, replacing any versions of those files which came with you version of Tomcat.
  1. Restart Tomcat. It will automatically start the Zim database connections if it is configured to do so.

The above should get you started. You will probably want to configure Tomcat further – particularly by adjusting the file [TOMCAT_ROOT]/conf/server.xml – before installing into a production environment.

Note: Make sure that you do not have the zimcgis.jarfile from the ZimCGI in your Java CLASSPATH, otherwise they may interfere with one another.

Tomcat can be configured to run both standalone, or in conjunction with other web servers like Apache.

creating secure zim web applications

fbarbosafbarbosa182003-01-27T14:37:00Z2003-01-27T14:45:00Z12721552ZIM Technologies12319059.3821

Creating Secure ZimWeb Applications

Some key guidelines for creating secure ZimWeb applications include:-

  • Secure access to the ZimWeb Administration servlet so that unpriviledged users cannot access it. The installation instructions for Tomcat (See Installation) show how to reserve it for a given user name and password.
  • Ensure that the client DEBUG facility is disabled by default by setting the allow-debug configuration option to no.
  • Specify a TEMPLATE in the security configuration for all procedures – this is described in the configuration file extensions.
  • Avoid or restrict using Zim sessions if at all possible, as they are openings to a denial of service by committing all the Zim database agents:
    • Use http session variables to preserve state information instead – see parameter sources for more details about this.
    • Use the most secure setting possible for the zim-session-security configuration option– preferably disable persistent Zim sessions if they are not requred, or track Zim sessions in the http session. In addition, existing unmodified ZimCGI applications can also have their security improved.
  • Record the authentication of a user in an http session parameter e.g. session.AuthenticatedUser, which is present in all procedure templates and checked by all procedures. The initial authentication can be performed by the web server or the Zim application.
  • Place XSLT stylesheets and templates in a secure location that cannot be accessed directly by clients. A suitable location is under the WEB-INF directory of the application, as demonstrated by the ZimWeb example application.
  • Be careful about what XML information is output by the application – remember that the client can specify style=none in any request to see the raw, unstyled XML data.

 

SQL Errors

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:

-100012The control file cannot be found. Ensure the SQLCPI environment variable points to the proper directory.
-100013Ensure the SQLCPI environment variable is pointing to the correct directory.  Ensure the control file (i.e., odbc2m.cpi) contains the appropriate record.
-100023Attempts by Zim to access the SAM have failed. Lack of memory is the likely cause.
-100037Connect has failed. Check the CONNECT parameters.
-100047Incompatible 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.

 

Zim Applications’ Input Parameters

 

Input parameters are those parameters supplied as input to the Zim application.

Parameters tend to work in the same way as the ZimCGI, except that:

  • The TEMPLATE parameter is required, except where a default parameter template has been specifed for a procedure.
  • There are more parameters with reserved meanings – namely PATHINFO, STYLE, PAGETEMPLATE and RENDER.
  • Parameters can come from HTTP sessions and cookies as well as form input.
  • Form parameters can come from both POST and GET requests.

 

N.B. Parameter names are not case sensitive.

Parameter sources

Input parameters can come from three different sources:

  • Form parameters (i.e. POST/GET).
  • Session parameters.
  • Cookie parameters.

 

You must specify the parameters to be passed to your Zim application in the TEMPLATE parameter, or the default parameter template for the procedure.

Normally, if the same parameter exists in several places then the form parameters have priority over the session parameters, and these have priority over the cookie parameters.

However, if a parameter has a name beginning with the prefix session. e.g. session.IsLoggedIn then it can only come from the HTTP session parameters.

Similarly, if a parameter has a name beginning with the prefix cookie. e.g. cookie.UserName then it can only come from the cookie parameters.

Parameters with new or changed meanings

Parameters with new or changed meanings, compared with the ZimCGI, are:

 

ZimCGI parameters which have been modified
TEMPLATEThe meaning and format of this parameter has not been changed, but it is required (unlike the ZimCGI), unless the procedure has a default parameter template.
DEBUGThe meaning and format of this parameter has not been changed – if you set the parameter DEBUG to any value in the request parameters then the debugging information will be sent to the client. However, the debugging information is a lot more comprehensive, including the raw output of the Zim database agent.
Note: For security reasons, any commands in the Zim database agent output are not processed in a DEBUG request.
Note also that a request for debugging information from a client will be ignored unless debug capability has been enabled.
Request information parameters
PATHINFOThe PathInfo of the request is placed in the PATHINFO parameter, which you can place in your TEMPLATE.
For example, say the ZimWeb servlet (ZII) is at the URL http:www.mycorp.com/ZII/servlet/ZII – if it receives a request for a URL relative to that e.g. http:www.mycorp.com/ZII/servlet/ZII/one/two, then the PATHINFO parameter would be set to /one/two.
REQUESTURLThe URL the client entered; N.B. this includes any PathInfo, but excludes any parameters.
SESSIONFROMCOOKIESet to 1 if the client HTTP session is being tracked through a cookie (e.g. the JSESSIONID cookie in Tomcat), otherwise 0.
N.B. This will be set on the second and subsequent calls to the servlet – the session is not set up the first time a client invokes the servlet. Of course, HTTP session tracking through cookies requires that cookies be enabled on the browser.
SESSIONFROMURLSet to 1 if the client http session is being tracked through URL rewriting, otherwise 0.
N.B. Session tracking does not currently work effectively through URL rewriting – instead you should track sessions by enabling cookies on the browser.
Authentication parameters
AUTHUSERNAMEThe user authenticated by the web server.
AUTHTYPEThe authentication method used by the web server – BASIC etc.
CLIENTUSERNAMEThe (not necessarily authenticated) user name the client is claiming.
CLIENTPASSWORDThe (not necessarily authenticated) password the client is claiming.
XSLT styling parameters
STYLEThis parameter indicates that a particular XSLT stylesheet is to be applied to the output of the Zim Server agent.
If the Zim Server agent output includes an apply-xslt: command, then the stylesheet specified in the STYLE parameter overrides the that specified by the apply-xslt: command.
The STYLE parameter specifies a file path relative to the base path of the ZimWeb application. If you have installed the ZimWeb in the manner described in the installation instructions then specifying STYLE as /styles/cool.xsl will refer to the file [TOMCAT_ROOT]/ZII/styles/cool.xsl.
If you specify STYLE=NONE then the Zim agent output (presumably XML) will be returned as-is, without the application of any XSLT or form template processing.
Note: specifying a STYLE automatically suppresses any XSL-FO rendering specified by the Zim Server agent, unless the RENDER parameter is also supplied.
Page template parameters
PAGETEMPLATE This parameter indicates that a particular page template is to be applied to the output of the Zim Server agent.
If the Zim Server agent output includes an apply-page-template: command, then the page template specified in the PAGETEMPLATE parameter overrides the that specified by the apply-page-template: command.
The PAGETEMPLATE parameter specifies a file path relative to the base path of the ZimWeb application. If you have installed the ZimWeb in the manner described in the installation instructions then specifying PAGETEMPLATE as /styles/fancy.html will refer to the file [TOMCAT_ROOT]/ZII/styles/fancy.html.
Read more about ZII page templates.
If you specify PAGETEMPLATE=NONE then the Zim agent output (presumably XML) will be returned as-is, without the application of any XSLT or form template processing.
Note: specifying a PAGETEMPLATE automatically suppresses any XSL-FO rendering specified by the Zim Server agent, unless the RENDER parameter is also supplied.
XSL Formatting Objects parameters
RENDERThis parameter indicates that the Zim agent output, or the result of the other content processing (typically XSLT), is to be treated as XSL Formatting Objects and rendered according to the RENDER parameter.
The two rendering options currently available are PDF (Adobe Portable Document Format), for which you would specify the value PDF, or alternatively RTF (Rich Text Format), for which you would specify the value RTF..
Note: that rendering to PDF is much more accurate than rendering to RTF.
If you specify RENDER=NONE then rendering is suppressed, and the XSL-FO is returned directly to the browser.

Zim on Windows

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

Zim on UNIX

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.

en_CAEnglish
pt_BRPortuguese en_CAEnglish