Witango Application Server 5.5
Linux ReadMe

Minimum Requirements

Hard Disk Space: 30MB free
Memory: 256MB RAM
Database Connectivity: ODBC driver manager such as iODBC or unixODBC, ODBC 3.x driver or above, JDBC, Oracle Call Interface (OCI) - Oracle Instant Client
WebServer: Apache 2.0.44 or above
JVM: 1.4.2_06 or greater


NOTE: It is assumed that the person installing the Witango Server has an understanding of the Linux operating system, system administration, file permissions and the access rights to be able to modify the startup sequence and file permissions.
Before Installing The Server
IMPORTANT : You should read this document before continuing with the installation.
IMPORTANT : Please ensure that any existing Witango Application Server processes on your system have been shut down before continuing with the installation.
IMPORTANT : You must create a witango user before continuing with the server installation. If you do not create a witango user, the server will fail to start as a daemon
IMPORTANT : The Java 1.4.2.06 (or higher) JVM should be installed prior to installation.

Dependancies:

Library	Location
libcrypt.so.1	/lib/libcrypt.so.1
libstdc++.so.5	/usr/lib/libstdc++.so.5
libssl.so.0.9.7	/usr/lib/libssl.so.0.9.7
libldap.so.199	/usr/lib/libldap.so.199
libcrypto.so.0.9.7	/usr/lib/libcrypto.so.0.9.7

What's new in Witango Server 5.5

1. DOM2
2. XPath
3. Xpointer
4. XSLT
5. LDAP
6. WHILE
7. IFNOTEMPTY
8. Web Services - SOAP, WSDL

Changes in Witango Server 5.5.020

• Updated to the xerces library 2.7
• Updated to the xalan library 1.10
• @SORT works on user scope vars when USERKEY is <@APPKEY><@USERREFERENCE>
• @CALLMETHOD does a meta evaluation for all parameters
• empty elements default to ODBC (T2K bug)
• empty element warnings logged to witangoevents.log
• Fixed several crashes caused by method calls from very large TCFs
• <@CIPHER> allows for UTF-8 encoding and decoding
• <@ARRAYTODOM> tag
• Apache 2.2 Plugin
• Several obscure crash conditions fixed
• Fixes to file cache to release TCFs in shared scopes under heavy load
• Minor optimisations to file cache structure
• Updated crypto library to latest version
• Fixed issue with socket status test routine in OS X web plug-ins
• Fixed bug to set time zones which were not whole hours. e.g. +09:30
• Fixed crash condition when assigning values to null arrays in user scope
• Updated processor affinity on Windows to handle HT & Dual Core CPUs
• @CHOICELIST is xhtml compliant
• Processor Affinity (Win) now works with up to 16 multi-core CPUs
• Processor Affinity now works with up to 16 hyperthreaded CPUs
• SQL syntax for FM8 now uses the LIKE % instead of old FM6 *= notation

Changes in Witango Server 5.5.009

• Bound parameters work with stored procedures that produce multiple resultsets
• Updated to the xerces library 2.6
• Updated to the xalan library 1.9
• @URL maintains session cookies when using SSL
• Script action now falls into no results when nothing is returned
• Fixes to the SQL generator
• Removed execution limit  of 32656 for external actions on Windows
• Fixed nextval so it errors when passed an empty value
• Fixed quote value setting on insert and update actions
• Fixed timeout trigger so that the variable store is always found
• Minor tweaks to JDBC interface to improve compatibility with OpenBase 8.0.4 JDBC driver
• Javascript library updated to 1.5 (SpiderMonkey Build) and made threadsafe
• Fixed xDBC heartbeat query to handle table names which begin with a digit or have spaces
• XML related tags that use XPath now uses the xalan XPath implementation
• Improvements to the IIS and Apache 2 plug-in error handling and reporting

Installing and Configuring Witango Server 5.5 for Linux

The following documentation will describe installing the Witango Server 5.5 into the /usr/local/WitangoServer/5.5 directory on Linux.

NOTE: If this location is not used the WITANGO_PATH environment variable must be set in the scripts that start the Witango Server process to allow the witangod daemon to find the configuration directory that contains the initialization files for the server.  This environment variable must also be set in the web server process environment to allow the Witango web server plugin to be able to locate the clients.ini file which is used to initialise the Witango web plug-in as the web server starts up.  Alternately the clients.ini file can be placed in /usr/local/WitangoServer/5.5/configuration with appropriate permissions

Installing and Configuring Witango Server 5.5

To install and configure the Witango server follow the steps below:

NOTE:   To have the Witango Server process (witangod) start as part of the startup sequence of your system, move the witango55.init.d file to the desired /etc/init.d directory.  You will need to modify this script to have the correct environment variable configuration for your system.  The script should be executed at a run level after network and IP services have started.  It is recommended that you start the witangod process late in the startup process after the network and security sub systems have been initialised.


  

Sample Witango Server Startup Script

A basic startup script to start the Witango Server process would:

1. Initialise the environment for the witangod process and subsystems
2. WITANGO_PATH
3. Java Environment and CLASSPATH
4. ODBCINI and ODBCINSTINI
5. LD_LIBRARY_PATH
6. PATH
7. Oracle Environment variable
8. Start the Witango Server process

An example script the initialises and starts two (2) Witango Server process follows:

Witango Server command line options

The witangod process has several command line options. The available options can be viewed by typing witangod -h

witangod [ -ksuorvh ] [-c config_name]
-k: Kill the running process
-s: Request status information of the running process
-u: Run process in user space, and not as a daemon
-o: Send output to standard out window
-r: Restart the daemon
-c: Start the daemon with 'config_name'
-v: Version Information
-h: This help message

If the -u arguments is not present the process will attempt to start as a daemon. You will require root access to do this via a terminal session.

Web Server Plug-in Installation and Configuration

Before the Witango Server can process user requests a Witango web server plug-in needs to be installed and configured. The Witango web server plug-in routes witango requests to the Witango Server and handles both load balancing and fault tolerance when multiple witango servers as configured. The plug-in manages and routes the requests from the web server to the Witango Server and the responses from the Witango server back to the web server.

On initialization the Witango web server plug-in reads the Witango configuration file clients.ini file. This file is located in the <witango-path>/configuration directory. If the privileges on this directory and file prevent the web server process from reading this file the Witango web server plug-in will not initialize and any attempt to request a witango file will result in a error stating that there was a client initialization error. If this occurs change the permission on the Witango configuration directory and the clients.ini file to allow the user that owns the web server process to have read access only to the clients.ini file

Apache 2.0.44 or above Plug-in Installation and Configuration

To install the Apache 2 plug-in

1. Copy the $WITANGO_PATH/Plug-Ins/mod_witango55_apache2.so file to the Apache 2 modules directory on your server
2. Add the following lines to your httpd.conf file
   
   # The following lines load the Witango 5.5 module for Apache 2 to enable communication with the Witango Application Server
   LoadModule WitangoModule /usr/local/Apache2/modules/mod_witango55_apache2.so
   WitangoModule mod_witango55_apache2.so
   AddType application/witango-application-file taf tml thtml tcf wws
   

NOTES:

1. The path to the Apache modules may need to be modified to reflect where Apache is installed on your system
2. If you have difficulties in loading the module, try using an absolute path to the witango55_apache2.so module or loading the module before the mod_rewrite module
3. The Apache 2 server must be compiled with the --enable-modules=all or --enable-so option for the server to be able to load and configure the Apache 2 plug-in.

Configuring the JVM and JavaBean Handler

The JavaBean handler or JDBC interfaces can only be enabled once a Java Virtual Machine (JVM) hase been successfully loaded by the server. For the JVM to load successfully you will need to setup the correct environment variables and configure where the JVM client library is located. The JAVAVIRTUALMACHINE parameter in the witango.ini fil allows the administrator to configure which JVM client library to load. The JVM client should only be referenced by an absolute path and not via a symbolic link. This parameter take an absolute path to the library as shown below.
JAVAVIRTUALMACHINE=/usr/java/j2re1.4.2_06/lib/i386/client/libjvm.so

If the Java Virtual Machine loads successfully the following message will be displayed in the Witango events log (witangoevents.log).


NOTE: It is recommended that the 1.4.2 or higher JVM be used. Unpredictable results may occur when using earlier versions of the JVM due to changes in the Java APIs on Linux.

Loading the JavaBean Handler

Once the JVM has been loaded you be able to enable the JavaBean handler. The JavaBean handler can be enable in the handlers.ini file by setting the parameter LoadHandler=1 (0 will not load the handler) and ensure the path to the bean handler library is correct:


For the server to be able to access javabeans they must be referenced in the CLASSPATH environment variable of the Witango server process. This is easily managed in the Witango Server startup script or by adding BEANPATH parameters to the objects.ini file under the JAVABEAN stanza.

Using the JDBC interface

For the server to be able to access JDBC drivers they must be referenced in the CLASSPATH environment variable of the session the server is running in. This is easily managed in the Witango server startup script (/etc/init.d/witangod55.init.d file). It is not recommended that the BEANPATH parameters in the objects.ini be used for this purpose. All JDBC datasources are configured in the jdbc.ini file in the configuration directory. A typical jdbc.ini file is:

A Few Things To Note If You Don’t Like Reading Manuals (Differences between Tango 3/2000 and Witango 5.5)

1. Local scope has been changed to request scope. This more accurately describes the life of the variable.
2. Local scope has been kept as an alias to Request scope to ensure backward compatability. The Witango Dev Studio version 5 uses Request scope with all actions instead of Local scope and will therefore produce code that is not fully compatible with a Tango 2000 server. This can be worked around by opening your taf and tcf files in a text editor and replacing Request with Local in the actions. On a Tango 2000 server all Request scoped variables will function as Custom scoped variables.
3. Request and Method scope have been optimized for speed and will operate faster than shared scopes like Domain, Application and Custom.
4. Always quote your parameter values, especially if they are string values.
5. The server settings now have the default scope set to Request. If you do not scope your variables (we recommend that you do) you will need to change this setting in the witango.ini file to User. Using a default scope of request will typically keep memory usage to a minimum and performance optimized.
6. The httpheader configuration variable does not function the same way in Witango v5.0 as it did in Tango 2000. Partial headers are no longer allowed and you now need to send complete http headers. There are 2 new tags to assist you in formulating http headers - @HTTPREASONPHRASE and @HTTPRESPONSECODE
7. TCF objects now operate in shared scopes without crashing the server.
8. Always scope your variables. This make more robust code and takes load off the server as it does not have to search the different scopes for the variable name. e.g. @@MyVariable forces the server to search the different variable scopes (domain, application, custom, user and request) while @@user$MyVariable would not require the server to search the different scopes.
9. If you have installed an alternate ODBC driver manager ensure that the path in ODBCDMLIBRARY points to the odbc library you are using.
10. The license key generated in 30 day trial mode is tied to the machines IP addresses or host names. The server will report an invalid license if either of these changes. This may affect installations on portables. A fully registered license key does not have this restriction.

Switching to a Different ODBC Driver Manager

The Witango Server installer automatically links to the ODBC driver manager installed /usr/lib/libodbc.dylib library. If you wish to use the server with a different ODBC driver manager, you will need to change the ODBCDMLIBRARY parameter in the witango.ini file to point to the odbc library you have installed. Witango Server is only compatible with odbc drivers that are written to the ODBC 3.0 and above. ODBC 2.5 or 2.0 compatible drivers will not work with the Witango Server. In these situations a suitable JDBC driver should be used.