Mini SQL 2.0

User Guide


Installing mSQL 2.0

For the eager reader, an overview of the compilation and installation process can be found below in the Express Setup section

Mini SQL is generally distributed in source code form to enable the widest possible use of the software. It is not feasible for binary distributions to be generated for every UNIX platform for each release of mSQL. Instead, the software and the installation tools have been made as portable as possible. In general, the software will automatically configure itself to the capabilities of the operating system on which it is being compiled. Typing four commands can complete the process of compiling and installing mSQL on most UNIX platforms. Only under extreme situations will the software not compile "out of the box". Hints for getting the software compiled on troublesome operating systems is available in the Installation Troubleshooting section below.

The software is distributed as a gziped (i.e. compressed) tar file. Tar is a standard UNIX facility for combining many files and directories into a single archive file. The tar utility should be available on any modern UNIX system. If your system does not provide the tar utility then a freely available version of tar has been produced by the Free Software Foundation (the GNU project). The GNU version of tar can be found on any GNU archive site. Similarly, the gzip compression tools are produced by the Free Software Foundation. If your system does not provide the gzip or gunzip utility then you will need to obtain these from your nearest GNU archive site.

The table below shows a selection of commonly used GNU archive sites. To access these site use anonymous FTP (or the URL provided). A complete list of GNU software mirror sites can be found at http://www.gnu.org/order/ftp.html.
 
 
Country
Hostname
Directory
URL
Australia archie.au /gnu ftp://archie.au/gnu
U.S.A prep.mit.edu /pub/gnu ftp://prep.mit.edu/pub/gnu
U.S.A ftp.uu.net /systems/gnu ftp://ftp.uu.net/systems/gnu
U.S.A gatekeeper.dec.com /pub/GNU ftp://gatekeeper.dec.com/pub/GNU
United Kingdom ftp.mcc.ac.uk /pub/gnu ftp://ftp.mcc.ac.uk/pub/gnu

 

Getting Ready to Compile

Before the software can be compiled, the contents of the archive file must be extracted. This involves uncompressing the archive file with gunzip and then using the tar utility to extract the file. If, for example, the file containing the mSQL distribution is called msql-2.0-rel.tar.gz then the following commands would extract the files (two methods are outlined)
 
  gunzip msql-2.0-rel.tar.gz

tar -xvf msq-2.0-rel.tar
 
 

Or

gzcat msql-2.0-rel.tar.gz | tar -xvf -
 
 

 This process would create a new directory called msql-2.0-rel in the current directory. Within that directory you will find the entire mSQL distribution. Along with various other files and directories there will be directories containing the source code (src directory) and the documentation (the doc directory). Although it is tempting to just enter the src directory and type "make" it is not the correct way to compile mSQL and doing so will cause problems.
 
 

The mSQL distribution is structured to allow it to be compiled on multiple machines using the same copy of the source code (source tree). For example, the source tree can be shared between various machines using NFS and versions for each machine type can be compiled in the same source tree. To achieve this, mSQL uses target directories for each machine type (hardware platform and operating system combination). To create a target directory for your machine simply type the following from the top directory of the distribution
 
 

make target This process will create a new directory called targets in the top directory. In the targets directory you will find a target directory for your machine (for example targets/SunOS-4.1.4-Sparc or targets/FreeBSD-2.2.2-i386). It is in this newly created target directory that you will compile the mSQL applications.

To continue the compilation process, change directory to your target directory using ?cd targets/SunOS-4.1.4-Sparc? for example. Once you are in the target directory you can configure the compilation process. The configuration process is totally automatic and will determine what system calls, library functions, and header files your operating system provides. To configure the compilation process simply type
 
 

./setup
 
  While the setup utility is executing you will see various pieces of information about your operating system being displayed as it is determined. This output is informative only. The results are automatically placed in files used by mSQL.

Once the automatic configuration is complete you may either compile the software using the default configuration settings or change the configuration settings from their default value. There are two configuration items located in the site.mm file in the targets directory that you may consider modifying. The configuration utility will try to determine the best C compiler to use on your system. If you have multiple C compilers (a system compiler and gcc for example) you may wish to modify the CC entry in site.mm.

The only other option in site.mm that may require modification is the INST_DIR entry. This entry defines the default installation directory. This setting is not only used during installation of the software but also as the directory containing the run-time configuration file. If you intend running mSQL from a directory other than the default /usr/local/Hughes directory then modify the INST_DIR entry in site.mm to reflect your installation directory.

 Compilation and Installation Once the setup utility has completed you may compile the software by typing
 
  make all
 
  The compilation process will traverse all the directories of the mSQL distribution and compile the C source code in those directories. Status information is displayed to you as the compilation process proceeds. If the compilation process stops with an error at any stage then please see the Installation Troubleshooting section below. If the compilation has completed properly you will see a message on your screen informing you that you are ready to install mSQL.

Installation of mSQL can also be achieved using a single command, although you may need to have special permissions on your UNIX system (usually root access). By default, mSQL will be installed in a directory called /usr/local/Hughes on your system. If /usr/local is root owned on your system (as it is on most systems) then you will either need root access or you will have to get your system administrator to complete the installation for you. If you are using a non-default installation directory then ensure that you have the required permissions to create the directory you specified. To complete the installation simply type
 
 

make install Configuring mSQL 2.0 mSQL 1.x offered several configuration options, including such details as the user the server should run as, the location of the TCP and UNIX sockets for client/server communications, the location of the database files etc. The problem with configuring mSQL 1.x was that all these details were hard-coded into the software at compile time. Once the software was compiled and installed you couldn't easily change those settings.

To overcome this problem, mSQL 2.0 utilises an external run-time configuration file for definition of all these values. The file is called msql.conf and is located in the installation directory (usually /usr/local/Hughes). An application can choose to use a different configuration file by calling the new msqlLoadConfigFile( ) API function. All standard mSQL applications and utilities provide a command line flag, -f ConfFile , that allows you to specify a non-standard configuration file. When an application first calls the mSQL API library, a check is made to see if a configuration file has been loaded via a call to the msqlLoadConfigFile( ) function. If no such call has been made, the API library loads the default config file. Any values that are specified in that file will over-ride the normal operating parameters used by mSQL. If no configuration file is found (or certain items are not set) then the default values listed below will be used.
 
 

 Structure of the config file The configuration file is a plain text file organised into sections. The file can contain blank lines and comments. A comment is a line that begins with the '#' character. Each section of the configuration file has a section header, which is written as the section name enclosed in square brackets (for example [ general ]).

Configuration values within a section are presented using the config parameter name followed by an equals sign and then the new value. There can only be one entry per line and if an entry is defined multiple times in the one config file the last value defined will be used. If a parameter is not defined in the config file then an internal default value will be used at run-time.

 Elements of the General section The following configuration parameters are available in the general section of the config file. Please note that %I may be used in configuration entries to signify the mSQL installation directory (e.g. /usr/local/Hughes).
 
 
Parameter
Default Value
Definition
Inst_Dir /usr/local/Hughes The full path to the installation directory. This is the directory in which all the mSQL files are located (such as the program files, the database files etc). 
mSQL_User msql The user that the mSQL server should run as. If a user other than this user starts the server (e.g. it is started as root from a boot script) it will attempt to change UID so that it runs as the specified user. 
Admin_User root The user that is allowed to perform privileged operations such as server shutdown, creation of databases etc. 
Pid_File %I/msql2.pid The full path of a file in which the PID of the running mSQL server process will be stored. 
TCP_Port 1114 The TCP port number on which the mSQL server will accept client/server connections over a TCP/IP network. If this value is modified it must be modified on the machine running the client software also. 
UNIX_Port %I/msql2.sock The full path name of the UNIX domain socket created by the mSQL server for connections from client applications running on the same machine. 

Elements of the W3-mSQL section

The following configuration parameters are available in the W3-mSQL section of the config file. These items impact on the operation of the W3-mSQL web interface package.
 
 
Parameter
Default Value
Definition
Auth_Host NULL The machine on which the mSQL database containing W3-Auth data is located. See the W3-Auth section for further details. If set to NULL (the default value) the database is assumed to be on the local host.
Hughes_Footer True Controls the appending of the standard Hughes Technologies footer to Web Pages.
Private_Only False If set to True, the W3-mSQL interface will only process private pages (see the W3-mSQL section for information on private pages). This may be used to enforce strict security on your system stopping remote users accessing normal HTML pages via the W3-mSQL cgi program.

 
 
 

Elements of the System section

The following configuration parameters are available in the System section of the configuration file and determine the values of various system level configuration items.
 
 
Parameter
Default Value
Definition
Msynch_Timer 30 Defines the interval in seconds at which the memory mapped data regions maintained in the mSQL server process will be synched with the on-disk images. Setting this value to 0 will disable forced synchronisation of the data and rely on the kernel?s synch?ing of the mmap regions.
Host_Lookup True Determines whether ip address to hostname lookups are required. If set to true, connections by hosts that do not resolve to a hostname will be rejected.
Read_Only False Forces the server to operate in read-only mode. Any attempts to modify the database will be rejected (.e. the only commands accepted are select queries). 

This option can be used if multiple database servers are to be run using the same data files. In such a case only one server should be running in read-write mode with all others running in read-only mode. This can easily be achieved by using different configuration files (specifying different TCP and UNIX ports as well) and loading the appropriate config file in the client application.

 
 
 

Example configuration file

Below is a sample configuration file. This file just sets the parameters to their default values.
 
  #

# msql.conf - Configuration file for Mini SQL Version 2.0

#

# This configuration sets all options to their default values.

# Note : %I is expanded to the value of the Inst_Dir element is included in a value.

#
 
 

[general]

Inst_Dir = /usr/local/Hughes

mSQL_User = msql

Admin_User = root

Pid_File = %I/msql2.pid

TCP_Port = 1114

UNIX_Port = %I/msql2.sock
 
 

[w3-msql]

Auth_Host = NULL

Hughes_Footer = True

Private_Only = False
 
 

[system]

Msynch_Timer = 30

Host_Lookup = True

Read_Only = False
 
 

 Express Setup Below is a rough outline of the process of compiling, installing and configuring mSQL. It is intended as a guide for those who are familiar with installing software on a UNIX machine. If you are not familiar with any of the steps mentioned below then please read the complete installation guide from the start of this manual section.

Step 1 Unpack the software distribution using gunzip and tar

gunzip msql-2.0-rel.tar.gz

tar -xvf msql-2.0-rel.tar
 
 

Or

gzcat msql-2.0-rel.tar.gz | tar -xvf -

 Step 2 Create a target directory for your hardware platform cd msql-2.0-rel

make target
 
 

 Step 3 Configure the compilation process cd targets/YourTargetDirectory

./setup
 
 

 Step 4 Check the default values of INST_DIR and CC in the site.mm file
 
 

Step 5 Compile the software

make all
 
  Step 6 Install the software make install Step 7 Configure the software by editing the msql.conf file in the installation directory
 
 
 
  Installation Troubleshooting Outlined below are some common problems encountered while installing mSQL. If you continue to have problems compiling or installing mSQL after you have checked the following sections, please e-mail support@Hughes.com.au with details of your system (operating system version etc) and an explanation of the error you are experiencing.
 
  mmap mSQL 2.0 requires a fully functional mmap implementation. Some operating systems either provide no mmap support at all or provide a limited subset of mmap. At this point in time, mSQL cannot operate on these operating systems. The most common operating systems displaying this problem are Digital Ultrix, Cray UNICOS and Linux versions earlier than 1.3 (newer versions of Linux are fine).

dynamic loading Some of the mSQL tools utilise dynamic loading of object modules (most notably the Lite and W3-mSQL tools). The setup utility will try to determine how to perform dynamic loading on your platform automatically. If you encounter link problems with references to functions such as dl_open then the automatic configuration has failed. You can safely remove the dynamic loading functionality by editing the site.mm and removing the "HAVE_DYNAMIC" option.
 
 

Linux Some distributions of Linux, including the Slackware distribution, do not include all the required C header files by default. If you did not include the kernel sources when you installed your version of Linux you may not be able to compile the mSQL software. Installing the kernel sources will solve this problem.

bitypes On some systems, the compilation of mSQL will fail with errors relating to the bitypes.h header file. This is commonly due to the installation of BIND 4.9 nameserver software. BIND replaces some of your header files during installation but fails to re-install the bitypes.h and cdefs.h files. The problem is solved by copying these header files from the compat/include directory of the BIND distribution to the /usr/include/sys directory of your system.

Irix Some installations of Irix include duplicate versions of several system routines in separate C libraries. The setup utility will recognise these libraries and include them in the link process automatically. This can cause errors relating to "weak definitions" and also unresolved symbols. To overcome this problem, edit the site.mm file and remove anything included on the EXTRA_LIBS line (i.e. set it to "EXTRA_LIBS=")