<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
  <!ENTITY figtype "#FIGTYPE#">
  <!ENTITY timestamp "#DATE#">
  <!ENTITY version "#VERSION#">
]>

<book>
	<title>Server User Manual &version;</title>
	<bookinfo>
		<address format="linespecific">e-mail: <email>sendinfo@3glab.com</email>
Web site:  www.3glab.com</address>
		<title>Copyright</title>
		<copyright>
			<year>(c) 2001</year>
			<holder>3G LAB Limited. ALL RIGHTS RESERVED.</holder>
		</copyright>
		<legalnotice>
			<para>The 3G LAB logo and Alligata logo are copyright of 3G LAB Limited in the US and other countries. In addition no part of any documentation contained in or on this packaging may be reproduced in any form (whether by electronic means, by photocopying or in any permanent or temporary form) without the express written permission of 3G LAB Limited or except as in accordance with the provisions of the Copyright Designs and Patents Act 1988 as amended or superseded from time to time.
</para>
			<para>Linux is a registered trademark of Linus Torvalds.
</para>
			<para>Solaris is a registered trademark of Sun Microsystems, Inc.
</para>
			<para>UltraSPARC is a registered trademark of SPARC International, Inc.
</para>
			<para>Wavecom and WM02 are registered trademarks of Wavecom S.A.
</para>
			<para>Nokia and Premicell are registered trademarks of Nokia Corporation.
</para>
			<para>Siemens and M20T are registered trademarks of Siemens AG.
</para>
			<para>Openwave is a trademark of Openwave Systems, Inc.
</para>
			<para>3G LAB recognises that other trademarks displayed are the property of their respective holders.</para>
		</legalnotice>
  <revhistory>
    <revision>
      <revnumber>&version;</revnumber>
      <date>&timestamp;</date>
    </revision>
  </revhistory>

	</bookinfo>
	<part>
		<title>Part One: Getting Started</title>
		<chapter>
			<title>1  Welcome</title>
			<para>Welcome to the <citetitle>Alligata Server User Manual</citetitle>. This manual is in two parts:
</para>
			<itemizedlist>
				<listitem>
					<para>This part, <citetitle>Getting Started</citetitle>, provides an overview of the Alligata Server, and explains how to install the program. It covers the following topics:
</para>
					<itemizedlist>
						<listitem>
							<para>How the Alligata Server fits into the architecture of the Wireless Application Protocol (WAP), the Short Message Service (SMS) and the World Wide Web
</para>
						</listitem>
						<listitem>
							<para>The internal functioning of the Alligata Server
</para>
						</listitem>
						<listitem>
							<para>The hardware and software you need to run the Alligata Server
</para>
						</listitem>
						<listitem>
							<para>How to install the Alligata Server from a Linux/Solaris windowing system, or from the Linux/Solaris command prompt
</para>
						</listitem>
						<listitem>
							<para>How to spread an installation of the Alligata Server across several computers in order to maximise processing capacity
</para>
						</listitem>
					</itemizedlist>
				</listitem>
				<listitem>
					<para>The second part, <citetitle>Using the Alligata Server</citetitle>, is a detailed guide to running, configuring and using the Alligata Server. It covers the following topics:
</para>
					<itemizedlist>
						<listitem>
							<para>How to start, stop and administer the Alligata Server
</para>
						</listitem>
						<listitem>
							<para>How to change the Alligata Server&apos;s configuration settings
</para>
						</listitem>
						<listitem>
							<para>How to view the example WAP sites provided with the Alligata Server
</para>
						</listitem>
						<listitem>
							<para>How to create WAP sites using Wireless Markup Language (WML)
</para>
						</listitem>
						<listitem>
							<para>How to create dynamic WAP sites using the Perl scripting language
</para>
						</listitem>
						<listitem>
							<para>How to create dynamic WAP sites using the PHP scripting language
</para>
						</listitem>
						<listitem>
							<para>How to use the Alligata Server&apos;s SMS features to deliver World Wide Web and other content to mobile phones
</para>
						</listitem>
						<listitem>
							<para>How to use the Alligata Server to send SMS messages from a computer workstation
</para>
						</listitem>
						<listitem>
							<para>How to configure a mobile phone for a WAP service &apos;over the air&apos; using the Alligata Server&apos;s SMS features
</para>
						</listitem>
					</itemizedlist>
				</listitem>
			</itemizedlist>
			<section>
				<title>1.1 The Alligata Server Package
</title>
				<para>Your Alligata Server package contains:
</para>
				<itemizedlist>
					<listitem>
						<para>An installation CD-ROM from which you can install the Alligata Server, some example WAP sites, the Apache Web server, the PHP scripting language and some modules for the Perl scripting language that are useful for developing Mobile Internet sites.
</para>
					</listitem>
					<listitem>
						<para>A booklet, <citetitle>Your Pocket Guide to the Mobile Internet</citetitle>.
</para>
					</listitem>
					<listitem>
						<para>This <citetitle>Alligata Server User Manual</citetitle>.
</para>
					</listitem>
					<listitem>
						<para>An <citetitle>Alligata Server Quick Reference Guide</citetitle>. 
</para>
					</listitem>
				</itemizedlist>
			</section>
		</chapter>
		<chapter>
			<title>2  System Requirements</title>
			<para>There are two versions of the Alligata Server, one for the Linux operating system and one for the Sun Solaris operating system.
</para>
			<section>
				<title>2.1 Linux Version
</title>
				<section>
					<title>Minimum System Requirements
</title>
<FormalPara>
<title>Hardware:</title>
<para>
					<itemizedlist>
						<listitem>
							<para>100% IBM-compatible PC with at least 16 MB of RAM
</para>
						</listitem>
						<listitem>
							<para>Hard disk with at least 30 MB free
</para>
						</listitem>
						<listitem>
							<para>Connection to the telephone network via modem or similar
</para>
						</listitem>
					</itemizedlist>
</para>
</FormalPara>
<FormalPara>
<title>Software:</title>
<para>
					<itemizedlist>
						<listitem>
							<para>Red Hat Linux version 6.0, 6.1 or 6.2 
or 
Mandrake Linux version 7.0 or 7.1
</para>
							<para>(The Alligata Server may run on some other distributions of Linux)
</para>
						</listitem>
						<listitem>
							<para>Perl version 5.0 or higher. Perl is standard in most Linux distributions. If you do not have Perl installed, download it from <ulink url="http://www.perl.org">www.perl.org</ulink>
							</para>
						</listitem>
					</itemizedlist>
</para>
</FormalPara>
				</section>
				<section>
					<title>Optional Hardware Accessories</title>
					<itemizedlist>
						<listitem>
							<para>Connection to the Internet, either dial-in or dedicated
</para>
						</listitem>
						<listitem>
							<para>GSM modem (Wavecom WM02, Nokia Premicell or Siemens M20T) <emphasis role="bold">or</emphasis> subscription to an SMS Centre (SMSC) <emphasis role="bold">or</emphasis> GSM mobile phone with integrated modem, for sending and receiving SMS messages
</para>
						</listitem>
					</itemizedlist>
				</section>
			</section>
			<section>
				<title>2.2 Solaris Version
</title>
				<section>
					<title>Minimum System Requirements
</title>
<FormalPara>
<title>Hardware:</title>
<Para>
					<itemizedlist>
						<listitem>
							<para>Sun UltraSPARC with at least 128 MB of RAM
</para>
						</listitem>
						<listitem>
							<para>Hard disk with at least 30 MB free
</para>
						</listitem>
						<listitem>
							<para>Connection to the telephone network
</para>
						</listitem>
					</itemizedlist>
</Para>
</FormalPara>
<FormalPara>
<title>Software:</title>
<Para>
					<itemizedlist>
						<listitem>
							<para>Sun Solaris version 7 or 8
</para>
						</listitem>
					</itemizedlist>
</Para>
</FormalPara>
				</section>
				<section>
					<title>Optional Hardware Accessories 
</title>
					<itemizedlist>
						<listitem>
							<para>Connection to the Internet, either dial-in or dedicated
</para>
						</listitem>
						<listitem>
							<para>GSM modem (Wavecom WM02, Nokia Premicell or Siemens M20T) <emphasis role="bold">or</emphasis> subscription to an SMS Centre (SMSC) <emphasis role="bold">or</emphasis> GSM mobile phone with integrated modem, for sending and receiving SMS messages
</para>
						</listitem>
					</itemizedlist>
				</section>
			</section>
			<section>
				<title>2.3 Optional Software Included with the Alligata Server
</title>
				<para>In addition to the Alligata Server software, the Alligata Server CD-ROM includes the following items of open source software, which you may find useful in setting up Mobile Internet services:
</para>
				<itemizedlist>
					<listitem>
						<para>Apache Web server
</para>
					</listitem>
					<listitem>
						<para>PHP scripting language
</para>
					</listitem>
					<listitem>
						<para>Common Gateway Interface (CGI), HTML parser, HTML tables and WML modules for the Perl scripting language
</para>
					</listitem>
				</itemizedlist>
				<para>The Alligata Server installation program gives you the option of installing any or all of these pieces of software at the same time as installing the Alligata Server.</para>
			</section>
		</chapter>
		<chapter>
			<title>3  About the Alligata  Server</title>
			<section>
				<title>3.1 What is the Alligata Server?
</title>
				<para>The Alligata Server is two applications in one: a WAP gateway and an SMS server.
</para>
				<para>As a WAP gateway, the Alligata Server is an entry point to the Mobile Internet. If you are a system administrator, you can use it to link your company&apos;s employees&apos; or clients&apos; mobile WAP phones to a local intranet or to the whole Mobile Internet. By using your own installation of the Alligata Server rather than a WAP gateway belonging to a telephone network operator or an Internet Service Provider (ISP), you have complete control over what services you offer your WAP phone users, and you can guarantee they will not be restricted to sites &apos;approved&apos; by a network operator or an ISP.
</para>
				<para>As an SMS server, the Alligata Server allows you to send messages to SMS phone users from a computer workstation, and to implement dynamic SMS keyword services such as retrieval of information from the World Wide Web. Although SMS is much less flexible than WAP, it is available on almost all modern Global System for Mobile Telecommunications (GSM) mobile phones. With its SMS messaging features, the Alligata Server provides limited access to Internet content even to users of non-WAP phones.
</para>
				<para>WAP and SMS complement each other. SMS is simple to use and widely available, but limited in its capabilities. WAP offers richer functionality, but as a new technology it is not yet as widespread as SMS. By offering both SMS and WAP functionality, the Alligata Server is a bridge between established and emerging technologies.
</para>
				<para>The Alligata Server is based on the Kannel WAP and SMS gateway for Linux. Kannel is an open source software project; if you would like to know more about it or contribute to it, visit the Kannel Web site at <ulink url="http://www.kannel.org">www.kannel.org</ulink>.
</para>
			</section>
			<section>
				<title>3.2 The Alligata Server, WAP and SMS
</title>
				<para>This section will help you to understand where the Alligata Server fits into the architecture of WAP and SMS. Before you read it, we recommend you read <citetitle>Your Pocket Guide to the Mobile Internet</citetitle>, included in the Alligata Server package. There you will find definitions of the terminology used by the WAP standard, and a description of how the WAP components fit together.
</para>
				<para>Every WAP phone is configured by default to use a single WAP gateway to gain access to the Mobile Internet. This gateway can be hosted by an ISP, by the phone user&apos;s employer, or by any third party with access to the Mobile Internet. A phone can contain configurations for several gateways, but it can only use a single gateway for the duration of a session. If you want to change gateways, you have to close down your Mobile Internet session, switch your phone&apos;s settings to the new gateway, and reconnect to the Mobile Internet.
</para>
				<para>The conceptual model into which the Alligata Server fits is shown in Figure 3.1.
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="wapdiagsmall&figtype;">
					</imageobject>
				</mediaobject>
				<para>A signal sent by a mobile device is picked up by one of a network operator&apos;s base stations. It is then routed through the mobile network to the Alligata Server using User Datagram Protocol (UDP). If it is an SMS message, it is first sent to the network&apos;s <emphasis role="bold">SMS Centre (SMSC)</emphasis>. The SMSC&apos;s main job is to hold pending SMS messages for recipients whose phones are turned off or otherwise inaccessible.
</para>
				<para>Once the Alligata Server has received a WAP data packet from a client and decompressed it, it uses Hypertext Transfer Protocol (HTTP) to retrieve data from the relevant content server on the Mobile Internet.
</para>
				<para>On receiving an SMS message, the Alligata Server scans it for keywords and parameters listed in its configuration file (see Section 13.1), then sends an automatic reply to the client device depending on which keyword and parameters it encountered. This reply can consist of static text, or it can be retrieved from a local file, a WAP site or a World Wide Web page.
</para>
				<para>The Alligata Server&apos;s reply to an SMS message is another SMS message. This means that, in principle, it has to be sent to the relevant network operator&apos;s SMSC in order to be routed to the recipient device (or stored if the recipient device is not accessible). Most network operators charge a fee for terrestrial access to their SMSCs, but the Alligata Server allows you to circumvent this if you own a GSM modem, or a mobile phone that includes a GSM modem such as the Nokia 7110 or 6210. The Alligata Server can use the modem to send SMS messages directly over the airwaves. This way, you will get charged the same rates as mobile phone users for sending SMS messages from your computer workstation. See Section 9.3.2 for details of how to send messages using a GSM modem.
</para>
			</section>
			<section>
				<title>3.3 Inside the Alligata Server
</title>
				<para>The Alligata Server is a collection of three programs: a Bearer Box, a WAP Box and an SMS Box. In fact, an implementation of the Alligata Server can include any number of WAP Boxes and SMS Boxes, all linked to a single Bearer Box.
</para>
				<para>All incoming messages pass through the Bearer Box. The Bearer Box performs preliminary operations on each message and forwards it on to a WAP or an SMS Box depending on whether it is a WAP or an SMS message.
</para>
				<para>A WAP Box implements the WAP protocol stack on incoming WAP messages (apart from Wireless Datagram Protocol (WDP), which is implemented by the Bearer Box). It decompresses the WAP data and forwards requests to Internet servers using HTTP (see the booklet <citetitle>Your Pocket Guide to the Mobile Internet</citetitle> for more details). It then handles the replies from the HTTP servers, compresses the replies, implements the Wireless Session Protocol (WSP) and Wireless Transaction Protocol (WTP) layers of the WAP protocol stack on them, and sends them on to the Bearer Box. The Bearer Box implements the WDP layer, and sends the replies to the client device.
</para>
				<para>An SMS Box scans incoming SMS messages for keywords listed in the Alligata Server configuration file. It carries out the function associated with the keyword - for example, retrieving a piece of text from a Web page - and sends a reply SMS message, via the Bearer Box, to the client device.
</para>
				<section>
					<title>3.3.1 Program States
</title>
					<para>At any given time, the Alligata Server can be in one of four states:
</para>
					<itemizedlist>
						<listitem>
							<para>Running. The Alligata Server accepts, processes and sends files and messages normally.
</para>
						</listitem>
						<listitem>
							<para>Suspended. The Alligata Server does not accept any new WAP requests or messages from SMSCs. The Bearer Box does not allow new WAP or SMS Boxes to connect to it. No messages or files are sent out.
</para>
						</listitem>
						<listitem>
							<para>Isolated. The Alligata Server does not accept any new WAP requests or messages from SMSCs. However, it continues processing messages already in its system, and accepts SMS messages sent via HTTP (see Section 13.2).
</para>
						</listitem>
						<listitem>
							<para>Shutdown. The Alligata Server performs the shutdown procedure. New WAP requests and SMS messages are refused. Requests already being processed are carried through. When all queues in the boxes have been processed, the Alligata Server closes down.
</para>
						</listitem>
					</itemizedlist>
					<para>You can change the state of the Alligata Server using HTTP administration commands. See Section 8.2.2.
</para>
					<para>There follows a more detailed look at the components of the Alligata Server. You do not need to know this information to use the Alligata Server, but you may find it of interest.
</para>
				</section>
				<section>
					<title>3.3.2 Bearer Box
</title>
					<para>The Bearer Box is the interface between the mobile telephone network and the rest of the Alligata Server. It receives data from mobile phones via network bearer services or SMSCs.
</para>
					<para>On receiving a WAP data packet from a mobile device, the Bearer Box implements the WDP layer of the WAP protocol stack on it, and sends it on to a WAP Box. If a session is already running between the Alligata Server and the client device, then the message is sent to the same WAP Box as previous messages from the device. If, on the other hand, the message is the first to be received from that client in the current session, then it is sent to a WAP box at random. A basic system of load balancing is used to avoid bottlenecks forming in any single WAP Box. Load balancing works as follows: at regular intervals, each WAP Box sends a &apos;heartbeat&apos; message (see Section 3.3.3) to the Bearer Box indicating its load - that is, how many sessions it is currently handling. If this load is significantly higher than the load of the least busy WAP box, then the Bearer Box stops sending requests from new clients to the busier WAP box. When the load of the busier WAP Box has fallen sufficiently, or the load of the other WAP Boxes has increased to near its own, the busier WAP Box starts to accept requests from new clients again.
</para>
					<para>Messages are distributed among the SMS Boxes in the same way as among as the WAP Boxes. That is, the Bearer Box sends all messages from a particular client to the same SMS Box; it assigns messages from new clients to an SMS Box at random; and it uses load balancing to prevent unnecessary congestion in any particular SMS Box.
</para>
					<para>Within the Alligata Server, the Bearer Box acts as a server to the WAP or SMS Boxes. Once running, it keeps a list of all the WAP and SMS Boxes connected to it. This list starts out empty, and is extended as boxes start up and announce their presence. The Bearer Box is in constant communication with the WAP and SMS Boxes via &apos;heartbeat&apos; messages (see Section 3.3.3), and dynamically updates its list of connected WAP and SMS Boxes as new boxes connect and old ones disconnect.
</para>
					<para>As well as receiving incoming messages, the Bearer Box processes all outgoing messages from the Alligata Server&apos;s WAP and SMS Boxes, adapting each message to the bearer service of the client&apos;s network. In the case of WAP messages, it also implements the WDP layer of the WAP protocol stack.
</para>
					<para>Since all incoming and outgoing messages pass through a single Bearer Box, there is a risk of bottlenecks arising when traffic becomes very heavy. The Alligata Server is designed so that the Bearer Box does as little processing on each data packet as possible, thereby reducing this risk (particularly if there are several WAP and SMS Boxes running on different computers).
</para>
				</section>
				<section>
					<title>3.3.3 Communication Between the Boxes
</title>
					<para>Data is exchanged between the Bearer Box and the WAP and SMS Boxes via Transmission Control Protocol (TCP) stream. TCP is a protocol suited for use in wide area networks (such as the Internet), and its incorporation into the Alligata Server means that the Bearer Box, WAP Boxes and SMS Boxes can be run on separate computers, if required. The advantages of this set-up are clear: it means that, outside the Bearer Box, groups of packets can be processed simultaneously, and therefore the Alligata Server can process high volumes of messages very quickly.
</para>
					<para>If the TCP stream between the Bearer Box and a WAP or SMS Box fails for any reason, the Bearer Box notices this and removes the disconnected box from its list of available boxes. Any packets from phones that were routed to this box are then treated as packets from new clients, and redirected by the Bearer Box to an alternative WAP Box. When a WAP Box receives a message from a new client that it identifies as being from the middle of a session, it sends an error message to the client device.
</para>
					<para>A WAP or SMS Box can also go &apos;catatonic&apos;: its TCP stream to the Bearer Box is still running, but it is not responding to any messages. So that the Bearer Box knows when this has happened, WAP and SMS Boxes send &apos;heartbeat&apos; packets at regular intervals, effectively telling the Bearer Box that they are running and functioning normally. If the Bearer Box stops receiving heartbeat messages from another box, it assumes there is a problem even though the TCP stream may still be running, and removes the box from its list. When the ailing box recovers and announces its presence, the Bearer Box reopens the connection.
</para>
				</section>
				<section>
					<title>3.3.4 WAP Box
</title>
					<para>A WAP Box receives data in WDP packets through its TCP connection with the Bearer Box. It implements the and WSP layers of the WAP protocol stack on the packets, and then decompresses them. 
</para>
					<para>Each incoming WDP packet is handled by a single program thread. This thread creates and manages a WTP state machine and, where necessary, a WSP state machine for the packet. The same WTP machine and WSP machine handle all packets from a given client session.
</para>
					<para>If a packet arrives in a WAP Box while the WTP machine for which it is destined is still processing the previous packet, then the WAP Box sets up a queue specific to that WTP machine. This is preferable to creating a new thread for waiting WDP packets, as it reduces the risk of the WAP Box&apos;s thread table becoming full when traffic is very heavy.
</para>
					<para>Once the WTP and WSP layers of the WAP protocol stack have been implemented on the incoming message, the WAP Box converts it into an HTTP request, and sends it to the relevant server on the Mobile Internet.
</para>
					<para>On receiving an HTTP reply from the Mobile Internet server, the WAP Box compresses the reply, implements the WSP and WTP layers of the WAP protocol stack on it, and sends it to the Bearer Box along the TCP connection.
</para>
				</section>
				<section>
					<title>3.3.5 SMS Box
</title>
					<para>The design of an SMS Box is straightforward. An SMS Box receives SMS messages from the Bearer Box via its TCP connection, parses each message in order to extract keywords and parameters from it, and then executes a service according to which keyword the message contains. The keyword is the first word in the message; any other words are interpreted as parameters. See Section 13.1 for more information.
</para>
					<para>If the SMS service in question has a url variable defined in the configuration file (see Section 9.3.3), then the SMS Box sends an HTTP request to the appropriate URL, retrieves the data, pulls out the content between the prefix and the suffix strings as specified in the configuration file, formats this content as an SMS message or messages, and sends the SMS message(s) to the Bearer Box via the TCP stream. The Bearer Box sends the message back to the client device via an SMSC.
</para>
					<para>Other services the SMS Box can provide include sending a fixed text message or the content of a local file in response to a keyword. For more information, see Sections 9.3 and 13.1.
</para>
					<para>The SMS Box also listens for SMS messages arriving via HTTP from computer workstations. It converts these messages from HTTP into true SMS format, and sends them on to the Bearer Box to be conveyed to mobile devices. See Section 13.2 for details of how to send SMS messages from a computer workstation.
</para>
				</section>
			</section>
		</chapter>
		<chapter>
			<title>4  Installation from a Graphical User Interface</title>
			<para>If your Linux or Solaris system includes a graphical user interface, the installation program automatically installs the Alligata Server using the graphical procedure described in this section.
</para>
<FormalPara>
<title>To install the Alligata Server from a Linux/Solaris graphical user interface:</title>
<Para>
			<orderedlist inheritnum="ignore" continuation="restarts">

				<listitem>
					<para>Place the Alligata Server CD-ROM in the CD-ROM drive.
</para>
					<para>If your version of Linux or Solaris automounts CD-ROMs, a file manager window will open, showing the contents of the directory into which the CD-ROM has been mounted. (In Linux this directory is usually <filename moreinfo="none">/mnt/cdrom</filename>, in Solaris it is usually <filename moreinfo="none">/cdrom/cdrom0</filename>.)
</para>
					<para>If you are running your Linux/Solaris session as <emphasis role="bold">root</emphasis>, you can continue by double-clicking the <guiicon moreinfo="none">install</guiicon> icon in the file manager window. This will take you straight to step 8.
</para>
				</listitem>
				<listitem>
					<para>Open a terminal window.
</para>
				</listitem>
				<listitem>
					<para>In the terminal window, type </para>
					<para>
						<userinput moreinfo="none">
							su
						</userinput>
					</para>
					<para> at the command prompt and press ENTER.
</para>
					<para>You will be prompted for the <emphasis role="bold">root</emphasis> password.
</para>
				</listitem>
				<listitem>
					<para>Type the password of the <emphasis role="bold">root</emphasis> user and press ENTER.
</para>
					<para>You will be returned to the command prompt.
</para>
				</listitem>
				<listitem>
					<para>At the command prompt, type
</para>
					<para>
						<userinput moreinfo="none">
							mount <replaceable>path_of_your_system&apos;s_CD-ROM_mount_point</replaceable>
						</userinput>
					</para>
					<para>(In Linux the path of the CD-ROM mount point is usually <filename moreinfo="none">/mnt/cdrom</filename>, in Solaris it is usually <filename moreinfo="none">/cdrom/cdrom0</filename> or something similar.) For example:
</para>
					<para>
						<userinput moreinfo="none">
							mount /mnt/cdrom
						</userinput>
					</para>
					<para>Press ENTER.
</para>
					<para>If your version of Linux or Solaris automounts CD-ROMs, you can ignore this step.
</para>
				</listitem>
				<listitem>
					<para>Change directory to your system&apos;s CD-ROM mount point. For example, Linux users should type </para>
					<para>
						<userinput moreinfo="none">
							cd /mnt/cdrom
						</userinput>
					</para>
					<para> and press ENTER.
</para>
				</listitem>
				<listitem>
					<para>Type </para>
					<para>
						<userinput moreinfo="none">./install</userinput>
					</para>
					<para> and press ENTER.
</para>
				</listitem>
				<listitem>
					<formalpara>
						<title> Solaris users</title>
						<para>The installation program requires Perl to be installed on your system. If Perl is not found (for example, if you are running the default Solaris 7 system), you will be prompted to install it:</para>
					</formalpara>
					<screen format="linespecific">Perl is not installed or is not in your command path.
  Do you want to install Perl now ? (y/N)
</screen>
					<para>Type Y, ENTER to install Perl or N, ENTER to abort installation.
</para>
				</listitem>
				<listitem>
					<para>A dialog box opens containing information on the licences used by the Alligata Server package (see Figure 4.1).</para>
					<mediaobject>
						<imageobject>
							<imagedata fileref="licences&figtype;">
						</imageobject>
						<caption>
							<para>Figure 4.1: Licence dialog box
</para>
						</caption>
					</mediaobject>
					<para>If you agree with the terms of the listed licence agreements, click &apos;I Agree&apos;.
</para>
				</listitem>
				<listitem>
					<para>The main installation dialog box appears (see Figure 4.2).
</para>
					<mediaobject>
						<imageobject>
							<imagedata fileref="maininst&figtype;">
						</imageobject>
						<caption>
							<para>Figure 4.2: Main Alligata Server installation dialog box
</para>
						</caption>
					</mediaobject>
					<para>
						<emphasis role="bold">
							<emphasis role="bold">Note:</emphasis>
						</emphasis> the Alligata Server installation program detects whether each item is <interface moreinfo="none">already</interface> installed on your system. Items already installed do not appear in the installation dialog box. For example, if your computer already contains an installation of the Apache server, the option &apos;Apache Web server&apos; will not appear in the dialog box.
</para>
					<para>In the dialog box, select the items you want to install. See Figure 4.3 for an explanation of the options in the installation dialog box.
</para>
					<variablelist>
						<title>Figure 4.3(a) Global Options
</title>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Install path
</guilabel>
							</term>
							<listitem>
								<para>Shows the directory into which the Alligata Server program files are installed. Defaults to <filename moreinfo="none">/usr/share/alligata</filename> in Linux, and <filename moreinfo="none">/opt/TGLBallig</filename> in Solaris. The install path cannot be changed.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Binary directory
</guilabel>
							</term>
							<listitem>
								<para>Shows the directory into which the Alligata Server&apos;s binary files are installed. Defaults to <filename moreinfo="none">/usr/bin</filename>, and cannot be changed.
</para>
							</listitem>
						</varlistentry>
					</variablelist>
					<variablelist>
						<title>Figure 4.3(b) Installation Options
</title>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Alligata Gateway (Kannel core)
</guilabel>
							</term>
							<listitem>
								<para>Installs the Alligata Server on the current computer, including the Bearer Box, one WAP Box and one SMS Box. If you want to install extra WAP and SMS Boxes on other computers, see Section 6.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Start the Bearer Box at boot
</guilabel>
							</term>
							<listitem>
								<para>If selected, causes the Alligata Server&apos;s Bearer Box to be started automatically every time the computer is booted.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Start the WAP Box at boot
</guilabel>
							</term>
							<listitem>
								<para>If selected, causes the WAP Box to be started automatically every time the computer is booted.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Start the SMS Box at boot
</guilabel>
							</term>
							<listitem>
								<para>If selected, causes the SMS Box to be started automatically every time the computer is booted.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Alligata example sites
</guilabel>
							</term>
							<listitem>
								<para>Installs the Alligata Server example WAP sites. In Linux, these are installed into <filename moreinfo="none">/home/httpd/alligata/wml</filename>. In Solaris 7, they are installed into <filename moreinfo="none">/usr/local/apache/alligata/wml</filename>. In Solaris 8, they are installed into <filename moreinfo="none">/etc/apache/alligata/wml</filename>.
</para>
								<para>Section 12 provides a guide to viewing, using and understanding the example sites.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Apache Web server
</guilabel>
							</term>
							<listitem>
								<para>Installs the Apache Web server. You will need Apache, or a similar HTTP server, to view the example sites.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Development files for the Apache Web server (Linux only)
</guilabel>
							</term>
							<listitem>
								<para>Installs the Apache development package. You will need this package if you plan to extend Apache, for example to write a new module.
</para>
								<para>If the computer already contains an installation of Apache, the Alligata Server installation program automatically updates the Apache configuration for WML and Wireless Bitmap (WBMP) file formats.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Apache manuals (Linux only)
</guilabel>
							</term>
							<listitem>
								<para>Installs the Apache manuals into the directory <filename moreinfo="none">/home/httpd/html/manual</filename>. To view the index page, open the file <filename moreinfo="none">index.html</filename> in a Web browser such as Netscape or Lynx.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">PHP language
</guilabel>
							</term>
							<listitem>
								<para>Installs the PHP scripting language. PHP is used by two of the Alligata Server example WAP sites. It can be very useful for developing Web and WAP applications.
</para>
								<para>In the Solaris installation, this option includes the PHP IMAP module (see below).
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">IMAP module for the PHP language (Linux only)
</guilabel>
							</term>
							<listitem>
								<para>Installs the IMAP PHP module. This module is used in the example WAP site PAT for liaising with your e-mail server.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Documentation for the PHP language (Linux only)
</guilabel>
							</term>
							<listitem>
								<para>Installs documentation for the PHP language into the directory <filename moreinfo="none">/home/httpd/html/manual/mod/mod_php3</filename>. To view the index page, open the file <filename moreinfo="none">index.html</filename> in a Web browser such as Netscape or Lynx.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">CGI module for Perl
</guilabel>
							</term>
							<listitem>
								<para>Installs the CGI Perl module, version 2.69. This module facilitates the output of Web files from Perl scripts. It is needed to view the Alligata Server&apos;s Perl example site. (The CGI modules supplied with most Linux distributions are too old and will not work with the example Perl site.)
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">HTML module for Perl
</guilabel>
							</term>
							<listitem>
								<para>Installs the HTML Perl module. This module is needed to view the Alligata Server&apos;s Perl example site.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">HTML tables module for Perl
</guilabel>
							</term>
							<listitem>
								<para>Installs the HTML tables Perl module. This module is needed to view the Alligata Server&apos;s Perl example site.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">WML module for Perl
</guilabel>
							</term>
							<listitem>
								<para>Installs the WML Perl module. This module is needed to view the Alligata Server&apos;s Perl example site.
</para>
							</listitem>
						</varlistentry>
					</variablelist>
				</listitem>
				<listitem>
					<para>Click <guibutton moreinfo="none">Begin Install</guibutton>.
</para>
					<para>The Alligata Server will be installed on your system. Installation progress information appears in the terminal window from which you launched the installation program.
</para>
				</listitem>
				<listitem>
					<para>When all the files have been copied to your system, the dialog box in Figure 4.4 is displayed.
</para>
					<mediaobject>
						<imageobject>
							<imagedata fileref="nearlydone&figtype;">
						</imageobject>
						<caption>
							<para>Figure 4.4: &apos;Thank You&apos; dialog box
</para>
						</caption>
					</mediaobject>
					<para>Click <guibutton moreinfo="none">Launch browser</guibutton> to go to the 3G LAB Web site, where you can receive information about Alligata Server updates and support.
</para>
					<para>Click <guibutton moreinfo="none">Exit</guibutton> to cancel the installation.
</para>
					<para>Click <guibutton moreinfo="none">View Readme</guibutton> to view the Readme file.
</para>
					<para>Click <guibutton moreinfo="none">Continue</guibutton> to complete the installation.
</para>
				</listitem>
				<listitem>
					<para>If you clicked <guibutton moreinfo="none">Continue</guibutton>, the dialog box in Figure 4.5 will appear.
</para>
					<mediaobject>
						<imageobject>
							<imagedata fileref="done&figtype;">
						</imageobject>
						<caption>
							<para>Figure 4.5: &apos;Install Complete&apos; dialog box</para>
						</caption>
					</mediaobject>
				</listitem>
				<listitem>
					<para>Click <guibutton moreinfo="none">Exit</guibutton> to finish the installation, or <guibutton moreinfo="none">View Readme</guibutton> to view the Readme file.
</para>
				</listitem>
				<listitem>
					<para>To start the Alligata Server, follow the instructions in Section 8.1.
</para>
				</listitem>
			</orderedlist>
</Para>
</FormalPara>

		</chapter>
		<chapter>
			<title>5  Installation from the Command Line</title>
			<para>If your Linux or Solaris system does not include a graphical user interface, the installation program will install the Alligata Server using the command line procedure described in this section.</para>
<FormalPara>
<title>To install the Alligata Server from the command line:</title>
<Para>
			<orderedlist inheritnum="ignore" continuation="restarts">
				<listitem>
					<para>Place the Alligata Server CD-ROM in the CD-ROM drive.
</para>
				</listitem>
				<listitem>
					<para>At the command prompt, type </para>
					<para>
						<userinput moreinfo="none">
							su
						</userinput>
					</para>
					<para> and press ENTER.
</para>
					<para>You will be prompted for the <emphasis role="bold">root</emphasis> password.
</para>
				</listitem>
				<listitem>
					<para>Type the password of the <emphasis role="bold">root</emphasis> user and press ENTER.
</para>
					<para>You will be prompted for the <emphasis role="bold">root</emphasis> password.
</para>
				</listitem>
				<listitem>
					<para>
At the command prompt, type
</para>
					<para>
						<userinput moreinfo="none">
							mount
							<replaceable>path_of_your_system&apos;s_CD-ROM_mount_point
</replaceable>
						</userinput>
					</para>
					<para>
(In Linux the path of the CD-ROM mount point is usually <filename moreinfo="none">/mnt/cdrom</filename>, in Solaris it is usually <filename moreinfo="none">/cdrom/cdrom0</filename> or something similar.) For example:
</para>
					<para>
						<userinput moreinfo="none">
							mount /mnt/cdrom
						</userinput>
					</para>
					<para>Press ENTER.
</para>
					<para>If your version of Linux or Solaris automounts CD-ROMs, you can ignore this step.
</para>
				</listitem>
				<listitem>
					<para>Change directory to your system&apos;s CD-ROM mount point. For example, Linux users should type

</para>
					<para>
						<userinput moreinfo="none">
							cd /mnt/cdrom
						</userinput>
					</para>
					<para>and press ENTER.
</para>
				</listitem>
				<listitem>
					<para>Type </para>
					<para>
						<userinput moreinfo="none">
							./install
						</userinput>
					</para>
					<para> and press ENTER.
</para>
				</listitem>
				<listitem>
					<formalpara>
						<title>Solaris users</title>
						<para>The installation program requires Perl to be installed on your system. If Perl is not found (for example, if you are running the default Solaris 7 system), you will be prompted to install it:
</para>
					</formalpara>
					<screen format="linespecific">Perl is not installed or is not in your command path.
  Do you want to install Perl now ? (y/N)
</screen>
					<para>Type Y, ENTER to install Perl or N, ENTER to abort installation.
</para>
				</listitem>
				<listitem>
					<para>Information on the licence agreements used by the Alligata Server package will be displayed on the screen, together with the question,
</para>
					<screen format="linespecific">Do you agree with the licence? [Y/n]
</screen>
					<para>If you agree, type Y, ENTER or just ENTER.
</para>
				</listitem>
				<listitem>
					<para>Information on the installation and binary paths appears on the screen. For example:
</para>
					<screen format="linespecific">Install path set to: /usr/share/alligata
Binary path set to: /usr/bin
</screen>
					<para>
						<emphasis role="bold">Note:</emphasis> you cannot change the installation and binary paths.
</para>
				</listitem>
				<listitem>
					<para>You will be presented with the questions listed in Figure 5.1. In response to each question, type Y, ENTER for &apos;yes&apos;, N, Enter for &apos;no&apos;, or ?, ENTER to receive help.
</para>
					<para>Pressing just ENTER in response to a question selects the first (capitalised) option in the square brackets after the question. For example, if the square brackets look like this:
</para>
					<screen format="linespecific">[N/y/?]</screen>
					<para>then pressing ENTER is equivalent to pressing N, ENTER.
</para>
					<para>
						<emphasis role="bold">Note:</emphasis> the Alligata Server installation program detects whether each item is already installed on your system. You will not be asked whether you want to install items that are already installed. For example, if your computer already contains an installation of the Apache server, the question &apos;Install Apache Web server?&apos; will be omitted.
</para>
					<variablelist>
						<title>Figure 5.1 Command Line Installation Options
</title>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Install the Alligata Gateway (Kannel core)? [Y/n/?]
</computeroutput>
							</term>
							<listitem>
								<para>Y installs the Alligata Server on the current computer, including the Bearer Box, one WAP Box and one SMS Box. If you want to install extra WAP and SMS Boxes on other computers, see Section 6.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Start the Bearer Box at boot? [N/y/?]
</computeroutput>
							</term>
							<listitem>
								<para>Y causes the Alligata Server&apos;s Bearer Box to be started automatically every time the computer is booted.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Start the WAP Box at boot [N/y/?]
</computeroutput>
							</term>
							<listitem>
								<para>Y causes the WAP Box to be started automatically every time the computer is booted.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Start the SMS Box at boot [N/y/?]
</computeroutput>
							</term>
							<listitem>
								<para>Y causes the SMS Box on the current computer to be started automatically every time the computer is booted.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Install the Alligata examples? [Y/n/?]
</computeroutput>
							</term>
							<listitem>
								<para>Y installs the Alligata Server example WAP sites. In Linux, these are installed into <filename moreinfo="none">/home/httpd/alligata/wml</filename>. In Solaris 7, they are installed into <filename moreinfo="none">/usr/local/apache/alligata/wml</filename>. In Solaris 8, they are installed into <filename moreinfo="none">/etc/apache/alligata/wml</filename>.</para>
								<para>Section 12 provides a guide to viewing, using and understanding the example sites.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Install Apache Web server? [N/y/?]
</computeroutput>
							</term>
							<listitem>
								<para>Y installs the Apache Web server. You will need Apache to view the example sites.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Install Development files for the Apache Web server? [N/y/?] (Linux only)
</computeroutput>
							</term>
							<listitem>
								<para>Y installs the Apache development package. You will need this package if you plan to extend Apache, for example to write a new module.</para>
								<para>If the computer already contains an installation of Apache, the Alligata Server installation program updates the Apache configuration for WML and WBMP file formats.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Install Apache manuals? [N/y/?] (Linux only)
</computeroutput>
							</term>
							<listitem>
								<para>Y installs the Apache manuals into the directory <filename moreinfo="none">/home/httpd/html/manual</filename>. To view the index page, open the file <filename moreinfo="none">index.html</filename> in a Web browser such as Netscape or Lynx.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Install PHP language? [N/y/?]
</computeroutput>
							</term>
							<listitem>
								<para>Y installs the PHP scripting language. PHP is used by two of the Alligata Server example WAP sites. It can be very useful for developing Web and WAP applications.</para>
								<para>In the Solaris installation, this option includes the PHP IMAP module (see below).
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Install IMAP module for the PHP language? [N/y/?] (Linux only)
</computeroutput>
							</term>
							<listitem>
								<para>Y installs the IMAP PHP module. This module is used in the example WAP site PAT for liaising with your e-mail server.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Install Documentation for the PHP language? [N/y/?] (Linux only)
</computeroutput>
							</term>
							<listitem>
								<para>Y installs documentation for the PHP language into the directory <filename moreinfo="none">/home/httpd/html/manual/mod/mod_php3</filename>. To view the index page, open the file <filename moreinfo="none">index.html</filename> in a Web browser such as Netscape or Lynx.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Install CGI module for Perl? [N/y/?]
</computeroutput>
							</term>
							<listitem>
								<para>Y installs the Common Gateway Interface (CGI) Perl module, version 2.69. This module facilitates the output of Web files from Perl scripts. It is needed to view the Alligata Server&apos;s Perl example site. (The CGI modules supplied with most Linux distributions are too old and will not work with the example Perl site.)
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Install HTML module for Perl? [N/y/?]
</computeroutput>
							</term>
							<listitem>
								<para>Y installs the HTML Perl module. This module is needed to view the Alligata Server&apos;s Perl example site.</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Install HTML tables modules for Perl? [N/y/?]
</computeroutput>
							</term>
							<listitem>
								<para>Y installs the HTML tables Perl module. This module is needed to view the Alligata Server&apos;s Perl example site.</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<computeroutput moreinfo="none">Install WML module for Perl? [N/y/?]
</computeroutput>
							</term>
							<listitem>
								<para>Y installs the WML Perl module. This module is needed to view the Alligata Server&apos;s Perl example site.</para>
							</listitem>
						</varlistentry>
					</variablelist>
				</listitem>
				<listitem>
					<para>The following messages (or equivalents) will be displayed on the screen:
</para>
					<screen format="linespecific">Installing to /usr/share/alligata
xMb available, 5Mb will be installed
Continue install? [Y/n]</screen>
					<para>Selecting Y installs the Alligata Server and any other selected items on your system.
</para>
					<para>Installation progress is displayed on the screen.
</para>
				</listitem>
				<listitem>
					<para>When installation is complete, the following messages will be displayed on the screen:
</para>
					<screen format="linespecific">Thank you for installing the Alligata Server, 
3G LAB&apos;s Mobile Internet Server!
Please visit our Web site for updates and support.
Would you like to launch a Web browser? [Y/n]</screen>
					<para>To visit the 3G LAB Web site, select Y.
</para>
					<para>If you select N, the following message will be displayed on the screen:
</para>
					<screen format="linespecific">Installation complete.
</screen>
				</listitem>
				<listitem>
					<para>To start the Alligata Server, follow the instructions in Section 8.1.</para>
				</listitem>
			</orderedlist>
</Para>
</FormalPara>

		</chapter>
		<chapter>
			<title>6  Installing Multiple WAP and SMS Boxes</title>
			<para>The Alligata Server installation program installs a Bearer Box, a WAP Box and an SMS Box onto a personal computer running Linux or Solaris. 
</para>
			<para>The following instructions assume you have already installed the Alligata Server on a personal computer running Linux or Solaris (&apos;Computer A&apos;). If you have not yet installed the Alligata Server, please follow the instructions in Section 4 for installation from a graphical user interface, or Section 5 for installation from the command line.
</para>
			<para>You can add any number of extra WAP and SMS Boxes to an installation of the Alligata Server.
</para>

<FormalPara>
<title>To add a WAP Box to an installation of the Alligata Server:</title>
<Para>

			<orderedlist inheritnum="ignore" continuation="restarts">
				<listitem>
					<para>Connect a computer running Linux or Solaris (&apos;Computer B&apos;) to Computer A using TCP/IP.</para>
				</listitem>
				<listitem>
					<para>Install a complete copy of the Alligata Server onto Computer B as described in Sections 4 and 5.
</para>
				</listitem>
				<listitem>
					<para>On Computer B, open the configuration file <filename moreinfo="none">/etc/alligata.conf</filename> in a text editor such as vi or Emacs.
</para>
					<para>
						<emphasis role="bold">About the configuration file:</emphasis> the Alligata Server configuration is a list of variables divided into groups. Each group begins with the line</para>
					<para>
						<userinput moreinfo="none">
							group = <replaceable>x</replaceable>
						</userinput>
					</para>
					<para> where <replaceable>x</replaceable> is a group identifier. A blank line signifies the end of a group. (Full instructions for configuring the Alligata Server are provided in Section 9.)
</para>
				</listitem>
				<listitem>
					<para>In the configuration group beginning with the line </para>
					<para>
						<userinput moreinfo="none">
							group = wapbox
						</userinput>
					</para>
					<para>, change the value of the variable </para>
					<para>
						<userinput moreinfo="none">
							bearerbox-host
						</userinput>
					</para>
					<para> to the IP address or URL of the computer hosting the Bearer Box (that is, computer A). For example:
</para>
					<para>
						<userinput moreinfo="none">
							bearerbox-host = 10.0.0.1
						</userinput>
					</para>
				</listitem>
				<listitem>
					<para>Repeat steps 1-4 on a new computer for each WAP Box you want to add.
</para>
				</listitem>
			</orderedlist>
</Para>
</FormalPara>
<FormalPara>
<title>To add an SMS Box to an installation of the Alligata Server:</title>
<Para>

			<orderedlist inheritnum="ignore" continuation="restarts">
				<listitem>
					<para>Connect a computer running Linux or Solaris (&apos;Computer C&apos;) to Computer A using TCP/IP.
</para>
				</listitem>
				<listitem>
					<para>Install a complete copy of the Alligata Server onto Computer C as described in Sections 4 and 5.
</para>
				</listitem>
				<listitem>
					<para>On Computer C, open the configuration file <filename moreinfo="none">/etc/alligata.conf</filename> in a text editor such as vi or Emacs.
</para>
					<para>
						<emphasis role="bold">About the configuration file:</emphasis> the Alligata Server configuration is a list of variables divided into groups. Each group begins with the line where <replaceable>x</replaceable> is a group identifier. A blank line signifies the end of a group. (Full instructions for configuring the Alligata Server are provided in Section 9.)
</para>
					<para>
						<userinput moreinfo="none">
							group = <replaceable>x</replaceable>
						</userinput>
					</para>
				</listitem>
				<listitem>
					<para>In the configuration group beginning with the line </para>
					<para>
						<userinput moreinfo="none">
							group = smsbox
						</userinput>
					</para>
					<para>, change the value of the variable bearerbox-host to the IP address or URL of the computer hosting the Bearer Box (that is, computer A). For example:
</para>
					<para>
						<userinput moreinfo="none">
							bearerbox-host = 10.0.0.1
						</userinput>
					</para>
				</listitem>
				<listitem>
					<para>Repeat steps 1-4 on a new computer for each SMS Box you want to add.
</para>
				</listitem>
			</orderedlist>
</Para>
</FormalPara>

		</chapter>
	</part>
	<part>
		<title>Part Two: Using the Alligata Server</title>
		<chapter>
			<title>7  Introduction to Part Two</title>
			<para>Welcome to Part Two of the <citetitle>Alligata Server User Manual, Using the Alligata Server</citetitle>. This part of the user manual explains how to:
</para>
			<itemizedlist>
				<listitem>
					<para>start, stop and administer the Alligata Server
</para>
				</listitem>
				<listitem>
					<para>change the Alligata Server&apos;s configuration settings
</para>
				</listitem>
				<listitem>
					<para>view the example WAP sites provided with the Alligata Server
</para>
				</listitem>
				<listitem>
					<para>create WAP sites using Wireless Markup Language (WML)
</para>
				</listitem>
				<listitem>
					<para>create dynamic WAP sites using the Perl scripting language
</para>
				</listitem>
				<listitem>
					<para>create dynamic WAP sites using the PHP scripting language
</para>
				</listitem>
				<listitem>
					<para>use the Alligata Server&apos;s SMS features to deliver World Wide Web and other content to mobile phones
</para>
				</listitem>
				<listitem>
					<para>use the Alligata Server to send SMS messages from a computer workstation
</para>
				</listitem>
				<listitem>
					<para>configure a mobile phone for a WAP service &apos;over the air&apos; using the Alligata Server&apos;s SMS features
</para>
				</listitem>
			</itemizedlist>
			<para>This part of the user manual assumes you have installed the Alligata Server successfully on a computer workstation running Linux or Solaris. If you have not yet installed the Alligata Server, please follow the installation instructions in Sections 4 to 6.</para>
		</chapter>
		<chapter>
			<title>8  Running the Alligata Server</title>
			<para>
				<emphasis role="bold">Note:</emphasis> to run an Alligata Server command line command, you must be logged in as <emphasis role="bold">root</emphasis>. Therefore, before using any of the command line commands in this section, change to <emphasis role="bold">root</emphasis> as follows:
</para>
			<orderedlist inheritnum="ignore" continuation="restarts">
				<listitem>
					<para>At the command prompt, type su and press ENTER.
</para>
					<para>You will be prompted for the password of <emphasis role="bold">root</emphasis>.</para>
				</listitem>
				<listitem>
					<para>Type the password of <emphasis role="bold">root</emphasis> and press ENTER.
</para>
					<para>You will be returned to the command prompt as <emphasis role="bold">root</emphasis>.
</para>
				</listitem>
			</orderedlist>
			<para>Once the Alligata Server is running, its user will change from <emphasis role="bold">root</emphasis> to that specified by the user variable in the Core group of the configuration file. By default, this user is <emphasis role="bold">alligata</emphasis>.</para>
			<section>
				<title>8.1 Starting the Alligata Server
</title>
				<para>Each box in the Alligata Server needs to be started separately. The Bearer Box must be started before any of the WAP or SMS Boxes. There are three methods of starting the Alligata Server.
</para>
				<para>To start the Alligata Server:
</para>
				<section>
					<title>8.1.1 Method 1
</title>
					<para>If, when you installed the Alligata Server, you selected &apos;Start the Bearer Box at boot&apos;, &apos;Start the WAP Box at boot&apos; or &apos;Start the SMS Box at boot&apos;, then the relevant box will start automatically each time you boot up the computer.
</para>
				</section>
				<section>
					<title>8.1.2 Method 2
</title>
					<section>
						<title>Linux users
</title>
						<para>
At the command prompt, type</para>
						<para>
							<userinput moreinfo="none">
								/etc/rc.d/init.d/<replaceable>box</replaceable> start
							</userinput>
						</para>
						<para>where <replaceable>box</replaceable> is one of the strings <userinput moreinfo="none">bearerbox</userinput>, <userinput moreinfo="none">wapbox</userinput> or <userinput moreinfo="none">smsbox</userinput>. Press ENTER.
</para>
						<para>The procedure to start the Bearer Box, WAP Box and SMS Box on a single Linux workstation is therefore as follows:
</para>
						<orderedlist inheritnum="ignore" continuation="restarts">
							<listitem>
								<para>To start the Bearer Box, type
</para>
								<para>
									<userinput moreinfo="none">
										/etc/rc.d/init.d/bearerbox start
									</userinput>
								</para>
								<para>at the command prompt and press ENTER.
</para>
								<para>The Bearer Box will start up.
</para>
							</listitem>
							<listitem>
								<para>To start the WAP Box, type
</para>
								<para>
									<userinput moreinfo="none">
										/etc/rc.d/init.d/wapbox start
									</userinput>
								</para>
								<para>at the command prompt and press ENTER.
</para>
								<para>The WAP Box will start up.
</para>
							</listitem>
							<listitem>
								<para>To start the SMS Box, type 
</para>
								<para>
									<userinput moreinfo="none">
										/etc/rc.d/init.d/smsbox start

									</userinput>
								</para>
								<para>at the command prompt and press ENTER.
</para>
								<para>The SMS Box will start up.
</para>
							</listitem>
						</orderedlist>
					</section>
					<section>
						<title>Solaris users
</title>
						<para>At the command prompt, type</para>
						<para>
							<userinput moreinfo="none">
								/etc/init.d/	<replaceable>box</replaceable> start
							</userinput>
						</para>
						<para>where <replaceable>box</replaceable> is one of the strings <userinput moreinfo="none">bearerbox</userinput>, <userinput moreinfo="none">wapbox</userinput> or <userinput moreinfo="none">smsbox</userinput>. Press ENTER.
</para>
						<para>The procedure to start the Bearer Box, WAP Box and SMS Box on a single Linux workstation is therefore as follows:
</para>
						<orderedlist inheritnum="ignore" continuation="restarts">
							<listitem>
								<para>To start the Bearer Box, type
</para>
								<para>
									<userinput moreinfo="none">
										/etc/init.d/bearerbox start
									</userinput>
								</para>
								<para>at the command prompt and press ENTER.
</para>
								<para>The Bearer Box will start up.
</para>
							</listitem>
							<listitem>
								<para>To start the WAP Box, type
</para>
								<para>
									<userinput moreinfo="none">
										/etc/init.d/wapbox start

									</userinput>
								</para>
								<para>at the command prompt and press ENTER.
</para>
								<para>The WAP Box will start up.
</para>
							</listitem>
							<listitem>
								<para>To start the SMS Box, type 
</para>
								<para>
									<userinput moreinfo="none">
										/etc/init.d/smsbox start

									</userinput>
								</para>
								<para>at the command prompt and press ENTER.
</para>
								<para>The SMS Box will start up.
</para>
							</listitem>
						</orderedlist>
					</section>
				</section>
				<section>
					<title>8.1.3 Method 3
</title>
					<para>This method of starting the Alligata Server allows you to enter command line options that customise the way each box runs. Using this method, the procedure to start up the Bearer Box, WAP Box and SMS Box on a single workstation is as follows:
</para>
					<orderedlist inheritnum="ignore" continuation="restarts">
						<listitem>
							<para> To start the Bearer Box, type</para>
							<para>
								<userinput moreinfo="none">
									bearerbox
								</userinput>
							</para>
							<para>at the command prompt and press ENTER. You can use command line options to override some of the settings in the configuration file. See <citetitle>Command Line Options</citetitle> below.</para>
							<para>The Bearer Box will start up.
</para>
						</listitem>
						<listitem>
							<para>To start the WAP Box, type
</para>
							<para>
								<userinput moreinfo="none">
									wapbox
								</userinput>
							</para>
							<para>at the command prompt and press ENTER. You can use command line options to override some of the settings in the configuration file. See <citetitle>Command Line Options</citetitle> below.
</para>
							<para>The WAP Box will start up.
</para>
						</listitem>
						<listitem>
							<para>To start the SMS Box, type
</para>
							<para>
								<userinput moreinfo="none">
									smsbox
								</userinput>
							</para>
							<para>at the command prompt and press ENTER. You can use command line options to override some of the settings in the configuration file. See <citetitle>Command Line Options</citetitle> below.
</para>
							<para>The SMS Box will start up.
</para>
						</listitem>
					</orderedlist>
					<para>For each box, you can use a different configuration file from the default file by including the path and name of the relevant file after the command. For example:
</para>
					<para>
						<userinput moreinfo="none">
							bearerbox /etc/alligata2.conf
						</userinput>
					</para>
					<section>
						<title>Command Line Options
</title>
						<para>If you start up the Alligata Server using Method 3, you can include options in the command line you use to start up each box. The format for command line options is
</para>
						<para>
							<userinput moreinfo="none">
								<replaceable>box option value</replaceable>
							</userinput>
						</para>
						<para>For example:
</para>
						<para>
							<userinput moreinfo="none">
								bearerbox -v 2

							</userinput>
						</para>
						<para>The available command line options are shown in Figure 8.1.
<table frame="all">
								<title>Figure 8.1: Alligata Server command line options</title>
								<tgroup cols="2">
									<tbody>
										<row>
											<entry>
												<userinput moreinfo="none">-F <replaceable>file_name</replaceable>
												</userinput>
											</entry>
											<entry>Log file name. Does not override the log file name setting in the configuration file, but outputs to both files.
</entry>
										</row>
										<row>
											<entry>
												<userinput moreinfo="none">-V <replaceable>number_0-4</replaceable>
												</userinput>
											</entry>
											<entry>Verbosity level for output to the log file specified with -F. 0 provides most detail, 4 least. The default value is 1.
</entry>
										</row>
										<row>
											<entry>
												<userinput moreinfo="none">-S</userinput>
											</entry>
											<entry>Suspended. Starts the Alligata Server in suspended state. See Section 3.3.1 for details.
</entry>
										</row>
										<row>
											<entry>
												<userinput moreinfo="none">-I</userinput>
											</entry>
											<entry>Isolated. Starts the Alligata Server in isolated state. See Section 3.3.1 for details.</entry>
										</row>
									</tbody>
								</tgroup>
							</table>
						</para>
					</section>
				</section>
			</section>
			<section>
				<title>8.2 Administering the Alligata Server
</title>
				<section>
					<title>8.2.1  Administering the Alligata Server from the Command Line
</title>
					<para>Each Alligata Server box understands four administration commands that can be entered from the Linux or Solaris command line. These commands must be in the following formats.
</para>
					<formalpara>
						<title>Linux users:
</title>
						<para>
							<userinput moreinfo="none">
								/etc/rc.d/init.d/<replaceable>box command</replaceable>
							</userinput>
						</para>
					</formalpara>
					<formalpara>
						<title>Solaris users:
</title>
						<para>
							<userinput moreinfo="none">
								/etc/init.d/<replaceable>box command
</replaceable>
							</userinput>
						</para>
					</formalpara>
					<para>Replace box with one of the strings bearerbox, wapbox or smsbox. For example:
</para>
					<para>
						<userinput moreinfo="none">
							/etc/rc.d/init.d/wapbox restart
						</userinput>
					</para>
					<para>The available command line commands are shown in Figure 8.2.
</para>
					<table>
						<title>Figure 8.2: Alligata Server command line administration commands
</title>
						<tgroup cols="2">
							<tbody>
								<row>
									<entry>
										<userinput moreinfo="none">start</userinput>
									</entry>
									<entry>Starts the specified box.
</entry>
								</row>
								<row>
									<entry>
										<userinput moreinfo="none">restart</userinput>
									</entry>
									<entry>Shuts down the specified box, then immediately restarts it.
</entry>
								</row>
								<row>
									<entry>
										<userinput moreinfo="none">stop</userinput>
									</entry>
									<entry>Shuts down the specified box.</entry>
								</row>
								<row>
									<entry>
										<userinput moreinfo="none">status</userinput>
									</entry>
									<entry>Outputs a summary of processes currently being run by the specified box.</entry>
								</row>
							</tbody>
						</tgroup>
					</table>
					<section>
						<title>8.2.2 Administering the Alligata Server Using HTTP
</title>
						<para>You can use a set of HTTP commands to set the Alligata Server&apos;s program state (see Section 3.3.1) while it is running. You can also use the <userinput moreinfo="none">status</userinput> command to retrieve information about the Alligata Server&apos;s current activity. Figure 8.3 lists the Alligata Server&apos;s HTTP administration commands.
</para>
<FormalPara>
<title>To send the Alligata Server an HTTP administration command:</title>
<Para>
						<itemizedlist>
							<listitem>
								<para>In the &apos;Location&apos; box of a Web browser, type the command using the following syntax:
</para>
								<para>
									<userinput moreinfo="none">
										http://<replaceable>hostname:port</replaceable>/cgi-bin/<replaceable>command</replaceable>?password=<replaceable>password</replaceable>
									</userinput>
								</para>
								<para>
									<userinput moreinfo="none">
										http://localhost:13004/cgi-bin/suspend?password=PAPaya
									</userinput>
								</para>
								<para>The port number (13004 in the example) must be the same as that defined by the admin-port variable in the Core configuration group (see Section 9.1). The command must be one of the five HTTP administration commands listed in Figure 8.3. The password must be that defined by the admin-password variable in the Core configuration group. (Note that the status command requires no password.)
</para>
								<para>To save having to type a whole URL for each command, you can create an HTML form. Here is one for the <userinput moreinfo="none">shutdown</userinput> command:
</para>
								<programlisting format="linespecific">&lt;form name=&quot;httpadmin&quot; method=&quot;get&quot; 
action=&quot;http://localhost:13004/cgi-bin/shutdown&quot;&gt;
Enter Alligata Server administration password:
&lt;br&gt;
&lt;input type=&quot;text&quot; name=&quot;password&quot; value=&quot;&quot;&gt;
&lt;input type=&quot;submit&quot; value=&quot;Shut down the Alligata Server&quot;&gt;
&lt;/form&gt;
</programlisting>
								<table>
									<title>Figure 8.3: Alligata Server HTTP administration commands
</title>
									<tgroup cols="2">
										<tbody>
											<row>
												<entry>
													<userinput moreinfo="none">status</userinput>
												</entry>
												<entry>Retrieves the following information about the Alligata Server&apos;s current activity: the program state; the total number of data packets queuing in the system; the total number of WAP Box and SMS Box connections. No password is required.
</entry>
											</row>
											<row>
												<entry>
													<userinput moreinfo="none">suspend</userinput>
												</entry>
												<entry>Sets the Alligata Server&apos;s state to &apos;suspended&apos;.
</entry>
											</row>
											<row>
												<entry>
													<userinput moreinfo="none">isolate</userinput>
												</entry>
												<entry>Sets the Alligata Server&apos;s state to &apos;isolated&apos;.
</entry>
											</row>
											<row>
												<entry>
													<userinput moreinfo="none">resume</userinput>
												</entry>
												<entry>Sets the Alligata Server&apos;s state to &apos;running&apos;, if it has been suspended or isolated.
</entry>
											</row>
											<row>
												<entry>
													<userinput moreinfo="none">shutdown</userinput>
												</entry>
												<entry>Sets the Alligata Server&apos;s state to &apos;shutdown&apos;. The shutdown process, once begun, cannot be stopped - though the Alligata Server&apos;s <userinput moreinfo="none">status</userinput> can still be queried. If a second <userinput moreinfo="none">shutdown</userinput> command is sent, the Alligata Server will close down immediately, regardless of whether any packets are still held in queues.</entry>
											</row>
										</tbody>
									</tgroup>
								</table>
							</listitem>
						</itemizedlist>
</Para>
</FormalPara>

					</section>
					<section>
						<title>8.2.3 Monitoring the Alligata Server Using <userinput moreinfo="none">less</userinput>
						</title>
						<para>You can monitor the Alligata Server&apos;s activity by opening the log files using the UNIX less command (for example, <userinput moreinfo="none">less /var/log/alligata/bearerbox.log</userinput>). To watch a log file update while the Alligata Server is running, press SHIFT+F from within <userinput moreinfo="none">less</userinput>.
</para>
					</section>
				</section>
			</section>
			<section>
				<title>Shutting down an Alligata Server box</title>
				<para>There are two methods of shutting down an Alligata Server box.
</para>
				<para>To shut down an Alligata Server box:
</para>
				<section>
					<title>8.3.1 Method 1
</title>
<FormalPara>
<title>Linux users</title>
<Para>
					<itemizedlist>
						<listitem>
							<para>From the command line, type
</para>
							<para>
								<userinput moreinfo="none">
									/etc/rc.d/init.d/<replaceable>box</replaceable> stop
								</userinput>
							</para>
							<para>replacing <replaceable>box</replaceable> with the relevant box name, <userinput moreinfo="none">bearerbox</userinput>, <userinput moreinfo="none">wapbox</userinput> or <userinput moreinfo="none">smsbox</userinput>. For example:</para>
							<para>
								<userinput moreinfo="none">
									/etc/rc.d/init.d/wapbox stop

								</userinput>
							</para>
						</listitem>
					</itemizedlist>
</Para>
</FormalPara>
<FormalPara>
<title>Solaris users</title>
<Para>
					<itemizedlist>
						<listitem>
							<para>From the command line, type
</para>
							<para>
								<userinput moreinfo="none">
									/etc/init.d/<replaceable>box</replaceable> stop
								</userinput>
							</para>
							<para>replacing <replaceable>box</replaceable> with the relevant box name, <userinput moreinfo="none">bearerbox</userinput>, <userinput moreinfo="none">wapbox</userinput> or <userinput moreinfo="none">smsbox</userinput>. For example:</para>
							<para>
								<userinput moreinfo="none">
									/etc/rc.d/init.d/wapbox stop

								</userinput>
							</para>
						</listitem>
					</itemizedlist>
</Para>
</FormalPara>
				</section>
				<section>
					<title>8.3.2 Method 2
</title>
					<itemizedlist>
						<listitem>
							<para>Send the Alligata Server an HTTP <userinput moreinfo="none">shutdown</userinput> administration command (see Section 8.2.2).
</para>
						</listitem>
					</itemizedlist>
					<para>Note that this method can only be used to shut down the Bearer Box, not individual WAP and SMS Boxes.</para>
				</section>
			</section>
		</chapter>
		<chapter>
			<title>9  Configuring the Alligata Server</title>
			<para>The Alligata Server is installed with a default configuration that allows you to use it as a WAP gateway. If you want to customise its WAP features, or implement SMS messaging services, you need to make changes to the configuration file.
</para>
			<para>All the configuration data for the Alligata Server is held in a single file. By default this file is called <filename moreinfo="none">alligata.conf</filename> and is held in the directory <filename moreinfo="none">/etc</filename>. If you want to use a different configuration file, specify the path and file after the relevant command when you start up a box. (To do this, you must start the box using Method 3 - see Section 8.1.3.) For example:
</para>
			<para>
				<userinput moreinfo="none">
					bearerbox /etc/alligata2.conf
				</userinput>
			</para>
			<para>An example Alligata Server configuration file is shown in Figure 9.1.
</para>
			<para>Figure 9.1: Example Alligata Server configuration:</para>
			<programlisting format="linespecific"># Example Alligata Server configuration

group = core
user = alligata
max-threads = 99
admin-port = 13004
wapbox-port = 13002
smsbox-port = 13005
admin-password = bar
wdp-interface-name = *
log-file = /alligata/admin/bearer.log
log-level = 0
box-deny-ip = *.*.*.*
box-allow-ip = 127.0.0.1
admin-deny-ip = 10.0.0.2
admin-allow-ip = *.*.*.*
unified-prefix = 0044,0

group = wapbox
bearerbox-host = localhost
log-file = /alligata/admin/wapbox.log
log-level = 0

group = smsbox
bearerbox-host = localhost
sendsms-port = 13013
global-sender = 123
log-file = /alligata/admin/smsbox.log
log-level = 0

group = smsc
smsc = at
modemtype = wavecom
device = /dev/ttyS2

group = sms-service
keyword = proverb
aliases = Proverb;PROVERB;potd;Potd;POTD
url = http://www.awebsite.net/potd.html
prefix = &lt;!--beginprov--&gt;
suffix = &lt;!--endprov--&gt;
split-chars = ;:.
split-suffix = -cont-
header = &quot;Today&apos;s proverb -- &quot;
max-messages = 10

group = sms-service
keyword = ota
# In one line!
url =
http://localhost:13013/cgi-bin/sendota?
  username=otauser&amp;password=foo&amp;phonenumber=%p

group = otaconfig
location = http://www.asite.net
service = Company Home
ipaddress = 10.0.0.5
phonenumber = 44998123456
bearer = data
calltype = analogue
connection = cont
pppsecurity = off
authentication = normal
login = phoneuser
secret = barfoo

group = sendsms-user
username = otauser
password = foo
user-deny-ip = 10.0.0.2
user-allow-ip = *.*.*.*
max-messages = 2
concatenation = 1

group = sms-service
keyword = ota
# In one line!
url =
http://localhost:13013/cgi-bin/sendota?
  username=otauser&amp;password=foo&amp;phonenumber=%p

group = sms-service
keyword = default
text = Sorry, the Alligata Server didn&apos;t understand your message.

group = sendsms-user
username = tester
password = foobar
max-messages = 10
split-chars = .;,
split-suffix = -cont.-
header = &quot;Msg from tester -- &quot;
password = foo
user-deny-ip = 10.0.0.2
user-allow-ip = *.*.*.*
max-messages = 2
concatenation = 1</programlisting>
			<para>The configuration file is a list of variables used by the Alligata Server, divided into groups. Each group controls a different area of the Alligata Server&apos;s functionality. The configuration file is a plain text file, so you can edit it in any text editor.
</para>
			<para>When editing the configuration file, note the following points:
</para>
			<itemizedlist>
				<listitem>
					<para>Groups must be separated by one or more blank lines.
</para>
				</listitem>
				<listitem>
					<para>Each group must begin with the line </para>
					<para>
						<userinput moreinfo="none">
							group = <replaceable>identifier</replaceable>
						</userinput>
					</para>
					<para>where <replaceable>identifier</replaceable> is one of the group identifiers listed in Figure 9.2.
</para>
				</listitem>
				<listitem>
					<para>The format of each variable definition is
</para>
					<para>
						<userinput moreinfo="none">
							<replaceable>variable_name</replaceable> = <replaceable>value</replaceable>
						</userinput>
					</para>
					<para>Quotation marks around the value are optional. Therefore,
</para>
					<para>
						<userinput moreinfo="none">
							log-file = /tmp/bearer.log
						</userinput>
					</para>
					<para>is equivalent to</para>
					<para>
						<userinput moreinfo="none">
							log-file = &quot;/tmp/bearer.log&quot;
						</userinput>
					</para>
					<para>However, quotation marks are required if the value begins or ends with a space, or if it contains special characters.
</para>
					<para>Within quotation marks, standard C escape character syntax operates:
</para>
					<table>
						<title>Escape characters</title>
						<tgroup cols="2">
							<tbody>
								<row>
									<entry>\a</entry>
									<entry>Alert</entry>
								</row>
								<row>
									<entry>\b</entry>
									<entry>Backspace</entry>
								</row>
								<row>
									<entry>\f</entry>
									<entry>Form feed</entry>
								</row>
								<row>
									<entry>\n</entry>
									<entry>Newline</entry>
								</row>
								<row>
									<entry>\r</entry>
									<entry>Carriage return</entry>
								</row>
								<row>
									<entry>\t</entry>
									<entry>Horizontal tab</entry>
								</row>
								<row>
									<entry>\t</entry>
									<entry>Vertical tab</entry>
								</row>
								<row>
									<entry>\\</entry>
									<entry>Backslash</entry>
								</row>
								<row>
									<entry>\&apos;</entry>
									<entry>Single quotation mark</entry>
								</row>
								<row>
									<entry>\&quot;</entry>
									<entry>Double quotation mark</entry>
								</row>
								<row>
									<entry>\0oo</entry>
									<entry>Octal value (where o represents an octal digit)
</entry>
								</row>
								<row>
									<entry>\xhh</entry>
									<entry>Hexadecimal value (where h represents a hexadecimal digit)
</entry>
								</row>
							</tbody>
						</tgroup>
					</table>
				</listitem>
				<listitem>
					<para>Within a group, each variable definition must be followed by a <emphasis role="bold">single</emphasis> carriage return.
</para>
				</listitem>
				<listitem>
					<para>A hash # at the start of a line indicates a comment. The Alligata Server will ignore this line.
</para>
				</listitem>
				<listitem>
					<para>The Alligata Server reads the configuration file when it is started up. If you make changes to the configuration file while it is running, then you must restart the Alligata Server before they will be implemented.
</para>
				</listitem>
			</itemizedlist>
			<para>A summary of the characteristics of each configuration group is shown in Figure 9.2.
</para>
			<table>
				<title>Figure 9.2: Summary of Alligata Server configuration groups
</title>
				<tgroup cols="5">
					<thead>
						<row>
							<entry>Group</entry>
							<entry>Required?</entry>
							<entry>Multiple groups allowed?</entry>
							<entry>Identifier in configuration file (<userinput moreinfo="none">group = ...</userinput>)</entry>
							<entry>Function</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>Core</entry>
							<entry>Yes</entry>
							<entry>No</entry>
							<entry>
								<userinput moreinfo="none">core</userinput>
							</entry>
							<entry>Configures the Bearer Box.
</entry>
						</row>
						<row>
							<entry>WAP Box</entry>
							<entry>No</entry>
							<entry>No</entry>
							<entry>
								<userinput moreinfo="none">wapbox</userinput>
							</entry>
							<entry>Configures the WAP Box.
</entry>
						</row>
						<row>
							<entry>SMS Box</entry>
							<entry>No</entry>
							<entry>No</entry>
							<entry>
								<userinput moreinfo="none">smsbox</userinput>
							</entry>
							<entry>Configures the SMS Box.
</entry>
						</row>
						<row>
							<entry>SMSC </entry>
							<entry>No</entry>
							<entry>Yes</entry>
							<entry>
								<userinput moreinfo="none">smsc</userinput>
							</entry>
							<entry>Configures the connection to an SMSC.
</entry>
						</row>
						<row>
							<entry>SMS Service</entry>
							<entry>No</entry>
							<entry>Yes</entry>
							<entry>
								<userinput moreinfo="none">sms-service</userinput>
							</entry>
							<entry>Configures an SMS keyword service.
</entry>
						</row>
						<row>
							<entry>Send SMS User</entry>
							<entry>No</entry>
							<entry>Yes</entry>
							<entry>
								<userinput moreinfo="none">sendsms-user</userinput>
							</entry>
							<entry>Configures a user account for sending SMS messages from a PC workstation via HTTP.
</entry>
						</row>
						<row>
							<entry>OTA</entry>
							<entry>No</entry>
							<entry>No</entry>
							<entry>
								<userinput moreinfo="none">otaconfig</userinput>
							</entry>
							<entry>Provides settings for over-the-air (OTA) configuration of client devices.</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
			<para>The rest of this section consists of a full list of all the variables that can be used in the Alligata Server configuration file. Variables are arranged by group.
</para>
			<section>
				<title>9.1 Core Configuration Variables (Core group)
</title>
				<para>The Core group provides general configuration information for the Alligata Server. This information is used by the Bearer Box.
</para>
				<variablelist>
					<varlistentry>
						<term>
							<literal moreinfo="none">group = core 
</literal>
						</term>
						<listitem>
							<para>Group. Introduces the Core group. (Required.)
</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">user = <replaceable>user_name</replaceable>
							</literal>
						</term>
						<listitem>
							<para>The user name under which the Alligata Server is run. The Alligata Server automatically switches to this user name after it has started. (You must be logged in as <emphasis role="bold">root</emphasis> to start the Alligata Server manually. See Section 8 for instructions on starting the Alligata Server.)
</para>
							<para>Setting <literal moreinfo="none">user</literal> to <literal moreinfo="none">root</literal> is strongly discouraged, as it could compromise the security of the system.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									user = alligata
								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">admin-port = <replaceable>port_number</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Administration Port. Gives the port number on which the Bearer Box listens to HTTP administration commands. It can be any value between 1024 and 65535. (It may be under 1024 if you are running the Alligata Server as a <emphasis role="bold">root</emphasis> process, but it is not recommended that you do this.) It is not the same as the HTTP port of the local World Wide Web server. (Required.)
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									admin-port = 13004
								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">admin-password = <replaceable>password</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Administration Password. Defines the password for HTTP administration commands (except the status command, which does not require a password). See Section 8.2.2 for HTTP administration instructions. (Required.)
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									admin-password = PAPaya
								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">smsbox-port = <replaceable>port_number</replaceable>
							</literal>
						</term>
						<listitem>
							<para>SMS Box Port. Defines the port number to which SMS Boxes connect. It can be any value between 1024 and 65535. (It may be under 1024 if the <literal moreinfo="none">user</literal> variable is set to <literal moreinfo="none">root</literal>, but this is not advised.)
</para>
							<para>This variable is required if the Alligata Server is to handle SMS traffic.
Example:</para>
							<para>
								<literal moreinfo="none">
									smsbox-port = 13005
								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">wapbox-port = <replaceable>port_number</replaceable>
							</literal>
						</term>
						<listitem>
							<para>WAP Box Port. Defines the port number to which WAP Boxes connect. It can be any value between 1024 and 65535. (It may be under 1024 if the <literal moreinfo="none">user</literal> variable is set to <literal moreinfo="none">root</literal>, but this is not advised.)
</para>
							<para>This variable is required if the Alligata Server is to handle WAP traffic.
Example:</para>
							<para>
								<literal moreinfo="none">
									wapbox-port = 13002
								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">wdp-interface-name = <replaceable>IP_address</replaceable>
							</literal>
						</term>
						<listitem>
							<para>If the Alligata Server&apos;s host machine has multiple network cards, specifies the IP address of the card from which User Datagram Protocol (UDP) WAP packets are accepted. If set to <literal moreinfo="none">0.0.0.0</literal>, accepts packets from any IP address.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									wdp-interface-name = 10.0.0.3

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">log-file = <replaceable>file_name</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Log File. Specifies a file to which to output a log report of the Bearer Box&apos;s activity. If the specified file already exists, new output will be added to the end of the file.
</para>
							<para>If a log file is also defined in the command line when the Bearer Box is started up, then the log report will be output to both files (as well as to the standard output). See Section 8.1.3 for command line options.
</para>
							<para>If <literal moreinfo="none">log-file</literal> is not set in the configuration file, it defaults to <literal moreinfo="none">/var/log/alligata/bearerbox.log</literal>.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									log-file = /alliglog/bearer.log
								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">log-level = <replaceable>number_0-4</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Log Level. Sets the level of information to be recorded in the log file. Settings are as follows (with 0 providing the most detail and 4 the least):
</para>
							<simplelist type="vert">
								<member>0 Debug</member>
								<member>1 Information</member>
								<member>2 Warning
</member>
								<member>3 Error
</member>
								<member>4 Panic
</member>
							</simplelist>
							<para>If <literal moreinfo="none">log-level</literal> is not defined in the configuration file, it defaults to a value of 1.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									log-level = 0
								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">box-deny-ip = <replaceable>List_of_IP_addresses</replaceable>
							</literal>
						</term>
						<term>
							<literal moreinfo="none">box-allow-ip = <replaceable>List_of_IP_addresses</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Denied and allowed Box IP List. These variables list the IP addresses of WAP or SMS Boxes to which the Bearer Box may, or may not, forward packets. These variables allow you to prevent third parties from intercepting TCP packets as they leave the Bearer Box.
</para>
							<para>Addresses in the Denied and Allowed Box IP Lists are separated by semicolons. An asterisk * can be used as a wildcard in place of any single group of digits, so *.*.*.* matches any IP address.
</para>
							<para>Examples:</para>
							<para>
								<literal moreinfo="none">
									box-deny-ip = *.*.*.*
								</literal>
							</para>
							<para>
								<literal moreinfo="none">
									box-allow-ip = 10.0.0.6;10.0.0.7

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">admin-deny-ip = <replaceable>List_of_IP_addresses</replaceable>
							</literal>
						</term>
						<term>
							<literal moreinfo="none">admin-allow-ip = <replaceable>List_of_IP_addresses</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Administration Denied and Allowed IP Lists. These variables list IP addresses to be denied and allowed HTTP administration access to the Alligata Server. Addresses are formatted in the same way as in <literal moreinfo="none">box-deny-ip</literal> and <literal moreinfo="none">box-allow-ip</literal>.
</para>
							<para>Examples:</para>
							<para>
								<literal moreinfo="none">
									admin-deny-ip = *.*.*.*

								</literal>
							</para>
							<para>
								<literal moreinfo="none">
									admin-allow-ip = 10.0.0.6;10.0.0.7

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">unified-prefix = 
								<replaceable>List_of_telephone_code_prefixes</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Unified Prefix. Lists substitutions for telephone code prefixes in SMS messages. Substitutions are applied to the &apos;sender&apos; and &apos;recipient&apos; fields in incoming and outgoing SMS messages respectively, and ensure that all equivalent numbers are formatted consistently for SMSCs.
</para>
							<para>The format for each substitution is <replaceable>r,p1,p2...</replaceable> where <replaceable>r</replaceable> is the replacement prefix, and <replaceable>p1, p2</replaceable>, etc. are the prefixes to be replaced. 
</para>
							<para>You can define any number of substitutions in the configuration file by separating each definition with a semicolon ;.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									unified-prefix = 0044, 0; 00555, 05, 050

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">white-list = <replaceable>URL</replaceable>
							</literal>
						</term>
						<listitem>
							<para>White List. Links to a file listing telephone numbers of approved senders of SMS messages to the Alligata Server. SMS messages from numbers not in this list will be automatically discarded.
</para>
							<para>The white list file should contain telephone numbers separated by carriage returns.
</para>
							<para>
								<emphasis role="bold">Note:</emphasis> only the last nine digits are read, so it is theoretically possible for unauthorised senders with numbers nearly identical to those in the white list to gain access to the Alligata Server. The likelihood of this occurring is, however, minimal.</para>
							<para>If the configuration file contains a <literal moreinfo="none">white-list</literal>, it should not contain a 
<literal moreinfo="none">black-list</literal>.
</para>
							<para>
Example:</para>
							<para>
								<literal moreinfo="none">
									white-list = http://www.awebsite.net/alligata/white.htm

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">black-list = <replaceable>URL</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Black List. Links to a file listing telephone numbers of prohibited senders of SMS messages to the Alligata Server. SMS messages from numbers on this list are automatically discarded.
</para>
							<para>The black list file should contain telephone numbers separated by carriage returns.
</para>
							<para>As with the white list, only the last nine digits of the number are read by the Alligata Server.
</para>
							<para>If the configuration file contains a <literal moreinfo="none">black-list</literal>, it should not contain a <literal moreinfo="none">white-list</literal>.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									black-list = http://www.awebsite.net/alligata/black.htm

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">http-proxy-host = <replaceable>IP_address/URL</replaceable>
							</literal>
						</term>
						<listitem>
							<para>HTTP Proxy Host. Identifies a proxy server to be used for HTTP requests.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									http-proxy-host = 10.0.0.8
								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">http-proxy-port = <replaceable>port_number</replaceable>
							</literal>
						</term>
						<listitem>
							<para>HTTP Proxy Port. Identifies the port on the proxy server to which the Alligata Server connects.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									http-proxy-port = 13005

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">http-proxy-exceptions = <replaceable>list_of_IP_addresses/URLs</replaceable>
							</literal>
						</term>
						<listitem>
							<para>HTTP Proxy Exceptions. Lists Internet addresses to be reached directly rather than via the proxy server (for example, computers on a local network).
</para>
							<para>Multiple values should be separated by spaces.
Example:</para>
							<para>
								<literal moreinfo="none">
									http-proxy-exceptions = 10.0.0.3 10.0.0.4
								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">access-log = <replaceable>file_name</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Access Log File. Specifies a file to which to output a log report of SMS messages processed by the Bearer Box.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									access-log = bearerbox.access

								</literal>
							</para>
						</listitem>
					</varlistentry>
				</variablelist>
			</section>
			<section>
				<title>9.2 WAP Configuration Variables (WAP Box group)
</title>
				<para>The WAP Box group provides the configuration for the WAP Box or Boxes. There cannot be more than one WAP Box group in the main configuration file. If you have installed several WAP Boxes on different computers (see Section 6), each WAP Box should use a separate configuration file.
</para>
				<para>If you are using the Alligata Server for WAP services, remember also to set the wapbox-port variable in the Core group (see Section 9.1).
</para>
				<para>If you are not using the Alligata Server for WAP services, then no WAP Box group is necessary.
</para>
				<variablelist>
					<varlistentry>
						<term>
							<literal moreinfo="none">group = wapbox
							</literal>
						</term>
						<listitem>
							<para>Group. Introduces the Wap box group. (Required.)
</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">bearerbox-host = <replaceable>IP_address/URL</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Bearer Box Host. Identifies the computer hosting the Bearer Box. (Required.)
</para>
							<para>Examples:</para>
							<para>
								<literal moreinfo="none">
									bearerbox-host = localhost
								</literal>
							</para>
							<para>
								<literal moreinfo="none">
									bearerbox-host = 100.100.100.100  
								</literal>
							</para>
							<para>
								<literal moreinfo="none">
									bearerbox-host = acomputer.asite.net

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">log-file = <replaceable>file_name</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Log File. Specifies a file to which to output a log report of the WAP Box&apos;s activity. If the specified file already exists, new output is added to the end of it.
</para>
							<para>If a log file is also defined in the command line when the WAP Box is started up (see Section 8.1.3), then the log report will be output to both files.
</para>
							<para>If <literal moreinfo="none">log-file</literal> is not set in the configuration file, it defaults to <filename moreinfo="none">/var/log/alligata/wapbox.log</filename>.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									log-file = /alliglog/wap.log

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">log-level = <replaceable>number_0-4</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Log Level. Sets the level of information to be recorded in the log file. Settings are as follows (with 0 providing the most detail and 4 the least):
</para>
							<simplelist type="vert">
								<member>0  Debug
</member>
								<member>1  Information
</member>
								<member>2  Warning
</member>
								<member>3  Error
</member>
								<member>4  Panic
</member>
							</simplelist>
							<para>If <literal moreinfo="none">log-level</literal> is not defined in the configuration file, it defaults to a value of 1.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									log-level = 0

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">timer-freq = <replaceable>value_in_seconds</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Timer Frequency. If not set in the configuration file, defaults to a value of 1.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									timer-freq = 3

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">map-url = <replaceable>url#1 url#2
</replaceable>
							</literal>
						</term>
						<listitem>
							<para>URL Mapping. On incoming URL requests, replaces <replaceable>url#1</replaceable> with <replaceable>url#2</replaceable>. Asterisks can be used as wildcards to right-truncate either or both of the URLs.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									map-url = xlwa/* http://www.extremely_longwinded _wapsite_address.com/*

								</literal>
							</para>
							<para>This example enables a mobile device user to gain access to the URL <filename moreinfo="none">http://www.extremely_longwinded_wapsite_address.com/contacts.wml</filename> simply by keying <literal moreinfo="none">xlwa/contacts.wml</literal>.
</para>
							<para>
								<emphasis role="bold">Note:</emphasis> only one map-url is allowed in the configuration. If you need to map more than one URL, use <literal moreinfo="none">map-url-0</literal>, etc. together with <literal moreinfo="none">map-url-max</literal>.
</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">map-url-max = <replaceable>number</replaceable>
							</literal>
						</term>
						<listitem>
							<para>URL Mapping Maximum. Sets the maximum number of URL mappings to be defined in the configuration file.
</para>
							<para>If no maximum is specified, the Alligata Server allows a default maximum of ten mappings, numbered from 0 to 9 (see <literal moreinfo="none">map-url-0, map-url-1</literal>, etc.).
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									map-url-max = 8
								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">map-url-0 = <replaceable>url#1 url#2
</replaceable>
							</literal>
						</term>
						<term>
							<literal moreinfo="none">map-url-1 = <replaceable>url#1 url#2 , etc.
</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Multiple URL Mappings. Define multiple URL mappings, unlike <literal moreinfo="none">map-url</literal>, which can define only one mapping. Further URL mappings would be defined by the variables <literal moreinfo="none">map-url-2</literal>, <literal moreinfo="none">map-url-3</literal> and so on, up to the maximum specified in <literal moreinfo="none">map-url-max</literal>.
</para>
							<para>Formatting syntax is as for map-url.
</para>
							<para>Examples:</para>
							<para>
								<literal moreinfo="none">
									map-url-0 = xlwa/* http://www.extremely_longwinded_wapsite_address.com/*

								</literal>
							</para>
							<para>
								<literal moreinfo="none">
									map-url-1 = olwa/* http://www.outrageously_longwinded_wapsite_address.com/*

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">device-home = <replaceable>url</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Device Home. For Openwave&apos;s UP.Browser, defines the client&apos;s WML home deck. The actual URL supplied by the Openwave microbrowser is <filename moreinfo="none">DEVICE:home</filename>. Both parts of the variable definition are implicitly right-truncated.
</para>
							<para>Thus,
</para>
							<para>
								<literal moreinfo="none">
									device-home = http://www.devicehome.com/

								</literal>
							</para>
							<para>is equivalent to
</para>
							<para>
								<literal moreinfo="none">
									is equivalent to

								</literal>
							</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									device-home = http://www.devicehome.com/

								</literal>
							</para>
						</listitem>
					</varlistentry>
				</variablelist>
			</section>
			<section>
				<title>9.3 SMS Configuration Variables (SMS Box, SMSC, SMS Service and Send SMS User groups)
</title>
				<section>
					<title>9.3.1 SMS Box group
</title>
					<para>The SMS Box group provides the configuration for the SMS Box. There cannot be more than one SMS Box group in the main configuration file. If you have installed several SMS Boxes on different computers (see Section 6), each SMS Box should use a separate configuration file.
</para>
					<para>If you are using the Alligata Server for SMS messaging, remember also to set the <literal moreinfo="none">smsbox-port</literal> variable in the Core group (see Section 9.1).
</para>
					<para>If you are not using the Alligata Server for SMS messaging, then no SMS Box group is necessary.
</para>
					<variablelist>
						<varlistentry>
							<term>
								<literal moreinfo="none">group = smsbox
</literal>
							</term>
							<listitem>
								<para>Group. Introduces the SMS Box group. (Required.)
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">bearerbox-host = <replaceable>IP_address/URL</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Bearer Box Host. Identifies the computer hosting the Bearer Box. (Required.)
</para>
								<para>Examples:</para>
								<para>
									<literal moreinfo="none">
										bearerbox-host = localhost

									</literal>
								</para>
								<para>
									<literal moreinfo="none">
										bearerbox-host = 10.0.0.1


									</literal>
								</para>
								<para>
									<literal moreinfo="none">
										bearerbox-host = acomputer.asite.net

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">sendsms-port = <replaceable>port_number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Send SMS Port. Specifies the port via which SMS messages sent from a workstation by HTTP are received (see Section 9.3.4).
</para>
								<para>The port number can be any value between 1024 and 65535. (It may be under 1024 if the <literal moreinfo="none">user</literal> variable in the Core configuration group is set to root, but this is not advised.)
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										sendsms-port = 13001

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">
									<replaceable>telephone_number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Global Sender Number. Specifies the number shown as the sender&apos;s telephone number in outgoing SMS messages.
</para>
								<para>Note that most SMSCs will automatically replace this number with their own.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										global-sender = 44998123456
									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">log-file = <replaceable>file_name</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Log File. Specifies a file to which to output a log report of the SMS Box&apos;s activity. If the specified file already exists, new output will be added to the end of it.
</para>
								<para>If a log file is also defined in the command line when the SMS Box is started up, then the log report will be output to both files.
</para>
								<para>If <literal moreinfo="none">log-file</literal> is not set in the configuration file, it defaults to <filename moreinfo="none">/var/log/alligata/smsbox.log</filename>.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										log-file = /alliglog/sms.log

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">log-level = <replaceable>number_0-4</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Log Level. Sets the level of information to be recorded in the log file. Settings are as follows (with 0 providing the most detail and 4 the least):
</para>
								<simplelist type="vert">
									<member>0  Debug
</member>
									<member>1  Information
</member>
									<member>2  Warning
</member>
									<member>3  Error
</member>
									<member>4  Panic
</member>
								</simplelist>
								<para>If <literal moreinfo="none">log-level</literal> is not defined in the configuration file, it defaults to a value of 1.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										log-level = 0
									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">access-log = <replaceable>file_name</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Access Log File. Specifies a file to which to output a log report of SMS messages processed by the SMS Box.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										access-log = smsbox.access
									</literal>
								</para>
							</listitem>
						</varlistentry>
					</variablelist>
				</section>
				<section>
					<title>9.3.2 SMSC group
</title>
					<para>For each SMSC with which the Alligata Server is in communication, you must configure an SMSC group. If you intend to use the Alligata Server for managing SMS messages, remember also to set the <literal moreinfo="none">smsbox-port</literal> variable in the Core group (see Section 9.1).
</para>
					<para>Which variables you need to include in an SMSC group depends on the protocol used by the relevant SMSC. Figure 9.3 provides a list of which protocols support which variables. For full details of each protocol, please consult the documentation for the relevant SMSC.
</para>
					<para>AT is the protocol that the Alligata Server uses to send and receive SMS messages via a GSM wireless modem using AT commands. Using a GSM modem circumvents the need for a subscription to an SMSC. Certain mobile phones that incorporate a GSM modem can also be linked to a computer workstation and used to send and receive SMS messages in the same way as a modem.
</para>
					<para>Modems supported by the Alligata Server include the Wavecom WM02 and the Nokia Premicell. Phones that can be used as modems include the Nokia 7110.
</para>
					<para>If you do not want to use the Alligata Server&apos;s SMS features, you do not need any SMSC groups in your configuration file.
</para>
					<table>
						<title>Figure 9.3: SMSC group protocol-specific variables
</title>
						<tgroup cols="3">
							<thead>
								<row>
									<entry>SMSC protocol</entry>
									<entry>Value of <literal moreinfo="none">smsc</literal> variable</entry>
									<entry>Variables.
Those in parentheses are optional.</entry>
								</row>
							</thead>
							<tbody>
								<row>
									<entry>CIMD</entry>
									<entry>
										<literal moreinfo="none">cimd</literal>
									</entry>
									<entry>
										<literal moreinfo="none">host, port, smsc-username, smsc-password</literal>
									</entry>
								</row>
								<row>
									<entry>CIMD2</entry>
									<entry>
										<literal moreinfo="none">cimd2</literal>
									</entry>
									<entry>
										<literal moreinfo="none">host, port, smsc-username, smsc-password, (keepalive)</literal>
									</entry>
								</row>
								<row>
									<entry>EMI</entry>
									<entry>
										<literal moreinfo="none">emi</literal>
									</entry>
									<entry>
										<literal moreinfo="none">phone, device, smsc-username, smsc-password</literal>
									</entry>
								</row>
								<row>
									<entry>EMI IP</entry>
									<entry>
										<literal moreinfo="none">emi_ip</literal>
									</entry>
									<entry>
										<literal moreinfo="none">host, port, smsc-username, smsc-password,  connect-allow-ip, (receive-port), (our-port)</literal>
									</entry>
								</row>
								<row>
									<entry>SMPP IP</entry>
									<entry>
										<literal moreinfo="none">smpp</literal>
									</entry>
									<entry>
										<literal moreinfo="none">host, port, smsc-password, system-id, system-type, address-range, (receive-port)</literal>
									</entry>
								</row>
								<row>
									<entry>SEMA X.28</entry>
									<entry>
										<literal moreinfo="none">sema</literal>
									</entry>
									<entry>
										<literal moreinfo="none">device, smsc-nua, home-nua, (wait-report)</literal>
									</entry>
								</row>
								<row>
									<entry>OIS</entry>
									<entry>
										<literal moreinfo="none">ois</literal>
									</entry>
									<entry>
										<literal moreinfo="none">host, port, receive-port, (ois-debug-level)</literal>
									</entry>
								</row>
								<row>
									<entry>AT</entry>
									<entry>
										<literal moreinfo="none">at</literal>
									</entry>
									<entry>
										<literal moreinfo="none">device, modemtype, (pin)</literal>
									</entry>
								</row>
							</tbody>
						</tgroup>
					</table>
					<variablelist>
						<varlistentry>
							<term>
								<literal moreinfo="none">group = smsc
								</literal>
							</term>
							<listitem>
								<para>Group. Introduces the SMSC group. (Required.)
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">smsc = <replaceable>smsc_type</replaceable>
								</literal>
							</term>
							<listitem>
								<para>SMSC Type. Identifies the SMSC type. Currently available types are <literal moreinfo="none">cimd, cimd2, emi, emi_ip, smpp, sema, at</literal> and <literal moreinfo="none">ois</literal>. See Figure 9.3. (Required.)
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										smsc = emi

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">smsc-id = <replaceable>string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>SMSC Identifier. Provides a name by which the SMSC can be referred to elsewhere. This name can be used to associate the SMSC with particular SMS services and users, via the <literal moreinfo="none">accepted-smsc, forced-smsc</literal> and <literal moreinfo="none">default-smsc</literal> variables in the SMS Service and Send SMS User groups (see Sections 9.3.3 and 9.3.4).
</para>
								<para>The value of <literal moreinfo="none">smsc-id</literal> may contain any alphanumeric characters, and is case-insensitive.
Example:</para>
								<para>
									<literal moreinfo="none">
										smsc-id = smsc1

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">denied-prefix = <replaceable>list_of_telephone_code_prefixes</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Denied Telephone Prefix List. Lists prefixes of telephone numbers to which messages are not to be sent via this SMSC.
</para>
								<para>Numbers in the list are separated by semicolons ;.
</para>
								<para>The <literal moreinfo="none">denied-prefix</literal> variable may be needed because some SMSCs do not allow messages to be sent to users on different telephone networks to their own. <literal moreinfo="none">denied-prefix</literal> and <literal moreinfo="none">preferred-prefix</literal> can also be useful to direct calls to the cheapest SMSC according to their destination code.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										denied-prefix = 0898;0999

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">preferred-prefix = <replaceable>list_of_telephone_code_prefixes</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Preferred Telephone Prefix List. Lists prefixes of telephone numbers that should, if possible, be sent messages via this SMSC.
</para>
								<para>Numbers in the list are separated by semicolons ;.
</para>
								<para>It is possible for a telephone code prefix to be listed as preferred in more than one SMSC group. Where this is the case, the Alligata Server chooses one of these SMSC groups at random.
</para>
								<para>Where a telephone number&apos;s prefix is not listed as preferred in any SMSC group, the Alligata Server chooses a group at random from all available SMSC groups.
Example:</para>
								<para>
									<literal moreinfo="none">
										preferred-prefix = 01487;01223

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">host = <replaceable>IP_address/host_name</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Examples:</para>
								<para>
									<literal moreinfo="none">
										host = 10.0.0.20
									</literal>
								</para>
								<para>
									<literal moreinfo="none">
										host = acomputer.acompany.net

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">port = <replaceable>port_number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>SMSC Host Port. Identifies the port number on the SMSC host machine used for communication. (Required.)
</para>
<para>Example:</para>
								<para><literal moreinfo="none">port = 13004</literal>
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">our-port = <replaceable>port_number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Local Port. Identifies the port on the Alligata Server&apos;s host machine used for communication with the SMSC. Currently only the EMI IP protocol supports this.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										our-port = 13005

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">receive-port = <replaceable>port_number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Receive Port. Used with protocols that accept different send and receive ports, namely EMI IP, SMPP IP and OIS.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										receive-port = 13006

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">smsc-username = <replaceable>user_name</replaceable>
								</literal>
							</term>
							<listitem>
								<para>SMSC User Name. The Alligata Server&apos;s account user name on the SMSC&apos;s host machine.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										smsc-username = ally

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">smsc-password = <replaceable>password</replaceable>
								</literal>
							</term>
							<listitem>
								<para>SMSC Password. The Alligata Server&apos;s account password on the SMSC&apos;s host machine.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										smsc-password = PINEapple

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">device = <replaceable>device_name</replaceable>
								</literal>
							</term>
							<listitem>
								<para>System Device. When the Alligata Server is used with a GSM modem or the EMI or X.28 protocols, this identifies the device associated with the modem.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										device = /dev/ttyS0

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">connect-allow-ip = <replaceable>list_of_IP_addresses</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Allowed IP Connections. Specifies IP addresses of SMSCs to be allowed to connect to the Alligata Server. Used by EMI IP.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										connect-allow-ip = 10.0.0.20 10.0.0.21

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">smsc_nua = <replaceable>X.121_address</replaceable>
								</literal>
							</term>
							<listitem>
								<para>SMSC address using X.121 protocol. Used by SEMA X.28.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										smsc_nua = 000001220900

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">home_nua = <replaceable>X.121_address</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Radio PAD (Product Assembler/Disassembler) address using X.121 protocol. Used by SEMA X.28.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										home_nua = 000001220900

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">wait_report = <replaceable>digit_(0_or_1)</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Wait Report. Used by SEMA X.28.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										wait_report = 1

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">phone = <replaceable>telephone_number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>The SMSC&apos;s telephone number. Used only by EMI.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										phone = 44999123456

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">keepalive = <replaceable>number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>The frequency of &apos;alive&apos; messages in seconds. Used only by CIMD2.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">system_id = <replaceable>string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>System ID. Used only by SMPP IP.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">system_type = <replaceable>string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>System Type. Used only by SMPP IP.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">address_range = <replaceable>range</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Address range. Used only by SMPP IP.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">modemtype = <replaceable>string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>The type of modem being used to send SMS messages by the AT protocol. Modems currently supported are as follows:
</para>
								<table>
									<title>Currently supported modems</title>
									<tgroup cols="2">
										<thead>
											<row>
												<entry>Modem</entry>
												<entry>
													<literal moreinfo="none">modemtype</literal> value
</entry>
											</row>
										</thead>
										<tbody>
											<row>
												<entry>Wavecom WM02 </entry>
												<entry>
													<literal moreinfo="none">wavecom</literal>
												</entry>
											</row>
											<row>
												<entry>Nokia Premicell</entry>
												<entry>
													<literal moreinfo="none">premicell</literal>
												</entry>
											</row>
											<row>
												<entry>Siemens M20T</entry>
												<entry>
													<literal moreinfo="none">siemens</literal>
												</entry>
											</row>
        <row>

                <entry>Siemens TC35</entry>

                <entry>

                        <literal moreinfo="none">siemens-tc35</literal>

                </entry>

        </row>

											<row>
												<entry>Phone with GSM modem</entry>
												<entry>
													<literal moreinfo="none">nokiaphone</literal>
												</entry>
											</row>
										</tbody>
									</tgroup>
								</table>
								<para>(The Nokia Premicell does not support user data headers (UDHs), so cannot be used for over-the-air configuration messages.)
</para>
								<para>Used only by AT.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										modemtype = wavecom

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">pin = <replaceable>number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Personal Identification Number. An optional variable used only by AT. Use this variable if the SIM card inserted in your GSM modem requires a PIN for activation.
</para>
							</listitem>
						</varlistentry>
					</variablelist>
				</section>
				<section>
					<title>9.3.3 SMS Service Group
</title>
					<para>An SMS Service group defines an action to be performed by the SMS Box in response to a keyword and parameters in incoming SMS messages.
</para>
					<para>If you are using the Alligata Server for SMS messaging, remember to include an SMS Box group and at least one SMSC group in the configuration. You also need to set the <literal moreinfo="none">smsbox-port</literal> variable in the Core group (see Section 9.1).
</para>
					<para>You can include as many SMS Service groups in the configuration as you like. Each group defines a single SMS service.
</para>
					<para>For instructions on how to implement SMS services, see Section 13.
</para>
					<variablelist>
						<varlistentry>
							<term>
								<literal moreinfo="none">group = sms-service
</literal>
							</term>
							<listitem>
								<para>Group. Introduces the SMS Service group. (Required.)
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">keyword = <replaceable>word</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Service Keyword. Defines the keyword that triggers the service. (Required.)
</para>
								<para>The keyword can only be a single word, without spaces, and must always be the first word in incoming messages.
</para>
								<para>
									<literal moreinfo="none">keyword</literal> is case-sensitive. For example, <literal moreinfo="none">frog, Frog</literal> and <literal moreinfo="none">FROG</literal> are treated as different keywords.
</para>
								<para>If <literal moreinfo="none">keyword</literal> has the value <literal moreinfo="none">default</literal>, then the SMS Service will be applied to all incoming messages that do not contain recognised keywords.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										keyword = football

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">aliases = <replaceable>word#1;word#2, etc.
</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Service Keyword Aliases. Defines alternative keywords that will trigger the service. Multiple aliases must be separated by semicolons ;. Each alias must be a single keyword, containing no spaces.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										aliases = Football;FOOTBALL

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">url = <replaceable>url</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Retrieval URL. Specifies a URL from which to fetch data.
</para>
								<para>The URL can include parameters that are extracted from the incoming SMS message. These parameters are expanded by the SMS Box before the request is sent to the World Wide Web.
</para>
								<para>Possible parameters are as follows:</para>
								<table>
									<title>Possible parameters in the URL template</title>
									<tgroup cols="2">
										<tbody>
											<row>
												<entry>
													<literal moreinfo="none">%s</literal>
												</entry>
												<entry>The next word from the incoming SMS message, starting with the second word (since the first word is the keyword). Characters that can be ambiguous in URLs are converted into hexadecimal ASCII codes, for example + is converted into %2B.

After each %s, the URL parser moves on to the next word in the message. </entry>
											</row>
											<row>
												<entry>
													<literal moreinfo="none">%S</literal>
												</entry>
												<entry>As <literal moreinfo="none">%s</literal>, but * is converted to ~ (tilde). This can be useful for users whose mobile phones do not allow ~ to be entered. In addition, potentially ambiguous characters are not encoded.
</entry>
											</row>
											<row>
												<entry>
													<literal moreinfo="none">%r</literal>
												</entry>
												<entry>All the remaining words in the message. For example, if the message is &apos;foo bar foobar baz&apos;, and <literal moreinfo="none">bar</literal> has already been parsed by a <literal moreinfo="none">%s</literal>, then <literal moreinfo="none">%r</literal> denotes <literal moreinfo="none">foobar baz</literal> (<literal moreinfo="none">foo</literal>, of course, being the keyword).
</entry>
											</row>
											<row>
												<entry>
													<literal moreinfo="none">%a</literal>
												</entry>
												<entry>All words in the incoming SMS message, including the first word.
</entry>
											</row>
											<row>
												<entry>
													<literal moreinfo="none">%t</literal>
												</entry>
												<entry>The time the message was sent, formatted as <replaceable>YYYY-MM-DD[space]HH:MM</replaceable>, for example <literal moreinfo="none">2000-07-28 15:56</literal>.
</entry>
											</row>
											<row>
												<entry>
													<literal moreinfo="none">%p</literal>
												</entry>
												<entry>The telephone number of the recipient of the SMS message.
</entry>
											</row>
											<row>
												<entry>
													<literal moreinfo="none">%P</literal>
												</entry>
												<entry>The telephone number of the sender of the SMS message.
</entry>
											</row>
											<row>
												<entry>
													<literal moreinfo="none">%q</literal>
												</entry>
												<entry>As <literal moreinfo="none">%p</literal>, except that a leading 00 is replaced with +.
</entry>
											</row>
											<row>
												<entry>
													<literal moreinfo="none">%Q</literal>
												</entry>
												<entry>As <literal moreinfo="none">%P</literal>, except that a leading 00 is replaced with +.</entry>
											</row>
										</tbody>
									</tgroup>
								</table>
								<para>These parameters can also be used with the <literal moreinfo="none">file</literal> and <literal moreinfo="none">text</literal> variables. See Section 13.1 for examples of how parameters can be used.
</para>
								<para>If an SMS Service group contains a <literal moreinfo="none">url</literal> variable, it cannot also contain a <literal moreinfo="none">file</literal> or a <literal moreinfo="none">text</literal> (see below). There can only be one <literal moreinfo="none">url</literal> in an SMS Service group.
</para>
								<para>
									<literal moreinfo="none">url</literal> can be used in conjunction with prefix and suffix to retrieve a section of a Web page.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										url = http://www.awebsite.net/cgi/salary?user=%s&amp;password=%s&amp;employee=%r

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">file = <replaceable>file_name</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Retrieval File. Specifies a file on a local disk from which to fetch data.
</para>
								<para>The whole of the file is retrieved, except for the last character (usually a line feed).
</para>
								<para>If an SMS Service group contains a <literal moreinfo="none">file</literal>, it cannot also contain a <literal moreinfo="none">url</literal> or a <literal moreinfo="none">text</literal>. There can only be one <literal moreinfo="none">file</literal> in an SMS Service group.
</para>
								<para>
									<literal moreinfo="none">file</literal> supports all the parameters listed under <literal moreinfo="none">url</literal>.
</para>
								<para>Examples:</para>
								<para>
									<literal moreinfo="none">
										file = /replies/areply.txt
									</literal>
								</para>
								<para>
									<literal moreinfo="none">
										file = /info/%s

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">text = <replaceable>character_string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Reply Text. Specifies a static text message to be sent to the client.
</para>
								<para>If an SMS Service group contains a <literal moreinfo="none">text</literal>, it cannot also contain a <literal moreinfo="none">url</literal> or a <literal moreinfo="none">file</literal>. There can only be one <literal moreinfo="none">text</literal> in an SMS Service group.
</para>
								<para>
									<literal moreinfo="none">text</literal> supports all the parameters listed under <literal moreinfo="none">url</literal>.
</para>
								<para>Examples:</para>
								<para>
									<literal moreinfo="none">
										text = All is well over here.

									</literal>
								</para>
								<para>
									<literal moreinfo="none">
										text = You wrote: %r.

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">prefix = <replaceable>character_string</replaceable>
								</literal>
							</term>
							<term>
								<literal moreinfo="none">suffix = <replaceable>character_string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Retrieval Prefix and Suffix. Used in conjunction with <literal moreinfo="none">url</literal>. The Alligata Server retrieves all text between (but not including) the prefix and the suffix in the target Web page. Tags are stripped out.
</para>
								<para>If the target page contains more than one occurrence of the prefix or suffix, then the Alligata Server retrieves everything between the first occurrence of the prefix and the first succeeding occurrence of the suffix.

</para>
								<para>Examples:</para>
								<para>
									<literal moreinfo="none">
										prefix = &lt;!--begin today&apos;s weather--&gt;

									</literal>
								</para>
								<para>
									<literal moreinfo="none">
										&lt;!--end today&apos;s weather--&gt;

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">faked-sender = <replaceable>telephone_number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Faked Sender Number. Specifies the number shown as the sender&apos;s telephone number in outgoing SMS messages for this service.
</para>
								<para>
									<literal moreinfo="none">faked-sender</literal> will override any sender numbers specified elsewhere (for example, the <literal moreinfo="none">global-sender</literal> variable in an SMS Box group).
</para>
								<para>Note that most SMSCs will replace the faked-sender number with their own.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										faked-sender = 44998123456

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">max-messages = <replaceable>number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Maximum Reply Messages. Specifies the maximum number of individual SMS messages allowed in a single reply.
</para>
								<para>If <literal moreinfo="none">max-messages</literal> is not set in the configuration file, it defaults to a value of 1.
</para>
								<para>If <literal moreinfo="none">max-messages</literal> is set to 0, then no replies will be sent, other than error messages.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										max-messages = 8

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">split-chars = <replaceable>list_of_characters</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Message Split Characters. Specifies characters that can be used to split a long outgoing message into several shorter ones.
</para>
								<para>The maximum length of a single SMS message will vary depending on whether it uses a 7-bit or an 8-bit format, and whether it has a user data header (UDH). A 7-bit message usually has a maximum length of 160 characters, an 8-bit message a maximum length of 140 characters. 
</para>
								<para>Messages over the maximum length for a single message are split as specified in the configuration file. Where <literal moreinfo="none">split-chars</literal> is not specified, the Alligata Server uses any character to split the message.
</para>
								<para>The Alligata Server only splits messages where necessary. For example, if the semicolon ; is specified as a split character, then a message of 200 characters containing six semicolons will be split into just two shorter messages, not seven.
</para>
								<para>
Example:</para>
								<para>
									<literal moreinfo="none">
										split-chars = ;:.

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">split-suffix = <replaceable>character_string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Message Split Suffix. Where a long message is split into two or more shorter ones, specifies a string to appear at the end of each message (except the last).
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										split-suffix = -cont.-

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">omit-empty = <replaceable>a numeric value</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Omit Empty Messages. If set to a number other than 0, stops messages containing no data being sent to the user.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										omit-empty = 1

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">header = <replaceable>character_string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Reply Header. Specifies a string to appear at the beginning of outgoing messages. In the case of split messages, the string appears on every message.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										header = Today&apos;s weather...

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">footer = <replaceable>character_string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Reply Footer. Specifies a string to appear at the end of outgoing messages. In the case of split messages, the string appears on every message.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										footer = -- sent by the Alligata Server --

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">accepted-smsc = <replaceable>list_of_smsc_identifiers</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Accepted SMSC identifiers. Only messages from SMSCs with these identifiers (see <literal moreinfo="none">smsc-id</literal> in Section 9.3.2) are allowed to use this service.
</para>
								<para>Multiple values should be separated by semicolons ;.

</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										accepted-smsc = smsc1;smsc2

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">concatenation = <replaceable>0_or_1</replaceable>
								</literal>
							</term>
							<listitem>
								<para>If set to 1, allows concatenation of multiple SMS messages in the client device.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										concatenation = 1 

									</literal>
								</para>
							</listitem>
						</varlistentry>
					</variablelist>
				</section>
				<section>
					<title>9.3.4 Send SMS User Group
</title>
					<para>The Alligata Server allows you to send SMS messages from a computer workstation using HTTP (see Section 13.2). To do this, you must configure at least one Send SMS user account. Each user account is defined in a separate Send SMS User group.
</para>
					<variablelist>
						<varlistentry>
							<term>
								<literal moreinfo="none">group = sendsms-user
</literal>
							</term>
							<listitem>
								<para>Group. Introduces the Send SMS User group. (Required.)
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">username = <replaceable>string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Send SMS User Name. Specifies the account user name. (Required.)
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										username = colin

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">password = <replaceable>string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Send SMS Password. Specifies the account password. (Required.)
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										password = AVOcado

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">user-deny-ip = <replaceable>List_of_IP_addresses</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Denied IP Addresses. Lists IP addresses from which SMS messages may not be sent using HTTP. Addresses in the list are separated by semicolons. An asterisk * can be used as a wildcard in place of any single group of digits. For example, *.*.*.* matches any IP address.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										user-deny-ip = 0.0.0.0;10.0.0.6

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">user-allow-ip = <replaceable>List_of_IP_addresses</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Allowed IP Addresses. Lists IP addresses from which SMS messages may be sent using HTTP. 
</para>
								<para>Addresses are formatted in the same way as in <literal moreinfo="none">user-deny-ip</literal>.
</para>
								<para>user-allow-ip = 0.0.0.0;10.0.0.7</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">faked-sender = <replaceable>telephone_number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Faked Sender Number. Specifies the telephone number shown as the sender&apos;s on client devices.
</para>
								<para>Note that most SMSCs will replace this number with their own.
</para>
								<para>
									<literal moreinfo="none">faked-sender</literal> will override any sender numbers specified elsewhere (for example, the <literal moreinfo="none">global-sender</literal> variable in the SMS Box group).
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										faked-sender = 44998123456

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">max-messages = <replaceable>number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Maximum Messages. Specifies the maximum number of individual SMS messages into which a long message can be split.
</para>
								<para>If <literal moreinfo="none">max-messages</literal> is not set in the configuration file, it defaults to a value of 1.
</para>
								<para>If <literal moreinfo="none">max-messages</literal> is set to 0, then no messages will be sent.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										max-messages = 8

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">split-chars = <replaceable>list_of_characters</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Message Split Characters. Specifies characters that can be used to split a long message into several shorter ones.
</para>
								<para>The maximum length of a message is usually 140 or 160 characters, depending on the SMSC&apos;s protocol. Messages over this length are split as specified in <literal moreinfo="none">max-messages</literal> and <literal moreinfo="none">split-chars</literal>. If <literal moreinfo="none">split-chars</literal> is not set, any character is used to split the message.
</para>
								<para>The Alligata Server will only split messages where necessary. For example, if the semicolon ; is specified as a split character, then a message of 200 characters containing six semicolons will be split into just two shorter messages, not seven.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										split-chars = .,&apos;:

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">split-suffix = <replaceable>character_string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Message Split Suffix. Where a long message is split into two or more shorter ones, specifies a string to appear at the end of each message (except the last).
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										split-suffix = -cont.-

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">omit-empty = <replaceable>number</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Omit Empty Messages. If set to a number other than 0, stops messages containing no data being sent to the user.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										omit-empty = 1

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">header = <replaceable>character_string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>message Header. Specifies a string to appear at the beginning of outgoing messages. In the case of split messages, the string appears on every message.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										header = Message from your manager

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">footer = <replaceable>character_string</replaceable>
								</literal>
							</term>
							<listitem>
								<para>message Footer. Specifies a string to appear at the end of outgoing messages. In the case of split messages, the string appears on every message.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										footer = -- Sent by Alligata Server --

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">forced-smsc = <replaceable>smsc_identifier</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Forced SMSC Identifier. Forces SMS messages to be sent via the specified SMSC. See <literal moreinfo="none">smsc-id</literal> in Section 9.3.2.
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										forced-smsc = smsc1;smsc2
									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">default-smsc = <replaceable>smsc_identifier</replaceable>
								</literal>
							</term>
							<listitem>
								<para>Default SMSC Identifier. Specifies an SMSC via which messages are to be sent, unless an alternative SMSC is specified in the smsc parameter in the message itself (see Section 13.2.2).
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										default-smsc = smsc1

									</literal>
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<literal moreinfo="none">concatenation = <replaceable>0_or_1</replaceable>
								</literal>
							</term>
							<listitem>
								<para>If set to 1, allows concatenation of multiple SMS messages in the client device. 
</para>
								<para>Example:</para>
								<para>
									<literal moreinfo="none">
										concatenation = 1 


									</literal>
								</para>
							</listitem>
						</varlistentry>
					</variablelist>
				</section>
			</section>
			<section>
				<title>9.4 Over-the-air Configuration Variables (OTA Configuration Group)
</title>
				<para>The OTA Configuration group sets the variables for over-the-air configuration of WAP client devices.
</para>
				<para>There are two ways of configuring a client device: from a workstation using an HTTP request, or from the client device via an SMS Service group. See Section 13.3 for instructions on how to configure a client device.
</para>
				<variablelist>
					<varlistentry>
						<term>
							<literal moreinfo="none">group = otaconfig
</literal>
						</term>
						<listitem>
							<para>Group. Introduces the OTA Configuration group. (Required.)
</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">location = 
<replaceable>url</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Home URL. The home URL of the client device. (Required.)
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									location = http://www.awapsite.net/


								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">service = <replaceable>string</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Title of the service as it will appear on client devices. (Required.)
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									service = Acme WAP Service


								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">ipaddress = <replaceable>IP_address</replaceable>
							</literal>
						</term>
						<listitem>
							<para>IP address of the Alligata Server&apos;s Bearer Box.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									ipaddress = 10.0.0.1


								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">phonenumber = <replaceable>telephone_number</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Telephone number via which the client device establishes the point-to-point Protocol (PPP) connection with the Alligata Server.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									phonenumber = 44998123456

								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">bearer = <replaceable>string</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Bearer type, either <literal moreinfo="none">data</literal> or <literal moreinfo="none">sms</literal>. 
</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">calltype = <replaceable>string</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Call type, either <literal moreinfo="none">isdn</literal> or <literal moreinfo="none">analogue</literal>.
</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">connection = <replaceable>string</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Connection type, either <literal moreinfo="none">cont</literal> (continuous) or <literal moreinfo="none">temp</literal> (temporary). Defaults to <literal moreinfo="none">cont</literal>.
</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">pppsecurity = <replaceable>on</replaceable> or <replaceable>off</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Enables CHAP authentication if set to <literal moreinfo="none">on</literal>. Otherwise enables PAP authentication.
</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">authentication = <replaceable>string</replaceable>
							</literal>
						</term>
						<listitem>
							<para>Authentication mode, either normal or secure. secure enables WTLS security. Defaults to normal.
</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">login = <replaceable>user_name</replaceable>
							</literal>
						</term>
						<listitem>
							<para>User login name.</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									login = colin


								</literal>
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>
							<literal moreinfo="none">secret = <replaceable>password</replaceable>
							</literal>
						</term>
						<listitem>
							<para>User password.
</para>
							<para>Example:</para>
							<para>
								<literal moreinfo="none">
									password = KUMquat

								</literal>
							</para>
						</listitem>
					</varlistentry>
				</variablelist>
			</section>
		</chapter>
		<chapter>
			<title>10  Creating WAP Documents</title>
			<para>The Alligata Server allows you to offer users of mobile WAP devices an access point to the Mobile Internet. You do not need to provide any WAP content of your own. However, you will probably want to set up your own WAP services - either static WML decks, or Common Gateway Interface (CGI) applications that retrieve data and format it automatically as WML.
</para>
			<para>In order to disseminate information on the Mobile Internet, all you need is space on the Internet from which a standard HTTP server such as Apache can retrieve data. In other words, serving WAP data is almost exactly the same as serving Web data. The only difference from the point of view of the content provider is that the data sent to the client must be in WML rather than HTML format. To all intents and purposes, WAP files are Web files, but in a different format to that understood by PC Web browsers.
</para>
			<para>When the HTTP server to which your Internet space is connected receives a request for WAP data, it finds the relevant file and sends it - or, if it is a CGI application, its WML output - to the IP address that requested it. It sends it using HTTP, like a Web file. The IP address to which it sends it is that of a WAP gateway (for example, an installation of the Alligata Server). The gateway compresses the data and sends it over the wireless network to the client mobile device that sent the original WAP request. See Section 3 for more information about what the WAP gateway does.</para>
		</chapter>
		<chapter>
			<title>11  Introduction to WML</title>
			<para>This section gives a summary of Wireless Markup Language (WML). WML is the formatting language used to encode WAP documents. Full details of WML can be found in the official WML specification on the WAP Forum&apos;s Web site at <filename moreinfo="none">http://www.wapforum.org</filename>. here we aim to provide you with enough information to get started with WML and create some basic WML documents of your own. The Alligata Server package includes some example WML files, so that you can see how WML works in practice.
</para>
			<para>WML is derived from Hypertext Markup Language (HTML), the tagging system used to format World Wide Web pages; if you are familiar with HTML, you should find WML fairly easy to learn. However, WML is tailored to display information on much smaller display areas than HTML, and to be compact enough to transmit efficiently, in compressed form, over low-bandwidth, high-latency wireless networks.
</para>
			<para>Writing WML is straightforward: you can use either a text editor, or one of the increasing number of dedicated WML editors available on the market. To check the formatting of your WML, we recommend you get a WAP phone, or download one of several free WAP phone emulators from the World Wide Web. 
</para>
			<para>The rest of this section covers the main features of WML.
</para>
			<section>
				<title>11.1 Content and Tags
</title>
				<para>To begin with, here is some sample WML: the file <filename moreinfo="none">logo.wml</filename> from the example site &apos;Static Simple&apos; on the Alligata Server installation CD. If you installed the example WAP sites along with the Alligata Server, you can view this file by selecting &apos;Static Simple&apos; from the &apos;Site Examples&apos; menu (a full guide to the example sites is provided in Section 12):
</para>
				<programlisting format="linespecific">&lt;?xml version=&quot;1.0&quot;?&gt;
 &lt;!DOCTYPE wml PUBLIC &quot;-//WAPFORUM//DTD WML 1.1//EN&quot;   
     &quot;http://www.wapforum.org/DTD/wml_1.1.xml&quot;&gt;
 &lt;wml&gt;
    &lt;card id=&quot;foo&quot; name=&quot;bar&quot; title=&quot;Static WML&quot;
		    newcontext=&quot;true&quot;&gt;
      &lt;p&gt;
      &lt;img src=&quot;3glab.wbmp&quot; alt=&quot;3G Lab Logo&quot;  align=&quot;middle&quot;/&gt;
      &lt;br/&gt;
      This is static &lt;big&gt;WML&lt;/big&gt; text.
   &lt;/p&gt;
  &lt;/card&gt;
 &lt;/wml&gt;</programlisting>
				<para>This file, like all WML documents, holds two main types of information: <emphasis role="bold">content</emphasis> and <emphasis role="bold">tags</emphasis>.
</para>
				<para>
					<emphasis role="bold">Content</emphasis> is generally textual information to be displayed on the client&apos;s microbrowser. It is encoded as plain text using the Unicode 2.0 character set. The example file&apos;s content is the sentence &apos;This is static WML text&apos;.
</para>
				<para>Some characters are not included in the Unicode character set, or are problematic to display because they are used by WML for purposes other than text display (for example the less than &lt; and greater than &gt; symbols, which denote the start and end of tags). Such characters are represented by entity references which begin with an ampersand &amp;, and end with a semicolon ;. Some of the most common entity references in WML are:
</para>
				<informaltable>
					<tgroup cols="2">
						<tbody>
							<row>
								<entry>
									<userinput moreinfo="none">&amp;lt;</userinput>
								</entry>
								<entry>less than &lt;</entry>
							</row>
							<row>
								<entry>
									<userinput moreinfo="none">&amp;gt;</userinput>
								</entry>
								<entry>greater than &gt;
</entry>
							</row>
							<row>
								<entry>
									<userinput moreinfo="none">&amp;apos;</userinput>
								</entry>
								<entry>apostrophe &apos;
</entry>
							</row>
							<row>
								<entry>
									<userinput moreinfo="none">&amp;quot;</userinput>
								</entry>
								<entry>quotation mark &quot;
</entry>
							</row>
							<row>
								<entry>
									<userinput moreinfo="none">&amp;nbsp;</userinput>
								</entry>
								<entry>non-breaking space
</entry>
							</row>
						</tbody>
					</tgroup>
				</informaltable>
				<para>
					<emphasis role="bold">Tags</emphasis> are the pieces of information held within angled brackets &lt; &gt;. Tags can do one of several things: they can describe to the microbrowser how to format content; tell it to display non-textual items where they occur; or describe an action for the microbrowser to perform in certain circumstances. Tags are not visible to the user of the client device.
</para>
				<para>Many tags occur in pairs, with a start tag immediately before the section of the file they relate to, and a corresponding end tag after it. An end tag always has a forward slash / immediately after the opening angled bracket.
</para>
				<para>In the example file, you can see that the letters &apos;WML&apos; have a <literal moreinfo="none">&lt;big&gt;</literal> tag before them, and a <literal moreinfo="none">&lt;/big&gt;</literal> tag after them. These tags tell the microbrowser to display the content between them in large text. So on your microbrowser, the sentence will look like this:
</para>
				<screen format="linespecific">This is static WML text.
</screen>
				<para>A tag that does not have a closing tag is called an empty tag - empty because it has no content or other tags inside it. An example is the tag <literal moreinfo="none">&lt;img alt=&quot;3G Lab Logo&quot; src=&quot;3glab.wbmp&quot; align=&quot;middle&quot;/&gt;</literal>. This tag tells the browser to display the image file <filename moreinfo="none">3glab.wbmp</filename> where it occurs. Note that an empty tag must end with a forward slash, so that the browser knows not to look for a companion end tag. In this respect WML differs from HTML, so if you are used to writing HTML, remember to include these slashes.
</para>
			</section>
			<section>
				<title>11.2 Elements and Attributes
</title>
				<para>WML tags, like HTML tags, contain information about elements and attributes.
</para>
				<para>An <emphasis role="bold">element</emphasis> is a structural unit of a WML document: every tag begins with an element indicator. In the example file (see Section 11.1), <literal moreinfo="none">wml, card, p, img</literal> and <literal moreinfo="none">big</literal> are all elements.
</para>
				<para>An <emphasis role="bold">attribute</emphasis> provides information about a specific occurrence of an element. Attributes are included in an element&apos;s start tag, after the element indicator. In the example file in Section 11.1, the <literal moreinfo="none">img</literal> element has several attributes associated with it. The attribute <literal moreinfo="none">src=&quot;3glab.wbmp&quot;</literal> tells the microbrowser to display the image <filename moreinfo="none">3glab.wbmp</filename>; <literal moreinfo="none">alt=&quot;3G Lab Logo&quot;</literal> tells it that if, for any reason, it can&apos;t display the image, it should display the text &apos;3G Lab Logo&apos; instead; and <literal moreinfo="none">align=&quot;middle&quot;</literal> tells the microbrowser to centre the image vertically on the card.
</para>
			</section>
			<section>
				<title>11.3 Cards and Decks
</title>
				<para>Whereas HTML documents are organised into &apos;pages&apos;, WML documents are organised into units called &apos;cards&apos; and &apos;decks&apos;. A WML file is a deck, and a deck contains one or more cards. On loading a deck of several cards, a microbrowser will always display the first card by default.
</para>
				<para>A card contains a &apos;screen&apos;s worth&apos; of information. Because most WAP client devices have small display areas, the user will often have to scroll downwards to view the whole of a card; but the card should not be so long that they lose track of where they are. WML&apos;s navigation facilities enable you to jump from one card in a deck to another.
</para>
				<para>Cards are marked up using the <literal moreinfo="none">card</literal> element. There is no <literal moreinfo="none">deck</literal> element - a deck comprises everything inside a file&apos;s <literal moreinfo="none">wml</literal> element. See Section 11.5 for more information on the <literal moreinfo="none">wml</literal> element.
</para>
			</section>
			<section>
				<title>11.4 XML Validation Tags
</title>
				<programlisting format="linespecific">&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!DOCTYPE wml PUBLIC &quot;-//WAPFORUM//DTD WML 1.1//EN&quot; 
    &quot;http://www.wapforum.org/DTD/wml_1.1.xml&quot;&gt;
</programlisting>
				<para>The tag <literal moreinfo="none">&lt;?xml version=&quot;1.0&quot;?&gt;</literal> tells the browser that the file is an XML document, complying with version 1.0 of the XML specification. XML is a markup language of which WML is a specialised subset. So every valid WML document is implicitly also a valid XML document.

</para>
				<para>The second tag tells the browser where to find the Document Type Definition (DTD) for files of its type - in this case, WML files. A DTD is an electronic specification for a file&apos;s format, declaring what elements are allowed within what other elements, and what attributes each element is allowed to contain. If the structure of the file does not match the structures allowed by the DTD, then the browser knows that it contains errors, and may display a message warning the user of this. In practice, browsers are often tolerant of errors and will do their best to display files, even if they are not structurally valid. However, you should always try to structure your WML files properly - apart from being good practice, this guarantees that they will display as you intend on all WML-compliant browsers.
</para>
				<para>These two tags are not WML tags, but validation tags instructing the browser to parse the rest of the file as WML.
</para>
			</section>
			<section>
				<title>11.5 The wml Element
</title>
				<para>The top-level element in every WML deck is <literal moreinfo="none">wml</literal>. The <literal moreinfo="none">&lt;wml&gt;</literal> tag announces to the browser that everything following it should be parsed as WML data, up to the <literal moreinfo="none">&lt;/wml&gt;</literal> tag. 
</para>
				<para>Therefore, the first tag in a deck (after the validation tags) should be <literal moreinfo="none">&lt;wml&gt;</literal>, and the last tag in the deck should be <literal moreinfo="none">&lt;/wml&gt;</literal>.
</para>
			</section>
			<section>
				<title>11.6 Paragraphs
</title>
				<para>It is good practice to organise WML content into paragraphs. Paragraphs are defined by the p element. Note that in WML, unlike in HTML, each <literal moreinfo="none">&lt;p&gt;</literal> tag <emphasis role="bold">must</emphasis> have a corresponding <literal moreinfo="none">&lt;/p&gt;</literal> closing tag. For example:
</para>
				<programlisting format="linespecific">&lt;card&gt;
  &lt;p&gt;This card is divided into paragraphs. This is the first paragraph.&lt;/p&gt;
  &lt;p&gt;This is the second paragraph. It is also the last.&lt;/p&gt;
&lt;/card&gt;
</programlisting>
				<para>By default, text between <literal moreinfo="none">&lt;p&gt;...&lt;/p&gt;</literal> tags is left-aligned. You can centre- or right-align it using the <literal moreinfo="none">align</literal> attribute with the value <literal moreinfo="none">center</literal> or <literal moreinfo="none">right</literal> respectively. For example:
</para>
				<programlisting format="linespecific">&lt;p align=&quot;right&quot;&gt;This paragraph is right-aligned.&lt;/p&gt;</programlisting>
			</section>
			<section>
				<title>11.7 Hyperlinks
</title>
				<para>Like HTML, WML allows you to include hyperlinks in your documents. A hyperlink can carry the user to a different place in the current deck, a different deck on the same WAP site, or a different WAP site.
</para>
				<para>How a hyperlink is activated by the user is a matter for the browser manufacturer. A typical implementation might provide two buttons on the device to move a highlight backwards and forwards between hyperlinks, and a third button to activate the highlighted link.
</para>
				<para>The hyperlink element in WML is <literal moreinfo="none">a</literal> (as in HTML, this stands for &apos;anchor&apos;). It takes an attribute <literal moreinfo="none">href</literal>, which indicates the destination of the link. For example:
</para>
				<programlisting format="linespecific">Great oaks from &lt;a 
  href=&quot;http://www.littleacorns.com&quot;&gt;little acorns&lt;/a&gt; grow.
</programlisting>
				<para>Here, the words &apos;little acorns&apos; are a hyperlink taking the user to the WAP site www.littleacorns.com. On a browser, the hyperlink may be indicated by underlining, in which case the sentence above would be displayed like this:
</para>
				<screen format="linespecific">Great oaks from little acorns grow.
</screen>
				<para>To create hyperlinks between cards in the same deck, give each <literal moreinfo="none">card</literal> a unique <literal moreinfo="none">id</literal> attribute, and refer to that <literal moreinfo="none">id</literal> in the <literal moreinfo="none">href</literal> attribute of hyperlinks to it. In the <literal moreinfo="none">href</literal> attribute, precede the destination card&apos;s name with a hash #: this indicates that the link is to a card rather than to a file.
</para>
				<para>The example file below contains two cards, linked by referring to one another&apos;s <literal moreinfo="none">id</literal> attributes.
</para>
				<programlisting format="linespecific">&lt;?xml version=&quot;1.0&quot;?&gt;
 &lt;!DOCTYPE wml PUBLIC &quot;-//WAPFORUM//DTD WML 1.1//EN&quot;
     &quot;http://www.wapforum.org/DTD/wml_1.1.xml&quot;&gt;
 &lt;wml&gt;
    &lt;card id=&quot;card1&quot;&gt;
   &lt;p&gt;
        This is a WML card.
      &lt;/p&gt;
   &lt;p&gt;
        &lt;a href=&quot;#card2&quot;&gt;Next card...&lt;/a&gt;
      &lt;/p&gt;
    &lt;/card&gt;
    &lt;card id=&quot;card2&quot;&gt;
   &lt;p&gt;
        And this is another.
      &lt;/p&gt;
   &lt;p&gt;
        &lt;a href=&quot;#card1&quot;&gt;Previous card...&lt;/a&gt;
      &lt;/p&gt;
    &lt;/card&gt;
 &lt;/wml&gt;
</programlisting>
				<para>You can also link to a specific card in another deck by appending a hash # and the card&apos;s <literal moreinfo="none">id</literal> to the URL. For example:
</para>
				<programlisting format="linespecific">&lt;a href=&quot;anotherfile.wml#acertaincard&quot;&gt;Go to that card&lt;/a&gt;
</programlisting>
				<para>Here, the link &apos;Go to that card&apos; takes the user to the card acertaincard in the deck anotherfile.wml.
</para>
			</section>
			<section>
				<title>11.8 Tasks (do Element)
</title>
				<para>The <literal moreinfo="none">do</literal> element allows you to incorporate simple interactive features into a WML card, without reference to any particular item on the card. How the user activates a <literal moreinfo="none">do</literal> task depends on the device manufacturer&apos;s implementation of WML. The general idea is that a <literal moreinfo="none">do</literal> function should be independent of where the user has scrolled to on the page, which hyperlink is currently highlighted, and so on. Typically, a <literal moreinfo="none">do</literal> function will be activated by a physical button on the client device.
</para>
				<para>A <literal moreinfo="none">do</literal> element can perform one of four basic functions, depending on which of the following elements is present between its start and end tags. These elements are called &apos;tasks&apos;:
</para>
				<informaltable>
					<tgroup cols="2">
						<tbody>
							<row>
								<entry>
									<literal moreinfo="none">go</literal>
								</entry>
								<entry>Navigates to another WAP deck, site or card, by means of an <literal moreinfo="none">href</literal> attribute.
</entry>
							</row>
							<row>
								<entry>
									<literal moreinfo="none">prev</literal>
								</entry>
								<entry>Navigates to the previous URL on the client&apos;s history stack.
</entry>
							</row>
							<row>
								<entry>
									<literal moreinfo="none">noop</literal>
								</entry>
								<entry>Does nothing. This can be useful for certain purposes, for example, to override a default task set in the <literal moreinfo="none">template</literal> element of a deck (see Section 11.10).
</entry>
							</row>
							<row>
								<entry>
									<literal moreinfo="none">refresh</literal>
								</entry>
								<entry>Resets the current deck to the state it was in when it was first loaded. As well as resetting the visual display of a deck, <literal moreinfo="none">refresh</literal> can also be made to reset variables (see Section 11.11).
</entry>
							</row>
						</tbody>
					</tgroup>
				</informaltable>
				<para>Here is an example do statement:
</para>
				<programlisting format="linespecific"> &lt;do type=&quot;prev&quot; label=&quot;Go Back&quot; name=&quot;goback&quot;&gt;
  &lt;prev/&gt;
 &lt;/do&gt;
</programlisting>
				<para>This <literal moreinfo="none">do</literal> element includes three attributes:
</para>
				<itemizedlist>
					<listitem>
						<para>The <literal moreinfo="none">type</literal> attribute gives the client browser an indication of what category of tasks the current task belongs to. Possible values include <literal moreinfo="none">&quot;accept&quot;, &quot;prev&quot;, &quot;help&quot;, &quot;reset&quot;, &quot;options&quot;</literal> and <literal moreinfo="none">&quot;delete&quot;</literal>. Note that the type attribute has no bearing on the actual function of the task element: it simply allows the client browser to decide how to display it. For example, the Nokia 7110 WAP phone displays a <literal moreinfo="none">do</literal> element of the <literal moreinfo="none">prev</literal> type in the bottom right corner of the screen and associates it with the right navigation button.
</para>
					</listitem>
					<listitem>
						<para>The <literal moreinfo="none">label</literal> attribute tells the browser what wording to assign to the function on-screen. In some instances, a client device may automatically override a label attribute: for example, the Nokia 7110 phone always labels a <literal moreinfo="none">do type=&quot;prev&quot;</literal> function as &apos;Back&apos;, regardless of the content of the <literal moreinfo="none">label</literal> attribute.
</para>
					</listitem>
					<listitem>
						<para>The <literal moreinfo="none">name</literal> attribute gives the <literal moreinfo="none">do</literal> function an identifier by which scripting languages such as WMLScript can refer to it.
</para>
					</listitem>
				</itemizedlist>
				<para>Suppose a client device associates <literal moreinfo="none">do type=&quot;prev&quot;</literal> with its right navigation button, and accepts a WML-defined <literal moreinfo="none">label</literal> attribute. On such a device, our example do function might appear as shown in the bottom right corner of Figure 11.1.
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="11-1&figtype;">
					</imageobject>
					<caption>
						<para>Figure 11.1</para>
					</caption>
				</mediaobject>
			</section>
			<section>
				<title>11.9 Events
</title>
				<para>WML allows you to specify automatic actions in a client device that are precipitated by particular &apos;events&apos;. An &apos;event&apos; must be associated with a particular element in a WML file - either <literal moreinfo="none">card, wml</literal> or <literal moreinfo="none">option</literal>. The response to an event is defined by the <literal moreinfo="none">onevent</literal> element, which must occur within the element to which it relates. The type of event to respond to is indicated in the <literal moreinfo="none">type</literal> attribute of the <literal moreinfo="none">onevent</literal> element.
</para>
				<para>Possible values for the <literal moreinfo="none">type</literal> attribute are as shown in Figure 11.2.
</para>
				<para>The action undertaken by the client device in response to an event must be defined by one of the task elements <literal moreinfo="none">go, prev, noop</literal> or <literal moreinfo="none">refresh</literal>. The task element must be situated within the <literal moreinfo="none">onevent</literal> element.
</para>
				<para>For example:
</para>
				<programlisting format="linespecific"> &lt;card&gt;
  &lt;onevent type=&quot;onenterbackward&quot;&gt;
   &lt;go href=&quot;backwardpeople.wml&quot;/&gt;
  &lt;/onevent&gt;
  You didn&amp;apos;t enter this card backwards.
 &lt;/card&gt;
</programlisting>
				<para>If a user arrives at this card via a hyperlink or a <literal moreinfo="none">go</literal> task, they will see the message
</para>
				<screen format="linespecific">You didn&apos;t enter this card backwards.
</screen>
				<para>However, if the user arrives at the card via a <literal moreinfo="none">prev</literal> task, they will be redirected to the file <filename moreinfo="none">backwardpeople.wml</filename>.
</para>
				<para>There is another way of handling an event that is shorter, but less flexible. Instead of using the <literal moreinfo="none">onevent</literal> element, you can specify an action in the form of an attribute in the relevant <literal moreinfo="none">card</literal> or <literal moreinfo="none">wml</literal> element. For example, the sample WML above could be rewritten as follows, and would do exactly the same thing:
</para>
				<programlisting format="linespecific"> &lt;card onenterbackward=&quot;backwardpeople.wml&quot;&gt;
     You didn&amp;apos;t enter this card backwards.
 &lt;/card&gt;
</programlisting>
				<para>Note that the only kind of action possible using this method is a jump to a URL (in this case, <filename moreinfo="none">backwardpeople.wml</filename>). This is equivalent to the <literal moreinfo="none">go</literal> action. If you want to perform a <literal moreinfo="none">prev</literal>, a <literal moreinfo="none">noop</literal> or a <literal moreinfo="none">refresh</literal> action, you have to use the longer method.
</para>
				<table>
					<title>Figure 11.2: WML event types
</title>
					<tgroup cols="3">
						<thead>
							<row>
								<entry>
									<literal moreinfo="none">&lt;onevent type=&gt;</literal> attribute value</entry>
								<entry>Occurs within element(s)...</entry>
								<entry>Function</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>
									<literal moreinfo="none">&quot;ontimer&quot;</literal>
								</entry>
								<entry>
									<literal moreinfo="none">card, wml</literal>
								</entry>
								<entry>Executes the specified action when a timer expires. Timers are specified using the <literal moreinfo="none">timer</literal> element.
</entry>
							</row>
							<row>
								<entry>
									<literal moreinfo="none">&quot;onenterforward&quot;</literal>
								</entry>
								<entry>
									<literal moreinfo="none">card, wml</literal>
								</entry>
								<entry>Executes the specified action when the user arrives at the current card or deck via a hyperlink, a <literal moreinfo="none">go</literal> task or any other method that involves moving forwards in the client microbrowser&apos;s history stack.
</entry>
							</row>
							<row>
								<entry>
									<literal moreinfo="none">&quot;onenterbackward&quot;</literal>
								</entry>
								<entry>
									<literal moreinfo="none">card, wml</literal>
								</entry>
								<entry>Executes the specified action when the user arrives at the current card or deck via a <literal moreinfo="none">prev</literal> task, or any other method that involves moving backwards in the client microbrowser&apos;s history stack.
</entry>
							</row>
							<row>
								<entry>
									<literal moreinfo="none">&quot;onclick&quot;</literal>
								</entry>
								<entry>
									<literal moreinfo="none">option</literal>
								</entry>
								<entry>Executes the specified action when the user selects or deselects an option.</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
			</section>
			<section>
				<title>11.10 Templates
</title>
				<para>Suppose you create a WML deck consisting of five cards, and you want a <literal moreinfo="none">prev</literal> task on every card except the first. Rather than repeating the same <literal moreinfo="none">do</literal> statement in each of the four cards - which is laborious for you as a WML author, and uses up precious bytes in the WML file - you can use the <literal moreinfo="none">template</literal> element to specify a task to appear automatically on every card you want.
</para>
				<para>Here is an example of a WML file that uses a <literal moreinfo="none">template</literal> element:
</para>
				<programlisting format="linespecific"> &lt;?xml version=&quot;1.0&quot;?&gt;
 &lt;!DOCTYPE wml PUBLIC &quot;-//WAPFORUM//DTD WML 1.1//EN&quot;
     &quot;http://www.wapforum.org/DTD/wml_1.1.xml&quot;&gt;
 
 &lt;wml&gt;
 
  &lt;template&gt;
   &lt;do type=&quot;prev&quot;&gt;
    &lt;prev/&gt;
   &lt;/do&gt;
  &lt;/template&gt;

  &lt;card id=&quot;card1&quot;&gt;
   &lt;do type=&quot;prev&quot;&gt;
    &lt;noop/&gt;
      &lt;/do&gt;
      Love speaks, even when the lips are closed.
      &lt;br/&gt;
      &lt;a href=&quot;#card2&quot;&gt;
    Next proverb...
      &lt;/a&gt;
    &lt;/card&gt;

    &lt;card id=&quot;card2&quot;&gt;
   It is an ill dog that deserves not a crust. 
   &lt;br/&gt;
   &lt;a href=&quot;#card3&quot;&gt;
         Next proverb...
      &lt;/a&gt;
    &lt;/card&gt;

    &lt;card id=&quot;card3&quot;&gt;
      He who wants a mule without fault, must walk on foot.
      &lt;br/&gt;
      &lt;a href=&quot;#card4&quot;&gt;
        Next proverb...
      &lt;/a&gt;
    &lt;/card&gt;

    &lt;card id=&quot;card4&quot;&gt;
   Never cast a clout till May be out.
      &lt;br/&gt;
      &lt;a href=&quot;#card5&quot;&gt;
       Next proverb...
      &lt;/a&gt;
    &lt;/card&gt;

    &lt;card id=&quot;card5&quot;&gt;
   Scabby donkeys scent each other over nine hills.
   &lt;br/&gt;
  &lt;/card&gt;

 &lt;/wml&gt;
</programlisting>
				<para>When this file is viewed on a WAP microbrowser, every card except the first one has a &apos;Back&apos; link on it - even though, in the WML source, none of them contains a <literal moreinfo="none">prev</literal> task. The explanation for this is that the <literal moreinfo="none">prev</literal> task is held in the <literal moreinfo="none">template</literal> element at the beginning of the file, and is applied automatically to every card in the deck, except the first.
</para>
				<para>The reason there is no &apos;Back&apos; link on the first card is that the first card contains a <literal moreinfo="none">noop</literal> task. Because a task defined in a card always overrides a default task of the same type as specified in the <literal moreinfo="none">template</literal>, and because <literal moreinfo="none">noop</literal> does nothing, this card displays nothing in place of a &apos;Back&apos; link. 
</para>
			</section>
			<section>
				<title>11.11 Variables
</title>
				<para>One of the most interesting features of WML is its ability to process variables. If you have any programming experience, you will know that a variable is a &apos;label&apos; for a numeric value or a string of characters in a computer program. A common use of variables is to store input from a user or another external source - in other words, information that can&apos;t be written into the program itself.
</para>
				<para>Variables in WML enable you to implement interactive features into your cards and decks without getting involved in the complexities of scripting languages like WMLScript. Note that the only variables allowed in WML are strings.
</para>
				<para>There are a number of ways in which you can specify variables. One of the most useful is via the <literal moreinfo="none">input</literal> element, which allows the user to enter information into the client device&apos;s interface.
</para>
				<para>Here is a very simple WML deck that writes a &apos;proverb&apos; based on terms the user enters through the <literal moreinfo="none">input</literal> element:
</para>
				<programlisting format="linespecific"> &lt;?xml version=&quot;1.0&quot;?&gt;
 &lt;!DOCTYPE wml PUBLIC &quot;-//WAPFORUM//DTD WML 1.1//EN&quot;
     &quot;http://www.wapforum.org/DTD/wml_1.1.xml&quot;&gt;
 &lt;wml&gt;
  &lt;card id=&quot;card1&quot; title=&quot;Proverb Wizard&quot;&gt;
      Name an animal:
      &lt;input name=&quot;animal&quot;/&gt;
      Name a vegetable:
      &lt;input name=&quot;vegetable&quot;/&gt;
       &lt;a href=&quot;#card2&quot;&gt;
     View proverb...
       &lt;/a&gt;
  &lt;/card&gt;

  &lt;card id=&quot;card2&quot; title=&quot;Your proverb&quot;&gt;
   &lt;do type=&quot;accept&quot; label=&quot;Another?&quot;&gt;
    &lt;go href=&quot;#card1&quot;/&gt;
   &lt;/do&gt;
   A small $(animal) may eat a large $(vegetable).
  &lt;/card&gt;

 &lt;/wml&gt;
</programlisting>
				<para>When this file is opened on a microbrowser, the following card will be displayed:
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="11-3&figtype;">
					</imageobject>
					<caption>
						<para>Figure 11.3</para>
					</caption>
				</mediaobject>
				<para>As can be seen, there are two input fields. These are created by the tags <literal moreinfo="none">&lt;input name=&quot;animal&quot;/&gt;</literal> and <literal moreinfo="none">&lt;input name=&quot;vegetable&quot;/&gt;</literal> in the WML source. The <literal moreinfo="none">name</literal> attributes tell the browser to create the variables <literal moreinfo="none">animal</literal> and <literal moreinfo="none">vegetable</literal> respectively, based on what the user types into each field.
</para>
				<para>To select a horse for the animal and a radish for the vegetable, enter <userinput moreinfo="none">horse</userinput> into the first field and <userinput moreinfo="none">radish</userinput> into the second field. (The actual mechanism for entering text will depend on your microbrowser. For example, it may present you with an <interface moreinfo="none">Edit</interface> option that you activate by pressing one of the phone&apos;s navigation buttons.)
</para>
				<para>The microbrowser display will now be as in Figure 11.4.
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="11-4&figtype;">
					</imageobject>
					<caption>
						<para>Figure 11.4</para>
					</caption>
				</mediaobject>
				<para>Now, activate the &apos;View proverb...&apos; link. A new card is loaded, showing a proverb based on the terms you entered in the first card (see Figure 11.5).
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="11-5&figtype;">
					</imageobject>
					<caption>
						<para>Figure 11.5</para>
					</caption>
				</mediaobject>
				<para>In the source WML you can see how the terms entered in the first card were passed to the second card. The variables <literal moreinfo="none">animal</literal> and <literal moreinfo="none">vegetable</literal> were set in the tags <literal moreinfo="none">&lt;input name=&quot;animal&quot;/&gt;</literal> and <literal moreinfo="none">&lt;input name=&quot;vegetable&quot;/&gt;</literal>. 
</para>
				<para>The source text in the second card looks like this:
</para>
				<programlisting format="linespecific">A small $(animal) may eat a large $(vegetable).
</programlisting>
				<para>When the browser encounters a dollar symbol $, it knows that what follows in parentheses is a variable. So instead of displaying &apos;(animal)&apos; it looks for the variable called <literal moreinfo="none">animal</literal> and displays its value - in this example, the string &apos;horse&apos;. It does the same with the variable <literal moreinfo="none">vegetable</literal>, substituting its name with &apos;radish&apos;.
</para>
				<para>(If you want to display a dollar symbol on the screen, use two dollar symbols $$ in your WML file.)
</para>
			</section>
			<section>
				<title>11.12 Timers
</title>
				<para>You can incorporate a timer into a WML card or deck using the <literal moreinfo="none">timer</literal> element. When a timer runs out, an action is performed as specified in the <literal moreinfo="none">ontimer</literal> event handler. See Section 11.9 for more details about event handling.
</para>
				<para>
					<literal moreinfo="none">timer</literal> takes a <literal moreinfo="none">value</literal> attribute, specifying how long the timer should run for. The value is expressed in tenths of a second.
</para>
				<para>Here is an example timer implementation:
</para>
				<programlisting format="linespecific"> &lt;?xml version=&quot;1.0&quot;?&gt;
 &lt;!DOCTYPE wml PUBLIC &quot;-//WAPFORUM//DTD WML 1.1//EN&quot;
     &quot;http://www.wapforum.org/DTD/wml_1.1.xml&quot;&gt;
 &lt;wml&gt;
  &lt;card id=&quot;wait&quot;&gt;
   &lt;onevent type=&quot;ontimer&quot;&gt;
    &lt;go href=&quot;#thankyou&quot;/&gt;
   &lt;/onevent&gt;
   &lt;timer value=&quot;40&quot;/&gt;
   &lt;p&gt;
   Please wait.
   &lt;/p&gt;
  &lt;/card&gt;
  &lt;card id=&quot;thankyou&quot;&gt;
   &lt;p&gt;
   Thank you for waiting.
   &lt;/p&gt;
  &lt;/card&gt;
 &lt;/wml&gt;
</programlisting>
				<para>When you first load this file you will see the message &apos;Please wait.&apos; After about four seconds, the first card will time out and the second card will appear, showing the message &apos;Thank you for waiting.&apos;
</para>
			</section>
			<section>
				<title>11.13 Images
</title>
				<para>WML can include embedded images. These must be in two-colour wireless bitmap (WBMP) format. There are several free WBMP editors that can be downloaded from the World Wide Web.
</para>
				<para>To embed an image in a file, use the <literal moreinfo="none">img</literal> element with some or all of the attributes shown in Figure 11.6. For example:
</para>
				<programlisting format="linespecific">&lt;img src=&quot;3glab.wbmp&quot; alt=&quot;3G Lab Logo&quot; align=&quot;middle&quot;/&gt;
</programlisting>
				<table>
					<title>Figure 11.6: Image attributes</title>
					<tgroup cols="2">
						<thead>
							<row>
								<entry>Attribute
(* = required)
</entry>
								<entry>Function</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>
									<literal moreinfo="none">src</literal> * </entry>
								<entry>Specifies the URL of the source file for the image.
</entry>
							</row>
							<row>
								<entry>
									<literal moreinfo="none">alt</literal> * </entry>
								<entry>Specifies text for the browser to display if the image cannot be displayed.
</entry>
							</row>
							<row>
								<entry>
									<literal moreinfo="none">localsrc</literal>
								</entry>
								<entry>Specifies a local source for the image.
</entry>
							</row>
							<row>
								<entry>
									<literal moreinfo="none">vspace</literal>
								</entry>
								<entry>Specifies the amount of blank space to appear above and below the image in the microbrowser display. 
</entry>
							</row>
							<row>
								<entry>
									<literal moreinfo="none">hspace</literal>
								</entry>
								<entry>Specifies the amount of blank space to appear to the left and the right of the image in the microbrowser display.
</entry>
							</row>
							<row>
								<entry>
									<literal moreinfo="none">align</literal>
								</entry>
								<entry><para>Specifies the vertical alignment of the image in relation to the surrounding text. Must have the value <literal moreinfo="none">&quot;top&quot;, &quot;middle&quot;</literal> or <literal moreinfo="none">&quot;bottom&quot;</literal>.
</para><para>
To change the horizontal alignment of an image, enclose it in an appropriately formatted paragraph.
</para><para>
For example:
<programlisting format="linespecific">
     &lt;p align=&quot;center&quot;&gt;
     &lt;img src=&quot;image.wbmp&quot; 
		   alt=&quot;An image&quot;/&gt;
     &lt;/p&gt;
</programlisting></para></entry>
							</row>
							<row>
								<entry><literal moreinfo="none">height,width</literal></entry>
								<entry>Specify the height and width of the image in pixels. This allows the browser to reserve space for it while it loads therest  of the card. If these attributes are omitted, the image is displayed at its actual size, though the microbrowser will probably not reserve space for it while the card is loading.

If the height and width attributes do not match the actual height and width of an image, the microbrowser either scales the image to match the attributes, or else ignores the attributes and shows the image at its actual size.</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
			</section>
		</chapter>
		<chapter>
			<title>12  Example WAP Sites</title>
			<para>Included on the Alligata Server CD-ROM are five example WAP sites. If you installed the example sites along with the Alligata Server (see Sections 4 and 5), and you have an HTTP server such as Apache running on your computer, you can view them from a WAP phone or a WAP phone emulator. 
</para>
			<para>The example sites are illustrations of the kinds of service you can implement using WAP. You can create simple sites using just WML, or you can incorporate dynamic features into them using scripting languages like Perl and PHP. The most important thing to remember is to keep the files you serve as small and simple as possible. A compiled WML file should not be larger than 1400 bytes, which means the size of your source WML file should not exceed about 3000 characters.
</para>
<FormalPara>
<title>To view the example WAP sites:</title>
<Para>
			<orderedlist inheritnum="ignore" continuation="restarts">
				<listitem>
					<para>If you have not already done so, install the Alligata Server as described in Sections 4 and 5. If you are installing from a graphical user interface, select &apos;Alligata Server example sites&apos; in the main installation dialog box. If you are installing from the command prompt, enter Y when you are asked, &apos;Install Alligata Server examples?&apos;.
</para>
				</listitem>
				<listitem>
					<para>Start the Bearer Box and the WAP Box using any of the methods described in Section 8.1.
</para>
				</listitem>
				<listitem>
					<para>Start the Web server. For example, to start Apache:
</para>
					<formalpara>
						<title>Linux users: 
</title>
						<para>Type <userinput moreinfo="none">/etc/rc.d/init.d/httpd start</userinput> at the command prompt, and press ENTER.
</para>
					</formalpara>
					<formalpara>
						<title>Solaris users: 
</title>
						<para>Type <userinput moreinfo="none">/etc/init.d/apache start</userinput> at the command prompt, and press ENTER.
</para>
					</formalpara>
				</listitem>
				<listitem>
					<para>Configure your WAP client device to use your installation of the Alligata Server as its WAP gateway. An example configuration is shown in Figure 12.1.
</para>
					<table>
						<title>Figure 12.1: Example WAP phone configuration
</title>
						<tgroup cols="2">
							<tbody>
								<row>
									<entry>Home URL:</entry>
									<entry>
										<literal moreinfo="none">http://www.mysite.net</literal>
									</entry>
								</row>
								<row>
									<entry>Service name:</entry>
									<entry>
										<literal moreinfo="none">Alligata</literal>
									</entry>
								</row>
								<row>
									<entry>IP address: </entry>
									<entry>
										<literal moreinfo="none">10.0.0.1</literal>
									</entry>
								</row>
								<row>
									<entry>Dial-up phone number:</entry>
									<entry>
										<literal moreinfo="none">0999123456</literal>
									</entry>
								</row>
								<row>
									<entry>Bearer type:</entry>
									<entry>
										<literal moreinfo="none">data</literal>
									</entry>
								</row>
								<row>
									<entry>Call type:</entry>
									<entry>
										<literal moreinfo="none">analogue</literal>
									</entry>
								</row>
								<row>
									<entry>Connection type:</entry>
									<entry>
										<literal moreinfo="none">cont</literal>
									</entry>
								</row>
								<row>
									<entry>PPP security:</entry>
									<entry>
										<literal moreinfo="none">off</literal>
									</entry>
								</row>
								<row>
									<entry>Authentication mode:</entry>
									<entry>
										<literal moreinfo="none">normal</literal>
									</entry>
								</row>
								<row>
									<entry>Login:</entry>
									<entry>
										<literal moreinfo="none">foo</literal>
									</entry>
								</row>
								<row>
									<entry>Password: </entry>
									<entry>
										<literal moreinfo="none">bar</literal>
									</entry>
								</row>
							</tbody>
						</tgroup>
					</table>
					<para>The login and password settings are those of your Point-to-Point Protocol (PPP) server.
</para>
				</listitem>
				<listitem>
					<para>On your WAP client device, navigate to the URL of the example sites index. By default this will be the URL of your Web server, followed by <filename moreinfo="none">/wml/</filename>; for example, <filename moreinfo="none">http://acomputer.asite.net/wml/</filename>.
</para>
				</listitem>
				<listitem>
					<para>The card in Figure 12.2 is displayed.
</para>
					<mediaobject>
						<imageobject>
							<imagedata fileref="12-2&figtype;">
						</imageobject>
						<caption>
							<para>Figure 12.2: Site Examples index</para>
						</caption>
					</mediaobject>
					<para>From this card, you can navigate to any of the example sites by selecting the relevant hyperlink. The example sites are described in Sections 12.1 to 12.5.
</para>
				</listitem>
			</orderedlist>
</Para>
</FormalPara>

			<section>
				<title>12.1 Example Site 1: Static WML (Simple)
</title>
				<para>The simplest kind of WAP site consists of a set of static WML decks or cards. You can find examples of this kind of site by selecting &apos;Static Simple&apos; or &apos;Static Complex&apos; from the Site Examples index.
</para>
				<para>The &apos;Static Simple&apos; is discussed in Section 11.1. It is a single WML card that displays the message, &apos;This is static WML text.&apos;
</para>
			</section>
			<section>
				<title>12.2 Example Site 2: Static WML (Complex)
</title>
				<para>If you select &apos;Static Complex&apos; from the Site Examples index page, you will be presented with the logo shown in Figure 12.3.
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="12-3&figtype;">
					</imageobject>
					<caption>
						<para>Figure 12.3</para>
					</caption>
				</mediaobject>
				<para>After a few seconds the logo will disappear, to be replaced by a set of links (see Figure 12.4).
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="12-4&figtype;">
					</imageobject>
					<caption>
						<para>Figure 12.4</para>
					</caption>
				</mediaobject>
				<para>If you follow a link, you will be taken to the corresponding piece of information. You can also use the link &apos;ACME home&apos; to take you back to the home deck. (Since this is a <literal moreinfo="none">prev</literal> task, it may simply be labelled &apos;Back&apos; on your device&apos;s display - see Section 11.8.)
</para>
				<para>If you select &apos;ACME Vacancies&apos;, the card in Figure 12.5 will appear on your screen.
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="12-5&figtype;">
					</imageobject>
					<caption>
						<para>Figure 12.5</para>
					</caption>
				</mediaobject>
				<para>If you select a link from this card, you will be taken to information about the relevant post. For example, &apos;Head of Marketing&apos; will show you the card in Figure 12.6.
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="12-6&figtype;">
					</imageobject>
					<caption>
						<para>Figure 12.6</para>
					</caption>
				</mediaobject>
				<para>From here you can use the &apos;ACME Vacancies&apos; link to return to the list of jobs. (Again, this a <literal moreinfo="none">prev</literal> task, so your device may just label it &apos;Back&apos;.) To go right back to the home deck, keep navigating backwards in the same way.
</para>
				<para>From the home deck, you can navigate through any series of cards in the way just described.
</para>
				<para>The first file that the microbrowser loaded when it visited the site <filename moreinfo="none">Static Complex</filename> is called <filename moreinfo="none">index.wml</filename>. Its source is as follows:
</para>
				<programlisting format="linespecific"> &lt;?xml version=&quot;1.0&quot;?&gt;
 &lt;!DOCTYPE wml PUBLIC &quot;-//WAPFORUM//DTD WML 1.1//EN&quot;
     &quot;http://www.wapforum.org/DTD/wml_1.1.xml&quot;&gt;
 &lt;wml&gt;
  &lt;card id=&quot;logo&quot; ontimer=&quot;#menu&quot; title=&quot;Welcome to ACME&quot; newcontext=&quot;true&quot;&gt;
      &lt;timer value=&quot;30&quot;/&gt;
   &lt;img alt=&quot;ACME corp&quot; src=&quot;acmelogo.wbmp&quot; align=&quot;middle&quot;/&gt;
  &lt;/card&gt;
  &lt;card id=&quot;menu&quot; name=&quot;menu&quot; title=&quot;the ACME menu&quot;&gt;
   &lt;do type=&quot;prev&quot; label=&quot;ACME home&quot;&gt;
    &lt;prev/&gt;
   &lt;/do&gt;
   &lt;a href=&quot;info.wml&quot;&gt;
    What is ACME?
   &lt;/a&gt;
   &lt;br/&gt;
   &lt;a href=&quot;contact.wml&quot;&gt;
    Contacting ACME
   &lt;/a&gt;
   &lt;br/&gt;
   &lt;a href=&quot;employ.wml&quot;&gt;
    ACME Vacancies
   &lt;/a&gt;
   &lt;br/&gt;
   &lt;a href=&quot;wpaper.wml&quot;&gt;
    ACME White Paper
   &lt;/a&gt;
  &lt;/card&gt;
 &lt;/wml&gt;
</programlisting>
				<para>Remember that your microbrowser does not see this data but a compressed version of it that is less easy for a human being to decipher, but quicker to transmit and using less of the client device&apos;s limited memory.
</para>
				<para>The first two tags in the file are the XML validation tags:
</para>
				<programlisting format="linespecific">&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!DOCTYPE wml PUBLIC &quot;-//WAPFORUM//DTD WML 1.1//EN&quot;
    &quot;http://www.wapforum.org/DTD/wml_1.1.xml&quot;&gt;
</programlisting>
				<para>As we saw earlier, every WML file needs to start with these tags, which specify which versions of XML and WML the file conforms to (see Section 11.4).
</para>
				<para>Next comes the deck-level <literal moreinfo="none">&lt;wml&gt;</literal> tag. Following that is the first card in the deck:
</para>
				<programlisting format="linespecific"> &lt;card id=&quot;logo&quot; ontimer=&quot;#menu&quot; title=&quot;Welcome to ACME&quot;    
 newcontext=&quot;true&quot;&gt;
  &lt;timer value=&quot;30&quot;/&gt;
  &lt;img alt=&quot;ACME corp&quot; src=&quot;acmelogo.wbmp&quot; align=&quot;middle&quot;/&gt;
 &lt;/card&gt;
</programlisting>
				<para>This is the card containing the ACME logo. Because it is the first card in the deck, it is the one that appears by default when you load the file. 
</para>
				<para>Here is a description of the card item by item. 
</para>
				<para>First, you will see that the <literal moreinfo="none">card</literal> element contains four attributes:
</para>
				<itemizedlist>
					<listitem>
						<para>
							<literal moreinfo="none">id=&quot;logo&quot;</literal> gives the card a name by which other cards or decks can refer to it.
</para>
					</listitem>
					<listitem>
						<para>
							<literal moreinfo="none">ontimer=&quot;#menu&quot;</literal> tells the microbrowser that when the timer contained in the card runs out, it should load the card <filename moreinfo="none">menu</filename>. The timer is defined in the <literal moreinfo="none">timer</literal> element.</para>
					</listitem>
					<listitem>
						<para>
							<literal moreinfo="none">title=&quot;Welcome to ACME&quot;</literal> defines a title to appear at the top of the card in the microbrowser.</para>
					</listitem>
					<listitem>
						<para>
							<literal moreinfo="none">newcontext=&quot;true&quot;</literal> instructs the microbrowser to reset its &apos;context&apos; when the card is loaded. A microbrowser&apos;s context consists of information it holds in its memory about recent events. Specifically, <literal moreinfo="none">newcontext=&quot;true&quot;</literal> removes all WML variables, clears the microbrowser&apos;s navigation history, and resets other information in the microbrower to its default value. precisely what information this is depends on the microbrowser. </para>
					</listitem>
				</itemizedlist>
				<para>The next element is <literal moreinfo="none">timer</literal>. It has the attribute <literal moreinfo="none">value=&quot;30&quot;</literal>, which tells the microbrowser to wait about three seconds before performing the action specified in the card&apos;s <literal moreinfo="none">ontimer</literal> attribute.
</para>
				<para>Note that, because <literal moreinfo="none">timer</literal> is an empty element - that is, one without a closing tag - its tag must end in a forward slash /.
</para>
				<para>The remaining element in the card is <literal moreinfo="none">img</literal>, with three attributes:
</para>
				<itemizedlist>
					<listitem>
						<para>
							<literal moreinfo="none">alt=&quot;ACME corp&quot;</literal> tells the microbrowser to display the text &apos;ACME corp&apos; if it cannot load the image for any reason.
</para>
					</listitem>
					<listitem>
						<para>
							<literal moreinfo="none">src=&quot;acmelogo.wbmp&quot;</literal> tells the microbrowser that the image to be displayed is the file <filename moreinfo="none">acmelogo.wbmp</filename>.
</para>
					</listitem>
					<listitem>
						<para>
							<literal moreinfo="none">align=&quot;middle&quot;</literal> tells the microbrowser to centre the image vertically, in relation to the surrounding text.
</para>
					</listitem>
				</itemizedlist>
				<para>
					<literal moreinfo="none">img</literal>, like <literal moreinfo="none">timer</literal>, is an empty element, so the tag needs a forward slash / at the end of it.
</para>
				<para>Finally, the card ends with a <literal moreinfo="none">&lt;/card&gt;</literal> tag.
</para>
				<para>The second card in the deck looks like this:
</para>
				<programlisting format="linespecific"> &lt;card id=&quot;menu&quot; name=&quot;menu&quot; title=&quot;The ACME Menu&quot;&gt;
  &lt;do type=&quot;prev&quot; label=&quot;ACME home&quot;&gt;
   &lt;prev/&gt;
  &lt;/do&gt;
  &lt;a href=&quot;info.wml&quot;&gt;
   What is ACME?
  &lt;/a&gt;
  &lt;br/&gt;
  &lt;a href=&quot;contact.wml&quot;&gt;
   Contacting ACME
  &lt;/a&gt;
  &lt;br/&gt;
  &lt;a href=&quot;employ.wml&quot;&gt;
   ACME Vacancies
  &lt;/a&gt;
  &lt;br/&gt;
  &lt;a href=&quot;wpaper.wml&quot;&gt;
   ACME White Paper
  &lt;/a&gt;
 &lt;/card&gt;
</programlisting>
				<para>This is the menu that appeared when the ACME logo card timed out. As you can see, it is a list of hyperlinks to other WML files, with each hyperlink being defined by its own a element. Note that the card begins with a do element, which implements a prev link to allow navigation back to the previous card.
</para>
				<para>We selected the hyperlink &apos;ACME Vacancies&apos; from this menu. As you can see from the source WML, that link goes to the file <filename moreinfo="none">employ.wml</filename>, which looks like this:
</para>
				<programlisting format="linespecific"> &lt;?xml version=&quot;1.0&quot;?&gt;
 &lt;!DOCTYPE wml PUBLIC &quot;-//WAPFORUM//DTD WML 1.1//EN&quot;
     &quot;http://www.wapforum.org/DTD/wml_1.1.xml&quot;&gt;

  &lt;wml&gt;
   &lt;card id=&quot;employ&quot; title=&quot;Vacancies&quot;&gt;
    &lt;do type=&quot;prev&quot; label=&quot;ACME home&quot;&gt;
     &lt;prev/&gt;
    &lt;/do&gt;
    &lt;a href=&quot;#job1&quot;&gt;
     Systems Analyst
    &lt;/a&gt;
    &lt;br/&gt;
    &lt;a href=&quot;#job2&quot;&gt;
     Head of Marketing
    &lt;/a&gt;
    &lt;br/&gt;
    &lt;a href=&quot;#job3&quot;&gt;
     Chief of Admin
    &lt;/a&gt;
    &lt;br/&gt;
    &lt;a href=&quot;contact.wml&quot;&gt;
     -=Contact ACME=-
    &lt;/a&gt;
   &lt;/card&gt;

   &lt;card id=&quot;job1&quot; title=&quot;Job: Systems Analyst&quot;&gt;
    &lt;do type=&quot;prev&quot; label=&quot;ACME Vacancies&quot;&gt;
     &lt;prev/&gt;
    &lt;/do&gt;
    &lt;p&gt;
    A position has opened for a Systems Analyst. 
		Please send us your CV if you think you are 
		suitably skilled in Systems Analysis.
    &lt;/p&gt;
   &lt;/card&gt;
   &lt;card id=&quot;job2&quot; title=&quot;Job: Marketing Head&quot;&gt;
    &lt;do type=&quot;prev&quot; label=&quot;ACME Vacancies&quot;&gt;
     &lt;prev/&gt;
    &lt;/do&gt;
    &lt;p&gt;
    ACME is looking for a new head of Marketing: 
		someone who is living in Tibet, or can move 
		there at short notice, with a 3rd tier 
		university degree and at least five years&amp;apos; 
		experience in a marketing environment. 
		Must be a people person.
    &lt;/p&gt;
   &lt;/card&gt;
   &lt;card id=&quot;job3&quot; title=&quot;Job: Chief Admin&quot;&gt;
    &lt;do type=&quot;prev&quot; label=&quot;ACME Vacancies&quot;&gt;
     &lt;prev/&gt;
    &lt;/do&gt;
    &lt;p&gt;
    ACME is looking for a new chief of administration. 
		If you are a talented manager with a head for 
		figures, an eye for detail and a gift for 
		coercion, we would like to hear from you.
    &lt;/p&gt;
   &lt;/card&gt;
  &lt;/wml&gt;
</programlisting>
				<para>All the features of this file are described elsewhere in this guide. It is a deck of four cards, with the first card presenting hyperlinks to the other three. In the earlier example the link &apos;Head of Marketing&apos; was chosen, which goes to the card <filename moreinfo="none">job2</filename>.
</para>
				<para>Note that, once again, every card in the deck has a <literal moreinfo="none">&lt;prev/&gt;</literal> link to return to the previous card.
</para>
			</section>
			<section>
				<title>12.3 Example Site 3: Perl System Resource Monitor
</title>
				<para>A WAP site does not need to consist just of static WML files: it can also contain scripts that generate WML decks on the fly. To generate WML dynamically, you can use any of the same scripting languages that are available to generate HTML pages on the World Wide Web. All you have to remember is to make your output as concise as possible (less than 3000 characters) and that it needs to be valid WML.
</para>
				<para>One language already widely used for Web scripting is the Practical Extraction and Report Language (Perl). Perl&apos;s powerful text processing capabilities make it equally suitable for WAP scripting.</para>
				<para>You call a WAP script from a mobile device exactly as you would call a Web script from a desktop computer: the relevant URL just has to point to the script file rather than a WML deck. For example, <filename moreinfo="none">http://www.awapsite.net/anyscript.pl</filename> could execute the Perl script <filename moreinfo="none">anyscript.pl</filename> on the WAP site <filename moreinfo="none">http://www.awapsite.net/</filename>. (Of course, the script&apos;s output needs to be in WML, in order to display on a WAP microbrowser.)
</para>
				<para>To download Perl and to find out more about it, visit <filename moreinfo="none">www.perl.com</filename>. Many books are also available on Perl programming.
</para>
				<para>The Alligata Server&apos;s example Perl site retrieves system information from its host machine and sends it in WML format to the client device. Because the information is retrieved using Linux/UNIX commands, the Perl script must be running on a Linux or UNIX operating system.
</para>
				<para>To view the Alligata Server example Perl site, select &apos;Sysinfo Perl&apos; from the Site Examples index. You will see the card in Figure 12.7.
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="12-7&figtype;">
					</imageobject>
					<caption>
						<para>Figure 12.7</para>
					</caption>
				</mediaobject>
				<para>From top to bottom, this information is as follows:
</para>
				<informaltable>
					<tgroup cols="2">
						<tbody>
							<row>
								<entry>Linux-2.2.16</entry>
								<entry>Operating system
</entry>
							</row>
							<row>
								<entry>19 users</entry>
								<entry>Number of logins since the system was started up
</entry>
							</row>
							<row>
								<entry>Up: 11 Days 7h54m</entry>
								<entry>Time the system has been running
</entry>
							</row>
							<row>
								<entry>CPU: 24%  AVG: 1.18</entry>
								<entry>Current CPU load and load average
</entry>
							</row>
							<row>
								<entry>RAM: 98% </entry>
								<entry>Amount of RAM used
</entry>
							</row>
							<row>
								<entry>SWP: 8% </entry>
								<entry>Amount of swap space used
</entry>
							</row>
						</tbody>
					</tgroup>
				</informaltable>
				<para>The first item in the list is a hyperlink that takes you to a card showing the names of the users currently logged in to the server machine (see Figure 12.8).
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="12-8&figtype;">
					</imageobject>
					<caption>
						<para>Figure 12.8</para>
					</caption>
				</mediaobject>
				<para>The WML generated by the Perl script for this file is as follows:
</para>
				<programlisting format="linespecific"> &lt;?xml version=&quot;1.0&quot;?&gt;
 &lt;!DOCTYPE wml PUBLIC &quot;-//WAPFORUM//DTD WML 1.1//EN&quot;
     &quot;http://www.wapforum.org/DTD/wml_1.1.xml&quot;&gt;
 &lt;wml&gt;
  &lt;template&gt;
   &lt;do type=&quot;prev&quot; name=&quot;back&quot; label=&quot;Back&quot;&gt;
    &lt;prev/&gt;
   &lt;/do&gt;
  &lt;/template&gt;
  &lt;card id=&quot;main&quot; title=&quot;apc.acompany.net&quot; newcontext=&quot;true&quot;&gt;
   &lt;p&gt;
   &lt;a href=&quot;#users&quot;&gt;
    Linux-2.2.16 19 users
   &lt;/a&gt;
   &lt;/p&gt;
   &lt;p&gt;
    Up: 11 Days 7h54m
   &lt;/p&gt;
   &lt;p&gt;
    CPU: 24%  AVG: 1.18
   &lt;/p&gt;
   &lt;p&gt;
    RAM: 98%  SWP: 8%
   &lt;/p&gt;
  &lt;/card&gt;
  &lt;card id=&quot;users&quot; title=&quot;users logged in&quot;&gt;
   &lt;p&gt;
    atrull fturton ymuller
   &lt;/p&gt;
  &lt;/card&gt;
 &lt;/wml&gt;
12.4</programlisting>
			</section>
			<section>
				<title>12.4 Example Site 4: PHP System Resource Monitor
</title>
				<para>PHP is a server-side embedded scripting language optimised for use on the World Wide Web. Like Perl, it can be made to generate dynamic output in WML as easily as in HTML. Again, the important thing to remember is that a dynamically generated WML file, like a static WML file, must be less than about 3000 bytes long before compression.
</para>
				<para>PHP is an open source programming language. You can learn about it at the PHP Web site at <ulink url="http://www.php.net">www.php.net</ulink>. This site includes a complete online PHP manual, a Quick Reference Guide and a Frequently Asked Questions page.
</para>
				<para>The Alligata Server package includes two example PHP sites. The first retrieves system information from its host machine&apos;s operating system using the <literal moreinfo="none">uptime</literal> and <literal moreinfo="none">free</literal> Linux/UNIX commands and the PHP <literal moreinfo="none">fsockopen</literal> function.
</para>
				<para>To view the PHP System Resource Monitor, select the link &apos;Sysinfo PHP&apos; from the Site Examples index.
</para>
				<para>You will see the site&apos;s main index card (see Figure 12.9).
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="12-9&figtype;">
					</imageobject>
					<caption>
						<para>Figure 12.9</para>
					</caption>
				</mediaobject>
				<para>Follow any of the three links, &apos;Load/Uptime&apos;, &apos;Memory&apos; or &apos;Port Status&apos;, to display the relevant card. Example cards are shown below. For ease of legibility, the content of these cards is shown in full, rather than on a microbrowser screen. The information in the &apos;Load/Uptime&apos; card is explained in the right column; the information in the &apos;Memory&apos; and the &apos;Port Status&apos; cards is self-explanatory.
</para>
				<screen format="linespecific">Load/Uptime
--
time: 2:40pm The time according to the system&apos;s clock
up: 8 d 1:56 The amount of time the system has been running
users: 7  The number of logins since the system was started up
load (1): 2.91 The system&apos;s average load over the last minute
load (5): 2.53 The system&apos;s average load over the last 5 minutes
load (15): 2.08 The system&apos;s average load over the last 15 minutes

Memory
--
total: 192704
used: 189652
free: 3052
shared: 117292
buffers: 30056
cached: 28444
 
Port Status
--
21: open
22: open
23: open
53: closed
80: open</screen>
				<para>The PHP-generated information is all held in a single WML deck:
</para>
				<programlisting format="linespecific"> &lt;?xml version=&quot;1.0&quot;?&gt;
 &lt;!DOCTYPE wml PUBLIC &quot;-//WAPFORUM//DTD WML 1.1//EN&quot;
     &quot;http://www.wapforum.org/DTD/wml_1.1.xml&quot;&gt;
 &lt;wml&gt;
  &lt;head&gt;
  &lt;meta http-equiv=&quot;Cache-Control&quot; content=&quot;max-age=0&quot; forua=&quot;true&quot;/&gt;
  &lt;/head&gt;

  &lt;template&gt;
   &lt;do type=&quot;accept&quot;&gt;
    &lt;go href=&quot;#&quot;/&gt;
   &lt;/do&gt;
   &lt;do type=&quot;prev&quot; name=&quot;back&quot; label=&quot;Back&quot;&gt;
    &lt;prev/&gt;
   &lt;/do&gt;
  &lt;/template&gt;

  &lt;card id=&quot;init&quot; newcontext=&quot;true&quot;&gt;
   &lt;p align=&quot;center&quot;&gt;
   &lt;b&gt;System Resource Monitor:&lt;/b&gt;
   &lt;/p&gt;
   &lt;p&gt;
   &lt;a href=&quot;#up&quot;&gt;Load/Uptime&lt;/a&gt;
   &lt;br/&gt;
   &lt;a href=&quot;#mem&quot;&gt;Memory&lt;/a&gt;
   &lt;br/&gt;
   &lt;a href=&quot;#ports&quot;&gt;Port Status&lt;/a&gt;
   &lt;br/&gt;
   &lt;/p&gt;
  &lt;/card&gt;

  &lt;card id=&quot;up&quot;&gt;
   &lt;p align=&quot;center&quot;&gt;
   &lt;b&gt;Load/Uptime&lt;/b&gt;
   &lt;br/&gt;
   --
   &lt;/p&gt;
   &lt;p align=&quot;left&quot;&gt;
   time: 12:29pm
   &lt;br/&gt;
   up: 8 d 1:56
   &lt;br/&gt;
   users: 7
   &lt;br/&gt;
   load (1): 2.91
   &lt;br/&gt;
   load (5): 2.53
   &lt;br/&gt;
   load (15): 2.08
   &lt;br/&gt;
   &lt;/p&gt;
  &lt;/card&gt;

  &lt;card id=&quot;mem&quot;&gt;
   &lt;p align=&quot;center&quot;&gt;
   &lt;b&gt;Memory&lt;/b&gt;
   &lt;br/&gt;
   --
   &lt;/p&gt;
   &lt;p align=&quot;left&quot;&gt;
   total: 192704
   &lt;br/&gt;
   used: 189652
   &lt;br/&gt;
   free: 3052
   &lt;br/&gt;
   shared: 117292
   &lt;br/&gt;
   buffers: 30056
   &lt;br/&gt;
   cached: 28444
   &lt;br/&gt;
   &lt;/p&gt;
  &lt;/card&gt;

  &lt;card id=&quot;ports&quot;&gt;
   &lt;p align=&quot;center&quot;&gt;
   &lt;b&gt;Port Status&lt;/b&gt;
   &lt;br/&gt;
   --
   &lt;/p&gt;
   &lt;p align=&quot;left&quot;&gt;
   21: open
   &lt;br/&gt;
   22: open
   &lt;br/&gt;
   23: open
   &lt;br/&gt;
   53: closed
   &lt;br/&gt;
   80: open
   &lt;br/&gt;
   &lt;/p&gt;
  &lt;/card&gt;
 &lt;/wml&gt;
</programlisting>
			</section>
			<section>
				<title>12.5 Example Site 5: &apos;PAT&apos; PHP Mail
</title>
				<para>The Alligata Server&apos;s second example PHP site, &apos;PAT&apos;, enables you to read your e-mail from a WAP client device. It uses PHP&apos;s IMAP functions to retrieve messages from your e-mail server, embeds them in WML, and sends them to your mobile device. Despite their name, IMAP functions in PHP can be used with protocols other than IMAP, namely POP3, NNTP and local mailbox access methods.
</para>
				<para>Before PAT will work on your system, you need to make one edit to the file <filename moreinfo="none">index.wml</filename> in the directory <filename moreinfo="none">/home/httpd/alligata/wml/dynamic/complex/pat/</filename> (Linux) or <filename moreinfo="none">/opt/TGLBallex/alligata/wml/dynamic/complex/pat/</filename> (Solaris). In the <literal moreinfo="none">&lt;go/&gt;</literal> tag, insert the name of your e-mail server after <literal moreinfo="none">server=</literal>. For example, if your e-mail server is <filename moreinfo="none">imap.asite.net</filename>, the tag should be as follows:
</para>
				<programlisting format="linespecific">&lt;go href=&quot;view.php3?username=$username&amp;amp;password=$passwo
rd&amp;amp;server=imap.asite.net&quot;/&gt;
</programlisting>
				<para>To view the PAT mail site, select the link &apos;PAT: PHP mail&apos; from the Site Examples index. You will see a login card:
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="12-10&figtype;">
					</imageobject>
					<caption>
						<para>Figure 12.10</para>
					</caption>
				</mediaobject>
				<para>This card is from the file <filename moreinfo="none">index.wml</filename>. Enter your e-mail user name and password and you will be taken to the top of your e-mail inbox:
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="12-11&figtype;">
					</imageobject>
					<caption>
						<para>Figure 12.11</para>
					</caption>
				</mediaobject>
				<para>The inbox shows each message&apos;s number in the list and its subject. Owing to the size limitations of WML files, the inbox is divided into segments of five messages. To view the next five messages in the inbox, follow the hyperlink &apos;NEXT 5&apos; at the bottom of the card.
</para>
				<para>To view a message, select the hyperlinked number preceding it. The message is prefixed by details of the subject, the send date and time, and the sender:
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="12-12&figtype;">
					</imageobject>
					<caption>
						<para>Figure 12.12</para>
					</caption>
				</mediaobject>
				<mediaobject>
					<imageobject>
						<imagedata fileref="12-13&figtype;">
					</imageobject>
					<caption>
						<para>Figure 12.13</para>
					</caption>
				</mediaobject>
				<para>Where a message is longer than 700 characters, it is split into several smaller messages.
</para>
				<para>PAT is composed of several files. These are summarised in Figure 12.14.
</para>
				<table>
					<title>Figure 12.14: Summary of PAT files</title>
					<tgroup cols="2">
						<thead>
							<row>
								<entry>File</entry>
								<entry>Function</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>Main files:</entry>
							</row>
							<row>
								<entry>
									<filename moreinfo="none">index.wml</filename>
								</entry>
								<entry>Contains the login card. Receives the user name and password from the user and invokes <filename moreinfo="none">view.php3</filename>.
</entry>
							</row>
							<row>
								<entry>
									<filename moreinfo="none">view.php3</filename>
								</entry>
								<entry>Invokes <filename moreinfo="none">lib/mailbox.php3</filename> to display the mailbox.
</entry>
							</row>
							<row>
								<entry>
									<filename moreinfo="none">message.php3</filename>
								</entry>
								<entry>Invokes <filename moreinfo="none">lib/mailmessage.php3</filename> to display a message.
</entry>
							</row>
							<row>
								<entry>Library files:
</entry>
							</row>
							<row>
								<entry>
									<filename moreinfo="none">lib/mailbox.php3</filename>
								</entry>
								<entry>Sets up the class <literal moreinfo="none">mailbox</literal>, which defines the contents of a mailbox.
</entry>
							</row>
							<row>
								<entry>
									<filename moreinfo="none">lib/mailmessage.php3</filename>
								</entry>
								<entry>Sets up the class <literal moreinfo="none">mailMessage</literal>, which defines the contents of a message.
</entry>
							</row>
							<row>
								<entry>
									<filename moreinfo="none">lib/mesgretrieve.php3</filename>
								</entry>
								<entry>Prepares messages for WML display.</entry>
							</row>
							<row>
								<entry>
									<filename moreinfo="none">lib/wmlheader.php3</filename>
								</entry>
								<entry>Defines a header for a WML file.
</entry>
							</row>
							<row>
								<entry>
									<filename moreinfo="none">lib/escaper.php3</filename>
								</entry>
								<entry>Converts escape characters.</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
			</section>
		</chapter>
		<chapter>
			<title>13  SMS Messaging </title>
			<para>The Alligata Server enables you to use SMS in three ways:
</para>
			<itemizedlist>
				<listitem>
					<para>To implement dynamic services such as retrieval of information from Web pages, in response to keywords contained in incoming SMS messages from mobile phones.
</para>
				</listitem>
				<listitem>
					<para>To send SMS messages to mobile phones from a personal computer, using HTTP commands.
</para>
				</listitem>
				<listitem>
					<para>To configure WAP phones to use a particular WAP service from a computer workstation.
</para>
				</listitem>
			</itemizedlist>
			<para>Before you can set up SMS keyword services or send SMS messages from a computer, you need to create an SMS Box group and an SMSC group in the configuration file (see Section 9). You must also have a subscription to an SMSC or a connection to a GSM modem, as explained in Section 9.3.2. Some example settings are shown in Figure 13.1. </para>
			<para>Figure 13.1: Example SMS Box and SMSC group configuration settings
</para>
			<programlisting format="linespecific">group = smsbox
bearerbox-host = localhost
sendsms-port = 13013
global-sender = 123
log-file = /alligata/admin/smsbox.log
log-level = 0

group = smsc
smsc = at
modemtype = wavecom
device = /dev/ttyS2</programlisting>
			<section>
				<title>13.1 Implementing SMS Keyword Services
</title>
				<para>Once you have configured an SMS Box group and an SMSC group in the configuration file, you need to create an SMS Service group for each service you want to implement. An example SMS Service group is shown in Figure 13.2. (See Section 9.3.3 for explanations of the configuration variables.)
</para>
				<para>Figure 13.2: Example SMS Service group configuration settings
</para>
				<programlisting format="linespecific">group = sms-service
keyword = proverb
aliases = Proverb;PROVERB;potd;Potd;POTD
url = http://www.awebsite.net/potd.html
prefix = &lt;!--beginprov--&gt;
suffix = &lt;!--endprov--&gt;
split-chars = ;:.
split-suffix = -cont-
header = &quot;Today&apos;s proverb -- &quot;
max-messages = 10</programlisting>
				<para>This group sets up an SMS service that returns a proverb from the Web page <filename moreinfo="none">http://www.awebsite.net/potd.html</filename> when it receives the message &apos;proverb&apos; from a mobile device. From the Web page, it retrieves everything between (but not including) the strings <literal moreinfo="none">&lt;!--beginprov--&gt;</literal> and <literal moreinfo="none">&lt;!--endprov--&gt;</literal>. The content of <filename moreinfo="none">potd.html</filename> could look like this:
</para>
				<programlisting format="linespecific"> &lt;html&gt;
  &lt;head&gt;
        &lt;title&gt;SMS proverb of the day&lt;/title&gt;
  &lt;/head&gt;
  &lt;body bgcolor=&quot;#FFFFFF&quot; text=&quot;#000000&quot;&gt;
   &lt;!--beginprov--&gt;
   A cat in gloves catches no mice.
   &lt;!--endprov--&gt;
  &lt;/body&gt;
 &lt;/html&gt;
</programlisting>
				<para>In this case, a user sending the message &apos;proverb&apos; to the Alligata Server would receive the reply message
</para>
				<screen format="linespecific">Today&apos;s proverb -- A cat in gloves catches no mice.
</screen>
				<para>The Alligata Server does not require the prefix and suffix of the message to be in comments <literal moreinfo="none">&lt;!--...--&gt;</literal>, but bear in mind that if they are not, they will be visible in the Web page if it is viewed from a desktop browser.
</para>
				<para>The maximum length of an SMS message is usually 140 or 160 characters (depending on whether it is in 7-bit or 8-bit format). If the text retrieved by the Alligata Server is longer than this limit, the Alligata Server splits it into several messages. To do this, it uses the variables <literal moreinfo="none">split-chars</literal> and <literal moreinfo="none">split-suffix</literal>. The message is split at an occurrence of one of the characters specified in <literal moreinfo="none">split-chars</literal>, and all sections of the message except the last have the text specified in <literal moreinfo="none">split-suffix</literal> appended to them. The Alligata Server splits the message at the nearest previous occurrence of a split character to the maximum message length. For example, suppose the proverb in <filename moreinfo="none">potd.html</filename> is a particularly long one:
</para>
				<programlisting format="linespecific"> &lt;html&gt;
  &lt;head&gt;
      &lt;title&gt;SMS proverb of the day&lt;/title&gt;
  &lt;/head&gt;
  &lt;body bgcolor=&quot;#FFFFFF&quot; text=&quot;#000000&quot;&gt;
   &lt;!--beginprov--&gt;
   Monday&apos;s child is fair of 
	 face, Tuesday&apos;s child is 
	 full of grace; Wednesday&apos;s 
	 child is full of woe, 
	 Thursday&apos;s child has far 
	 to go; Friday&apos;s child is 
	 loving and giving, Saturday&apos;s 
	 child works hard for its living; 
	 and the child that is born on the 
	 Sabbath day, is fair and wise and 
	 good and gay.
   &lt;!--endprov--&gt;
  &lt;/body&gt;
 &lt;/html&gt;
</programlisting>
				<para>In this instance, the message needs to be split, and the user will probably receive it in three smaller messages: 
</para>
				<informaltable>
					<tgroup cols="2">
						<tbody>
							<row>
								<entry>Message 1:</entry>
								<entry><screen format="linespecific">Today&apos;s proverb -- Monday&apos;s child is fair of face, Tuesday&apos;s child is full of grace; Wednesday&apos;s child is full of woe, Thursday&apos;s child has far to go; -cont.-</screen></entry>
							</row>
							<row>
								<entry>Message 2:</entry>
								<entry><screen format="linespecific">Today&apos;s proverb -- Friday&apos;s child is loving and giving, Saturday&apos;s child works hard for its living; -cont.-</screen></entry>
							</row>
							<row>
								<entry>Message 3:</entry>
								<entry><screen format="linespecific">Today&apos;s proverb -- and the child that is born on the Sabbath day, is fair and wise and good and gay.</screen></entry>
							</row>
						</tbody>
					</tgroup>
				</informaltable>
				<para>The string <literal moreinfo="none">-cont.-</literal> in the first and second messages indicates that they are part of a longer message, more of which is to follow. It is specified using the <literal moreinfo="none">split-suffix</literal> configuration variable.
</para>
				<para>Note that the incoming SMS message must <emphasis role="bold">only</emphasis> contain the keyword, unless the SMS service allows parameters after it. Parameters are discussed in Section 13.1.1.
</para>
				<section>
					<title>13.1.1 SMS Service Parameters
</title>
					<para>The configuration variables <literal moreinfo="none">url, file</literal> and <literal moreinfo="none">text</literal> can include parameters that the Alligata Server substitutes with terms from the incoming message. Each parameter is indicated by a percent character % followed by a letter. The parameters you can use are listed in full in Section 9.3.3.
</para>
					<para>Parameter values should be included in incoming messages after the service keyword, using the following syntax:
</para>
					<para>
						<userinput moreinfo="none">
							<replaceable>keyword parameter#1 parameter#2</replaceable>, etc.
						</userinput>
					</para>
					<para>As an example, suppose your company has created a CGI server application that returns an employee&apos;s salary. You want the Personnel department to be able to gain access to this information from their SMS phones, but no one else. In this case, you could configure the SMS Service group shown in Figure 13.3.
</para>
					<para>Figure 13.3: Example SMS Service group for a salary retrieval application
</para>
					<programlisting format="linespecific">keyword = salary
aliases = Salary;SALARY
url = http://intranet.awebsite.net/cgi/salary?user=%s&amp;password=%s&amp;employee=%r
header = &quot;Salary info -- &quot;</programlisting>
					<para>When the Alligata Server receives an SMS message starting with the keyword &apos;salary&apos; (or one of its aliases), it replaces the first <literal moreinfo="none">%s</literal> in <literal moreinfo="none">url</literal> with the next word in the message after the keyword; replaces the second <literal moreinfo="none">%s</literal> with the next word after that; and replaces the <literal moreinfo="none">%r</literal> with the rest of the message.
</para>
					<para>For example, if the CGI account has the user name <emphasis role="bold">personnel</emphasis> and the password <emphasis role="bold">STARfruit</emphasis>, then a Personnel member can access the salary details of the employee Emma Thompson by sending the Alligata Server the following SMS message:
</para>
					<para>
						<userinput moreinfo="none">
							salary personnel STARfruit emma thompson
						</userinput>
					</para>
					<para>Upon receiving this message, the Alligata Server sends the following HTTP GET request:
</para>
					<para>
						<userinput moreinfo="none">
							 http://intranet.awebsite.net/cgi/salary?user=personnel&amp;
 password=STARfruit&amp;employee=emma+thompson
						</userinput>
					</para>
					<para>When the HTTP reply arrives, the Alligata Server converts it into an SMS message or messages, and sends it back to the Personnel member&apos;s mobile phone.
</para>
				</section>
			</section>
			<section>
				<title>13.2 Sending SMS Messages Using HTTP
</title>
				<para>For every user you want to be able to send SMS messages using HTTP, you need to define a Send SMS User group in the configuration file. An example Send SMS User group is shown in Figure 13.4.
</para>
				<para>Figure 13.4: Example Send SMS User group
</para>
				<programlisting format="linespecific">group = sendsms-user
username = colin
password = AVOcado
user-allow-ip = 10.0.0.5
max-messages = 10
split-chars = .;,
split-suffix = -cont.-
header = &quot;Msg from Colin -- &quot;</programlisting>
				<para>This configuration group allows the user <emphasis role="bold">colin</emphasis> with the password <emphasis role="bold">AVOcado</emphasis> to send SMS messages from the IP address 10.0.0.5. As with SMS keyword services, outgoing messages that are over the maximum length of a single SMS message can be split into several smaller messages, up to the maximum specified in <literal moreinfo="none">max-messages</literal>. The variables <literal moreinfo="none">split-chars, split-suffix</literal> and <literal moreinfo="none">header</literal> work exactly as in SMS Service groups (see Section 13.1).
</para>
				<para>
					<userinput moreinfo="none">http://<replaceable>hostname:port</replaceable>/cgi-bin/sendsms?
username=<replaceable>username</replaceable>&amp;
password=<replaceable>password</replaceable>&amp;
from=<replaceable>sender&apos;s_number</replaceable>&amp;
to=<replaceable>receiver&apos;s_number</replaceable>&amp;
text=<replaceable>message_text</replaceable>
					</userinput>
				</para>
				<para>The elements in bold italic type should be replaced with the relevant information. For example:
</para>
				<para>
					<userinput moreinfo="none">
						http://localhost:13013/cgi-bin/sendsms?username=colin&amp;
password=AVOcado&amp;from=0999666666&amp;to=0898999999&amp;text=
All+sales+staff+return+to+office+immediately
					</userinput>
				</para>
				<para>The URL should contain no carriage returns and no spaces. Spaces in the message should be represented by plus signs +. 
</para>
				<section>
					<title>13.2.1 User Data Headers (<literal moreinfo="none">udh</literal> parameter)
</title>
					<para>An SMS message can include a <emphasis role="bold">user data header (UDH)</emphasis> that contains non-textual information for use by a mobile phone. For example, a UDH can tell a phone to handle the main body of the message in a particular way, such as storing it as a ring tone or as a graphical image to appear when the phone is switched on. For information on the format of UDH messages for a particular phone, consult the phone&apos;s documentation or visit the manufacturer&apos;s Web site.
</para>
					<para>When you send an SMS message from a computer workstation using HTTP, you can include a UDH by using the optional <literal moreinfo="none">udh</literal> parameter. For example:
</para>
					<para>
						<userinput moreinfo="none">
							http://localhost:13013/cgi-bin/sendsms?username=colin&amp;
password=AVOcado&amp;from=0999666666&amp;to=0898999999&amp;text=
%52%62%1a%bb%31%0d%21%84%77%ba%f7%f2&amp;udh=%31%a7%99%f3%80%db
						</userinput>
					</para>
					<para>All non-alphanumeric characters in the message text and the UDH value must be in hexadecimal format and preceded by a percent sign %.
 </para>
				</section>
				<section>
					<title>13.2.2  <literal moreinfo="none">smsc</literal> Parameter
</title>
					<para>You can use the optional smsc parameter to force an SMS message to be sent via a particular SMSC. The smsc parameter should have the value set by the <literal moreinfo="none">smsc-id</literal> variable in the relevant SMSC group of the configuration file (see Section 9.3.2). For example:
</para>
					<para>
						<userinput moreinfo="none">
							http://localhost:13013/cgi-bin/sendsms?username=colin&amp;
password=AVOcado&amp;from=0999666666&amp;to=0898999999&amp;text=
All+sales+staff+return+to+office+immediately&amp;smsc=smsc5

						</userinput>
					</para>
				</section>
				<section>
					<title>13.2.3 SMS Messaging Using HTML Forms
</title>
					<para>Typing complex URLs into a browser&apos;s &apos;Location&apos; box can be tedious, and if you expect to be sending a lot of SMS messages, it is worth creating an HTML form for the task. Use the HTTP GET method, and define variables in HTML input objects. Constant values can be embedded in hidden objects. Variable names should be specified in the name attributes of the relevant elements, and the corresponding values in <literal moreinfo="none">value</literal> attributes. For example:
</para>
					<programlisting format="linespecific"> &lt;html&gt;
 &lt;head&gt;
  &lt;title&gt;SMS Message Sender&lt;/title&gt;
 &lt;/head&gt;
 &lt;body bgcolor=&quot;#FFFFFF&quot; text=&quot;#000000&quot;&gt;
  &lt;h1&gt;SMS Message Sender&lt;/h1&gt;
  &lt;form name=&quot;sendsms&quot; method=&quot;get&quot; 
	    action=&quot;http://localhost:13013/cgi-bin/sendsms&quot;&gt;
   &lt;input type=&quot;hidden&quot; name=&quot;username&quot; value=&quot;tester&quot;&gt;
   &lt;input type=&quot;hidden&quot; name=&quot;password&quot; value=&quot;foobar&quot;&gt;
   &lt;input type=&quot;hidden&quot; name=&quot;from&quot; value=&quot;0999666666&quot;&gt;
   &lt;p&gt;
    Telephone number:&lt;br&gt;
    &lt;input type=&quot;text&quot; size=&quot;30&quot; name=&quot;to&quot;&gt;
   &lt;/p&gt;
   &lt;p&gt;
    Message:&lt;br&gt;
    &lt;textarea cols=&quot;25&quot; rows=&quot;5&quot; name=&quot;text&quot;&gt;
&lt;/textarea&gt;
   &lt;/p&gt;
   &lt;p&gt;
    User Data Header (optional):&lt;br&gt;
    &lt;input type=&quot;text&quot; size=&quot;30&quot; name=&quot;udh&quot;&gt;
   &lt;/p&gt;
   &lt;input type=&quot;submit&quot; value=&quot;Send Message&quot;&gt;
   &lt;br&gt;
  &lt;/form&gt;
 &lt;/body&gt;
 &lt;/html&gt;
</programlisting>
					<para>The appearance of this form in a Web browser is shown in Figure 13.5.
</para>
					<mediaobject>
						<imageobject>
							<imagedata fileref="13-5&figtype;">
						</imageobject>
						<caption>
							<para>Figure 13.5: Example HTML form for SMS messaging
</para>
						</caption>
					</mediaobject>
				</section>
			</section>
			<section>
				<title>13.3 Over-the-air (OTA) Configuration of WAP Client Devices Using SMS
</title>
				<para>Changing the settings for a WAP service provider from a mobile device can be laborious, with up to a dozen variables to alter on each device. If you are a system administrator needing to configure all your company&apos;s WAP phones to the same service, the process becomes particularly time-consuming. However, the Alligata Server allows you to automate device configuration by defining automatic WAP service settings in the configuration file. By sending a single SMS-format message to each phone from a computer workstation, you can add a whole configuration to its settings. It is also possible for the user of a client device to invoke the OTA configuration themselves. This enables a user to add WAP services to their mobile phone with a minimum of effort.
</para>
				<para>The Alligata Server&apos;s OTA configuration feature is currently known to work on the Nokia 7110, Nokia 6210 and Nokia 9110i phones.
</para>
				<para>In order to implement OTA configuration, you need to set up three configuration groups in the configuration file:
</para>
				<itemizedlist>
					<listitem>
						<para>an OTA Configuration group, containing the settings to be sent to the client device
</para>
					</listitem>
					<listitem>
						<para>a Send SMS User group, setting up a user account for sending of OTA messages 
</para>
					</listitem>
					<listitem>
						<para>an SMS Service group, pointing to the Alligata Server&apos;s <literal moreinfo="none">sendota</literal> CGI application
</para>
					</listitem>
				</itemizedlist>
				<para>For details of configuration groups and variables, see Section 9.
</para>
				<para>An example set of configuration groups for OTA configuration is shown in Figure 13.6.
</para>
<FormalPara>
<title>To configure a WAP client device over the air (system administrator):</title>
<Para>
				<itemizedlist>
					<listitem>
						<para>Send a message to the Alligata Server via HTTP using the following syntax:
</para>
						<para>
							<userinput moreinfo="none">
http://<replaceable>hostname:port</replaceable>/cgi-bin/sendota?
username=<replaceable>username</replaceable>&amp;password=<replaceable>password</replaceable>&amp;phonenumber=<replaceable>destination_phone_number</replaceable>
							</userinput>
						</para>
						<para>For example:
</para>
						<para>
							<userinput moreinfo="none">
								http://localhost:13013/cgi-bin/sendota?username=otauser&amp;
password=foo&amp;phonenumber=449999123456

							</userinput>
						</para>
						<para>The client device will receive a message containing the appropriate configuration information.
</para>
					</listitem>
				</itemizedlist>
</Para>
</FormalPara>
<FormalPara>
					<title>To configure a WAP client device over the air (client):
</title>
<Para>

				<orderedlist inheritnum="ignore" continuation="restarts">
					<listitem>
						<para>Send an SMS message to the Alligata Server&apos;s telephone number consisting of the keyword for the OTA configuration service. For example, for the configuration in Figure 13.6:
</para>
						<para>
							<userinput moreinfo="none">
								ota
							</userinput>
						</para>
					</listitem>
					<listitem>
						<para>After a while, you will receive an SMS message from the Alligata Server containing the new settings. How long this message takes to arrive depends on the capabilities and load of your SMSC.
</para>
					</listitem>
					<listitem>
						<para>Use the relevant feature of your device to add the configuration settings to your list of WAP providers and, if required, make the new service your default one.
</para>
					</listitem>
				</orderedlist>
</Para>
</FormalPara>

				<para>Figure 13.6: Example settings for OTA configuration
</para>
				<programlisting format="linespecific">group = sms-service
keyword = ota
# In one line!
url =
&quot;http://localhost:13013/cgi-bin/sendota?
  username=otauser&amp;password=GRAPefruit&amp;phonenumber=%p&quot;

group = otaconfig
location = &quot;http://www.asite.net&quot;
service = Company Home
ipaddress = 100.100.100.100
phonenumber = 01487772268
bearer = data
calltype = analogue
connection = cont
pppsecurity = off
authentication = normal
login = phoneuser
secret = barfoo

group = sendsms-user
username = otauser
password = GRAPefruit
user-deny-ip = &quot;&quot;
user-allow-ip = &quot;&quot;
max-messages = 2
concatenation = 1</programlisting>
			</section>
		</chapter>
	</part>
	<appendix>
		<title>Appendix: Troubleshooting Guide</title>
		<para>If you encounter any problems while running the Alligata Server, in the first instance you should check the log files for information. By default, the log files are held in the directory <filename moreinfo="none">/var/log/alligata</filename>. You can view the log files by using the UNIX <literal moreinfo="none">less</literal> command (for example, <userinput moreinfo="none">less /var/log/alligata/bearerbox.log</userinput>). To watch a log file update while the Alligata Server is running, press SHIFT+F from within <literal moreinfo="none">less</literal>. 
</para>
		<informaltable>
			<tgroup cols="3">
				<thead>
					<row>
						<entry>Problem</entry>
						<entry>Possible Cause</entry>
						<entry>Solution
</entry>
					</row>
				</thead>
				<tbody>
					<row>
						<entry>The Bearer Box will not start.</entry>
						<entry>The configuration file contains errors.</entry>
						<entry>Read Section 9 for information on how to edit the configuration file.

Note that when you first install the Alligata Server, it will not be connected to an SMSC or a GSM modem. Therefore, if the configuration file contains any SMS variables, the Alligata Server may not start.
</entry>
					</row>
					<row>
						<entry>The WAP Box will not start.</entry>
						<entry>There are errors in the WAP Box configuration group.</entry>
						<entry>Read Section 9 for information on how to edit the configuration file.</entry>
					</row>
					<row>
						<entry morerows="1">The SMS Box will not start.</entry>
						<entry>Your computer is not connected to an SMSC or a GSM modem.</entry>
						<entry>If you are subscribed to an SMSC, check that you are correctly linked to it and that you have configured the SMS Box and SMSC configuration groups properly (see Section 9).

If you are using a GSM modem, check that it is correctly connected to the computer and that the SMS Box and SMSC configuration groups are properly configured.
</entry>
					</row>
					<row>
						<entry>There are errors in the SMS Box or SMSC configuration groups.</entry>
						<entry>Read Section 9 for information on how to edit the configuration file.</entry>
					</row>
					<row>
						<entry morerows="1">The Alligata Server example sites cannot be viewed from a WAP client device.</entry>
						<entry>The example sites have not been installed.</entry>
						<entry>Rerun the installation program and install the example sites. (You do not need to reintall the Alligata Server.) See Sections 4 and 5 for installation instructions.</entry>
					</row>
					<row>
						<entry>There is no HTTP server running on the same computer as the example sites.</entry>
						<entry>Start your Web server and ensure that the example sites are in the correct directory for the server to find them (for example, in Linux, Apache looked by default in the directory <filename moreinfo="none">/home/httpd</filename>. See Section 12 for instructions on viewing the example sites).

If you have not installed a Web server, you can install the Apache server by rerunning the Alligata Server installation program and selecting the &apos;Apache Web server&apos; option. (You do not need to reinstall the whole of the Alligata Server.) See Sections 4 and 5 for installation instructions.
</entry>
					</row>
					<row>
						<entry>The message &apos;[OK]&apos; was displayed when each Alligata Server box was started, but the Alligata Server is not responding to any WAP or SMS requests.
</entry>
						<entry>The Alligata Server may have been forced to close down by an error.</entry>
						<entry>Check the Alligata Server log files for information about whatever caused the program to close down.</entry>
					</row>
					<row>
						<entry>When the Bearer Box was instructed to start, the message &apos;Could not connect to the port&apos; was displayed.</entry>
						<entry>The Bearer Box is already running.</entry>
						<entry><para>At the Linux command prompt, type<userinput moreinfo="none">
									ps -ef | grep box
								</userinput></para><para>This will output a list that includes all Alligata Server processes. If any of the processes are named &apos;bearerbox&apos;, then the Bearer Box is already running. </para></entry>
					</row>
					<row>
						<entry morerows="1">Outgoing SMS messages are not being sent by the Bearer Box.</entry>
						<entry>The connection to your SMSC or GSM modem is faulty.</entry>
						<entry>Check the connection to your SMS Centre or GSM modem. Ensure that the SMS Box and SMSC groups in the configuration file are properly set up.</entry>
					</row>
					<row>
						<entry>An SMS Service group is misconfigured.</entry>
						<entry>Check in the configuration file that the relevant SMS Service group is properly configured. A common problem is that the <literal moreinfo="none">max-messages</literal> variable is set too loiw. If an outgoing message needs splitting into more messages than allowed by max-messages, not all the messages will be sent.
</entry>
					</row>
					<row>
						<entry>Over-the-air (OTA) SMS configuration messages are not reaching the target mobile phone.</entry>
						<entry>The variable <literal moreinfo="none">max-messages</literal> in the OTA configuration group is set too low in the configuration file. (OTA configuration messages are usually too long to fit in a single SMS message.)</entry>
						<entry>Set the variable <literal moreinfo="none">max-messages</literal> in the OTA configuration group to a value of 2 or higher.</entry>
					</row>
				</tbody>
			</tgroup>
		</informaltable>
	</appendix>
</book>
