# 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:

1. Download the Witango Server 5.5 for Linux from the witango.com web site. (http://www.witango.com/downloads
2. Create a new user and group called witango. Add the witango user to the witango group.
3. Create a new directory 5.5 in the /usr/local/WitangoServer directory
4. mkdir /usr/local/WitangoServer
5. mkdir /usr/local/WitangoServer/5.5
6. Decompress the Witango archive and move all the file to the /usr/local/WitangoServer/5.5 directory
7. Set the permission on the /usr/local/WitangoServer/5.5 directory as follows. This will allow the witango user to start the server and read the configuration files. It will also allow "other" users to be able to read the clients.ini file which is necessary to allow the web server plugin to be able to read the clients.ini file.

       chown -R witango /usr/local/WitangoServer

       chgrp -R witango /usr/local/WitangoServer

       chmod -R 770 /usr/local/WitangoServer

       chmod 775 /usr/local/WitangoServer/5.5/configuration

       chmod 774 /usr/local/WitangoServer/5.5/configuration/clients.ini

8. Install the Sun JRE (or JDK) 1.4.2_06 or higher. This is required for the JDBC and JavaBean interfaces of the server to be enabled. If you do not use these features you may skip this step.
9. Edit the witango.ini file located in the configuration directory and set the following parameters to have the correct path to the associated library. If you do not use any of these libraries leave the parameter blank. The path displayed below are examples and may not match your system configuration.

       JAVAVIRTUALMACHINE=/usr/j2se/jre/lib/sparc/client/libjvm.so

       OCILIBPATH=

       ODBCDMLIBRARY=/usr/local/lib/libiodbc.so

10. Edit the start_witango.sh script file (this file is located in the install directory) so the environment variable have the correct paths for your system. This sample startup script will initialise all the environment variables required to load odbc, a JVM, OCI and the Witango Server.
11. You now need to add your license.ini file to the configuration directory and the license key to the LICENSE= parameter of the witango.ini file
12. The Witango Server is now ready to be started by running the start_witango.sh script from the command line. As the server process starts up status information will be written to stdout or to the witangoevents.log file in the configuration directory. An example of a successful startuo sequence is shown below. The following lines indicate that the server has started up correctly and initialised the JVM, Web Service, ODBC and OCI interfaces.
    [20403] 2004-01-19 15:39:47 START INFO Starting Witango Application Server Process
    [20403] 2004-01-19 15:39:47 RUNTIME INFO Flushing 0 documents from document cache
    [20403] 2004-01-19 15:39:47 RUNTIME INFO Flushing 0 documents from include cache
    [20403] 2004-01-19 15:39:47 RUNTIME INFO Application File Cache: Disabled
    [20403] 2004-01-19 15:39:47 RUNTIME INFO Flushing 0 documents from document cache
    [20403] 2004-01-19 15:39:47 RUNTIME INFO Flushing 0 documents from include cache
    [20403] 2004-01-19 15:39:47 RUNTIME INFO Include File Cache: Disabled
    [20403] 2004-01-19 15:39:47 VERSION INFO Witango Application Server 5.5 Liquorice (Linux) [Professional Edition]
    [20403] 2004-01-19 15:39:47 START INFO Loading configuration stanza 'WitangoServer'
    [20403] 2004-01-19 15:39:47 START INFO Maximum heap size 50000000 bytes
    [20403] 2004-01-19 15:39:47 START INFO Java Virtual Machine: Attempting to load /usr/java/jre/lib/sparc/client/libjvm.so
    [20403] 2004-01-19 15:39:47 START INFO Java Virtual Machine: Enabled
    [20403] 2004-01-19 15:39:47 START INFO JAVABEAN Interface: Enabled
    [20403] 2004-01-19 15:39:47 START INFO JavaScript-C 1.4 release 1 1998 10 31
    [20403] 2004-01-19 15:39:47 START INFO Web Service: Enabled
    [20403] 2004-01-19 15:39:47 START INFO ODBC Interface: Enabled
    [20403] 2004-01-19 15:39:47 START INFO Oracle Call Interface (OCI): Enabled
    [20403] 2004-01-19 15:39:47 START INFO Listener Address: Any
    [20403] 2004-01-19 15:39:47 START INFO Listener Port: 18100
    [20403] 2004-01-19 15:39:47 START INFO Allocated 20 worker threads
    [20403] 2004-01-19 15:39:47 START INFO Skipping empty startup URL
    [20403] 2004-01-19 15:39:47 START INFO Started accepting user requests
13. The line stating " Started accepting user requests " is an indication that the witangod process is ready to accept requests from the web server plug-in.
14. You now need to install the witango web server plug-in for your web server. See the section below for information on configuring Apache 2 or Sun Java Systems Web Server. The install directory contains sample startup scripts, init.d scripts, and the witango plug-ins for Apache 2 and Sun Java Systems Web Server as well as sample configurations for each plug-in.

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:
#
# InitWitangoEnv
# Use this procedure to set all environment variables to be used by the witangod process
#
InitWitangoEnv ()
{
umask 022
# Set up environment for Witango server
#
WITANGO_PATH= /usr/local/WitangoServer/5.5
export WITANGO_PATH
WITANGO_CONFIG=$WITANGO_PATH/configuration
export WITANGO_CONFIG
WITANGO_USER=witango
export WITANGO_USER
# Set up environment for Java Virtual Machine
#
JAVA_HOME=/usr/j2re
export JAVA_HOME
JAVA_LIB=$JAVA_HOME:$JAVA_HOME/lib/sparc:$JAVA_HOME/lib/sparc/client
export JAVA_LIB
#Add the paths to the JDBC jar files to the CLASSPATH
CLASSPATH=.:/usr/local/jdbcdrivers/msSQLjdbc/msbase.jar:/usr/local/jdbcdrivers/msSQLjdbc/mssqlserver.jar:/usr/local/jdbcdrivers/msSQLjdbc/msutil.jar:/usr/local/jdbcdrivers/mysql-connector-java-3.0.6-stable-bin.jar
export CLASSPATH
# Set up environment for ODBC driver manager
#
ODBCINI=/etc/odbc.ini
export ODBCINI
ODBCINSTINI=/etc/odbcinst.ini
export ODBCINSTINI
# Set up general environment variables
#
LD_LIBRARY_PATH=.:$JAVA_LIB:$JAVA_HOME/lib/sparc/native_threads:$WITANGO_PATH:/usr/local/lib:/usr/local/ssl/lib:/usr/lib
export LD_LIBRARY_PATH
DYLD_LIBRARY_PATH=$LD_LIBRARY_PATH
export DYLD_LIBRARY_PATH
PATH=.:$JAVA_HOME/bin:$WITANGO_PATH:/usr/bin:/usr/sbin:/usr/local/bin
export PATH
LC_ALL=en_US
export LC_ALL
}
InitWitangoEnv
echo "############# Witango Environment #############"
echo JAVA_HOME=$JAVA_HOME
echo
echo CLASSPATH=$CLASSPATH
echo
echo PATH=$PATH
echo
echo LD_LIBRARY_PATH=$LD_LIBRARY_PATH
echo
echo DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH
echo
java -version
echo
echo "#################################################"
$WITANGO_PATH/witangod -uo -c "WitangoServer"
$WITANGO_PATH/witangod -uo -c "WitangoServer1"

## 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).
[20403] 2004-01-19 15:39:47 START INFO Java Virtual Machine: Attempting to load /usr/java/jre/lib/sparc/client/libjvm.so
[20403] 2004-01-19 15:39:47 START INFO Java Virtual Machine: Enabled
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:
[JAVABEAN]
ShortName=JavaBeans
SupportsScanning=1
ServerPath=/usr/local/witango_5.5/sshbn501.dylib
LoadHandler=1
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:
<?xmlversion="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE JDBCINI SYSTEM "jdbcini.dtd" >
<JDBCINI Version="0x00010000">
<DataSources>
<DataSource ID="TestMySQL">
<DSN>TestMySQL</DSN>
<DriverClass>com.mysql.jdbc.Driver</DriverClass>
<URL>jdbc:mysql://127.0.0.1:3306/TestMySQL</URL>
<Properties/>
</DataSource>
<DataSource ID="TestMSSQL">
<DSN>TestMSSQL</DSN>
<DriverClass>com.microsoft.jdbc.sqlserver.SQLServerDriver</DriverClass>
<URL>jdbc:microsoft:sqlserver://127.0.0.1:1433;databaseName=TestMSSQL</URL>
<Properties/>
</DataSource>
<DataSource ID="TestFileMaker7">
<DSN>TestFileMaker7</DSN>
<DriverClass>com.ddtek.jdbc.sequelink.SequeLinkDriver</DriverClass>
<URL>jdbc:sequelink://127.0.0.1:2399;serverDataSource=TestFileMaker7</URL>
<Properties />
</DataSource>
<DataSource ID="TestOpenBase">
<DSN>TestOpenBase</DSN>
<DriverClass>com.openbase.jdbc.ObDriver</DriverClass>
<URL>jdbc:openbase://192.168.0.55/TestOpenBase</URL>
<Properties />
</DataSource>
</DataSources>
</JDBCINI>

## 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.