1.1 The Alligata Server Package

Your Alligata Server package contains:

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

• A booklet, Your Pocket Guide to the Mobile Internet.

• This Alligata Server User Manual.

• An Alligata Server Quick Reference Guide.

2.1 Linux Version

2.2 Solaris Version

2.3 Optional Software Included with the Alligata Server

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:

• Apache Web server

• PHP scripting language

• Common Gateway Interface (CGI), HTML parser, HTML tables and WML modules for the Perl scripting language

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.

3.1 What is the Alligata Server?

The Alligata Server is two applications in one: a WAP gateway and an SMS server.

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's employees' or clients' 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 'approved' by a network operator or an ISP.

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.

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.

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 www.kannel.org.

3.2 The Alligata Server, WAP and SMS

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 Your Pocket Guide to the Mobile Internet, 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.

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'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's settings to the new gateway, and reconnect to the Mobile Internet.

The conceptual model into which the Alligata Server fits is shown in Figure 3.1.

A signal sent by a mobile device is picked up by one of a network operator'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's SMS Centre (SMSC). The SMSC's main job is to hold pending SMS messages for recipients whose phones are turned off or otherwise inaccessible.

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.

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.

The Alligata Server'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'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.

3.3 Inside the Alligata Server

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.

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.

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 Your Pocket Guide to the Mobile Internet 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.

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.

8.1 Starting the Alligata Server

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.

To start the Alligata Server:

8.2 Administering the Alligata Server

Shutting down an Alligata Server box

There are two methods of shutting down an Alligata Server box.

To shut down an Alligata Server box:

9.1 Core Configuration Variables (Core group)

The Core group provides general configuration information for the Alligata Server. This information is used by the Bearer Box.

9.2 WAP Configuration Variables (WAP Box group)

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.

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

If you are not using the Alligata Server for WAP services, then no WAP Box group is necessary.

9.3 SMS Configuration Variables (SMS Box, SMSC, SMS Service and Send SMS User groups)

9.4 Over-the-air Configuration Variables (OTA Configuration Group)

The OTA Configuration group sets the variables for over-the-air configuration of WAP client devices.

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.

11.1 Content and Tags

To begin with, here is some sample WML: the file logo.wml from the example site 'Static Simple' 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 'Static Simple' from the 'Site Examples' menu (a full guide to the example sites is provided in Section 12):

<?xml version="1.0"?>
 <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"   
     "http://www.wapforum.org/DTD/wml_1.1.xml">
 <wml>
    <card id="foo" name="bar" title="Static WML"
		    newcontext="true">
      <p>
      <img src="3glab.wbmp" alt="3G Lab Logo"  align="middle"/>
      <br/>
      This is static <big>WML</big> text.
   </p>
  </card>
 </wml>

This file, like all WML documents, holds two main types of information: content and tags.

Content is generally textual information to be displayed on the client's microbrowser. It is encoded as plain text using the Unicode 2.0 character set. The example file's content is the sentence 'This is static WML text'.

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 < and greater than > symbols, which denote the start and end of tags). Such characters are represented by entity references which begin with an ampersand &, and end with a semicolon ;. Some of the most common entity references in WML are:

Tags are the pieces of information held within angled brackets < >. 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.

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.

In the example file, you can see that the letters 'WML' have a <big> tag before them, and a </big> 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:

This is static WML text.

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 <img alt="3G Lab Logo" src="3glab.wbmp" align="middle"/>. This tag tells the browser to display the image file 3glab.wbmp 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.

11.2 Elements and Attributes

WML tags, like HTML tags, contain information about elements and attributes.

An element is a structural unit of a WML document: every tag begins with an element indicator. In the example file (see Section 11.1), wml, card, p, img and big are all elements.

An attribute provides information about a specific occurrence of an element. Attributes are included in an element's start tag, after the element indicator. In the example file in Section 11.1, the img element has several attributes associated with it. The attribute src="3glab.wbmp" tells the microbrowser to display the image 3glab.wbmp; alt="3G Lab Logo" tells it that if, for any reason, it can't display the image, it should display the text '3G Lab Logo' instead; and align="middle" tells the microbrowser to centre the image vertically on the card.

11.3 Cards and Decks

Whereas HTML documents are organised into 'pages', WML documents are organised into units called 'cards' and 'decks'. 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.

A card contains a 'screen's worth' 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's navigation facilities enable you to jump from one card in a deck to another.

Cards are marked up using the card element. There is no deck element - a deck comprises everything inside a file's wml element. See Section 11.5 for more information on the wml element.

11.4 XML Validation Tags

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN" 
    "http://www.wapforum.org/DTD/wml_1.1.xml">

The tag <?xml version="1.0"?> 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.

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

These two tags are not WML tags, but validation tags instructing the browser to parse the rest of the file as WML.

11.5 The wml Element

The top-level element in every WML deck is wml. The <wml> tag announces to the browser that everything following it should be parsed as WML data, up to the </wml> tag.

Therefore, the first tag in a deck (after the validation tags) should be <wml>, and the last tag in the deck should be </wml>.

11.6 Paragraphs

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 <p> tag must have a corresponding </p> closing tag. For example:

<card>
  <p>This card is divided into paragraphs. This is the first paragraph.</p>
  <p>This is the second paragraph. It is also the last.</p>
</card>

By default, text between <p>...</p> tags is left-aligned. You can centre- or right-align it using the align attribute with the value center or right respectively. For example:

<p align="right">This paragraph is right-aligned.</p>

11.7 Hyperlinks

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.

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.

The hyperlink element in WML is a (as in HTML, this stands for 'anchor'). It takes an attribute href, which indicates the destination of the link. For example:

Great oaks from <a 
  href="http://www.littleacorns.com">little acorns</a> grow.

Here, the words 'little acorns' 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:

Great oaks from little acorns grow.

To create hyperlinks between cards in the same deck, give each card a unique id attribute, and refer to that id in the href attribute of hyperlinks to it. In the href attribute, precede the destination card's name with a hash #: this indicates that the link is to a card rather than to a file.

The example file below contains two cards, linked by referring to one another's id attributes.

<?xml version="1.0"?>
 <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
     "http://www.wapforum.org/DTD/wml_1.1.xml">
 <wml>
    <card id="card1">
   <p>
        This is a WML card.
      </p>
   <p>
        <a href="#card2">Next card...</a>
      </p>
    </card>
    <card id="card2">
   <p>
        And this is another.
      </p>
   <p>
        <a href="#card1">Previous card...</a>
      </p>
    </card>
 </wml>

You can also link to a specific card in another deck by appending a hash # and the card's id to the URL. For example:

<a href="anotherfile.wml#acertaincard">Go to that card</a>

Here, the link 'Go to that card' takes the user to the card acertaincard in the deck anotherfile.wml.

11.8 Tasks (do Element)

The do 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 do task depends on the device manufacturer's implementation of WML. The general idea is that a do function should be independent of where the user has scrolled to on the page, which hyperlink is currently highlighted, and so on. Typically, a do function will be activated by a physical button on the client device.

A do 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 'tasks':

Here is an example do statement:

 <do type="prev" label="Go Back" name="goback">
  <prev/>
 </do>

This do element includes three attributes:

• The type attribute gives the client browser an indication of what category of tasks the current task belongs to. Possible values include "accept", "prev", "help", "reset", "options" and "delete". 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 do element of the prev type in the bottom right corner of the screen and associates it with the right navigation button.

• The label 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 do type="prev" function as 'Back', regardless of the content of the label attribute.

• The name attribute gives the do function an identifier by which scripting languages such as WMLScript can refer to it.

Suppose a client device associates do type="prev" with its right navigation button, and accepts a WML-defined label attribute. On such a device, our example do function might appear as shown in the bottom right corner of Figure 11.1.

11.9 Events

WML allows you to specify automatic actions in a client device that are precipitated by particular 'events'. An 'event' must be associated with a particular element in a WML file - either card, wml or option. The response to an event is defined by the onevent element, which must occur within the element to which it relates. The type of event to respond to is indicated in the type attribute of the onevent element.

Possible values for the type attribute are as shown in Figure 11.2.

The action undertaken by the client device in response to an event must be defined by one of the task elements go, prev, noop or refresh. The task element must be situated within the onevent element.

For example:

 <card>
  <onevent type="onenterbackward">
   <go href="backwardpeople.wml"/>
  </onevent>
  You didn&apos;t enter this card backwards.
 </card>

If a user arrives at this card via a hyperlink or a go task, they will see the message

You didn't enter this card backwards.

However, if the user arrives at the card via a prev task, they will be redirected to the file backwardpeople.wml.

There is another way of handling an event that is shorter, but less flexible. Instead of using the onevent element, you can specify an action in the form of an attribute in the relevant card or wml element. For example, the sample WML above could be rewritten as follows, and would do exactly the same thing:

 <card onenterbackward="backwardpeople.wml">
     You didn&apos;t enter this card backwards.
 </card>

Note that the only kind of action possible using this method is a jump to a URL (in this case, backwardpeople.wml). This is equivalent to the go action. If you want to perform a prev, a noop or a refresh action, you have to use the longer method.

11.10 Templates

Suppose you create a WML deck consisting of five cards, and you want a prev task on every card except the first. Rather than repeating the same do 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 template element to specify a task to appear automatically on every card you want.

Here is an example of a WML file that uses a template element:

 <?xml version="1.0"?>
 <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
     "http://www.wapforum.org/DTD/wml_1.1.xml">
 
 <wml>
 
  <template>
   <do type="prev">
    <prev/>
   </do>
  </template>

  <card id="card1">
   <do type="prev">
    <noop/>
      </do>
      Love speaks, even when the lips are closed.
      <br/>
      <a href="#card2">
    Next proverb...
      </a>
    </card>

    <card id="card2">
   It is an ill dog that deserves not a crust. 
   <br/>
   <a href="#card3">
         Next proverb...
      </a>
    </card>

    <card id="card3">
      He who wants a mule without fault, must walk on foot.
      <br/>
      <a href="#card4">
        Next proverb...
      </a>
    </card>

    <card id="card4">
   Never cast a clout till May be out.
      <br/>
      <a href="#card5">
       Next proverb...
      </a>
    </card>

    <card id="card5">
   Scabby donkeys scent each other over nine hills.
   <br/>
  </card>

 </wml>

When this file is viewed on a WAP microbrowser, every card except the first one has a 'Back' link on it - even though, in the WML source, none of them contains a prev task. The explanation for this is that the prev task is held in the template element at the beginning of the file, and is applied automatically to every card in the deck, except the first.

The reason there is no 'Back' link on the first card is that the first card contains a noop task. Because a task defined in a card always overrides a default task of the same type as specified in the template, and because noop does nothing, this card displays nothing in place of a 'Back' link.

11.11 Variables

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 'label' 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't be written into the program itself.

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.

There are a number of ways in which you can specify variables. One of the most useful is via the input element, which allows the user to enter information into the client device's interface.

Here is a very simple WML deck that writes a 'proverb' based on terms the user enters through the input element:

 <?xml version="1.0"?>
 <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
     "http://www.wapforum.org/DTD/wml_1.1.xml">
 <wml>
  <card id="card1" title="Proverb Wizard">
      Name an animal:
      <input name="animal"/>
      Name a vegetable:
      <input name="vegetable"/>
       <a href="#card2">
     View proverb...
       </a>
  </card>

  <card id="card2" title="Your proverb">
   <do type="accept" label="Another?">
    <go href="#card1"/>
   </do>
   A small $(animal) may eat a large $(vegetable).
  </card>

 </wml>

When this file is opened on a microbrowser, the following card will be displayed:

As can be seen, there are two input fields. These are created by the tags <input name="animal"/> and <input name="vegetable"/> in the WML source. The name attributes tell the browser to create the variables animal and vegetable respectively, based on what the user types into each field.

To select a horse for the animal and a radish for the vegetable, enter horse into the first field and radish into the second field. (The actual mechanism for entering text will depend on your microbrowser. For example, it may present you with an Edit option that you activate by pressing one of the phone's navigation buttons.)

The microbrowser display will now be as in Figure 11.4.

Now, activate the 'View proverb...' link. A new card is loaded, showing a proverb based on the terms you entered in the first card (see Figure 11.5).

In the source WML you can see how the terms entered in the first card were passed to the second card. The variables animal and vegetable were set in the tags <input name="animal"/> and <input name="vegetable"/>.

The source text in the second card looks like this:

A small $(animal) may eat a large $(vegetable).

When the browser encounters a dollar symbol $, it knows that what follows in parentheses is a variable. So instead of displaying '(animal)' it looks for the variable called animal and displays its value - in this example, the string 'horse'. It does the same with the variable vegetable, substituting its name with 'radish'.

(If you want to display a dollar symbol on the screen, use two dollar symbols $$ in your WML file.)

11.12 Timers

You can incorporate a timer into a WML card or deck using the timer element. When a timer runs out, an action is performed as specified in the ontimer event handler. See Section 11.9 for more details about event handling.

timer takes a value attribute, specifying how long the timer should run for. The value is expressed in tenths of a second.

Here is an example timer implementation:

 <?xml version="1.0"?>
 <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
     "http://www.wapforum.org/DTD/wml_1.1.xml">
 <wml>
  <card id="wait">
   <onevent type="ontimer">
    <go href="#thankyou"/>
   </onevent>
   <timer value="40"/>
   <p>
   Please wait.
   </p>
  </card>
  <card id="thankyou">
   <p>
   Thank you for waiting.
   </p>
  </card>
 </wml>

When you first load this file you will see the message 'Please wait.' After about four seconds, the first card will time out and the second card will appear, showing the message 'Thank you for waiting.'

11.13 Images

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.

To embed an image in a file, use the img element with some or all of the attributes shown in Figure 11.6. For example:

<img src="3glab.wbmp" alt="3G Lab Logo" align="middle"/>

     <p align="center">
     <img src="image.wbmp" 
		   alt="An image"/>
     </p>

12.1 Example Site 1: Static WML (Simple)

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 'Static Simple' or 'Static Complex' from the Site Examples index.

The 'Static Simple' is discussed in Section 11.1. It is a single WML card that displays the message, 'This is static WML text.'

12.2 Example Site 2: Static WML (Complex)

If you select 'Static Complex' from the Site Examples index page, you will be presented with the logo shown in Figure 12.3.

After a few seconds the logo will disappear, to be replaced by a set of links (see Figure 12.4).

If you follow a link, you will be taken to the corresponding piece of information. You can also use the link 'ACME home' to take you back to the home deck. (Since this is a prev task, it may simply be labelled 'Back' on your device's display - see Section 11.8.)

If you select 'ACME Vacancies', the card in Figure 12.5 will appear on your screen.

If you select a link from this card, you will be taken to information about the relevant post. For example, 'Head of Marketing' will show you the card in Figure 12.6.

From here you can use the 'ACME Vacancies' link to return to the list of jobs. (Again, this a prev task, so your device may just label it 'Back'.) To go right back to the home deck, keep navigating backwards in the same way.

From the home deck, you can navigate through any series of cards in the way just described.

The first file that the microbrowser loaded when it visited the site Static Complex is called index.wml. Its source is as follows:

 <?xml version="1.0"?>
 <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
     "http://www.wapforum.org/DTD/wml_1.1.xml">
 <wml>
  <card id="logo" ontimer="#menu" title="Welcome to ACME" newcontext="true">
      <timer value="30"/>
   <img alt="ACME corp" src="acmelogo.wbmp" align="middle"/>
  </card>
  <card id="menu" name="menu" title="the ACME menu">
   <do type="prev" label="ACME home">
    <prev/>
   </do>
   <a href="info.wml">
    What is ACME?
   </a>
   <br/>
   <a href="contact.wml">
    Contacting ACME
   </a>
   <br/>
   <a href="employ.wml">
    ACME Vacancies
   </a>
   <br/>
   <a href="wpaper.wml">
    ACME White Paper
   </a>
  </card>
 </wml>

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's limited memory.

The first two tags in the file are the XML validation tags:

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
    "http://www.wapforum.org/DTD/wml_1.1.xml">

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

Next comes the deck-level <wml> tag. Following that is the first card in the deck:

 <card id="logo" ontimer="#menu" title="Welcome to ACME"    
 newcontext="true">
  <timer value="30"/>
  <img alt="ACME corp" src="acmelogo.wbmp" align="middle"/>
 </card>

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.

Here is a description of the card item by item.

First, you will see that the card element contains four attributes:

• id="logo" gives the card a name by which other cards or decks can refer to it.

• ontimer="#menu" tells the microbrowser that when the timer contained in the card runs out, it should load the card menu. The timer is defined in the timer element.

• title="Welcome to ACME" defines a title to appear at the top of the card in the microbrowser.

• newcontext="true" instructs the microbrowser to reset its 'context' when the card is loaded. A microbrowser's context consists of information it holds in its memory about recent events. Specifically, newcontext="true" removes all WML variables, clears the microbrowser's navigation history, and resets other information in the microbrower to its default value. precisely what information this is depends on the microbrowser.

The next element is timer. It has the attribute value="30", which tells the microbrowser to wait about three seconds before performing the action specified in the card's ontimer attribute.

Note that, because timer is an empty element - that is, one without a closing tag - its tag must end in a forward slash /.

The remaining element in the card is img, with three attributes:

• alt="ACME corp" tells the microbrowser to display the text 'ACME corp' if it cannot load the image for any reason.

• src="acmelogo.wbmp" tells the microbrowser that the image to be displayed is the file acmelogo.wbmp.

• align="middle" tells the microbrowser to centre the image vertically, in relation to the surrounding text.

img, like timer, is an empty element, so the tag needs a forward slash / at the end of it.

Finally, the card ends with a </card> tag.

The second card in the deck looks like this:

 <card id="menu" name="menu" title="The ACME Menu">
  <do type="prev" label="ACME home">
   <prev/>
  </do>
  <a href="info.wml">
   What is ACME?
  </a>
  <br/>
  <a href="contact.wml">
   Contacting ACME
  </a>
  <br/>
  <a href="employ.wml">
   ACME Vacancies
  </a>
  <br/>
  <a href="wpaper.wml">
   ACME White Paper
  </a>
 </card>

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.

We selected the hyperlink 'ACME Vacancies' from this menu. As you can see from the source WML, that link goes to the file employ.wml, which looks like this:

 <?xml version="1.0"?>
 <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
     "http://www.wapforum.org/DTD/wml_1.1.xml">

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

   <card id="job1" title="Job: Systems Analyst">
    <do type="prev" label="ACME Vacancies">
     <prev/>
    </do>
    <p>
    A position has opened for a Systems Analyst. 
		Please send us your CV if you think you are 
		suitably skilled in Systems Analysis.
    </p>
   </card>
   <card id="job2" title="Job: Marketing Head">
    <do type="prev" label="ACME Vacancies">
     <prev/>
    </do>
    <p>
    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&apos; 
		experience in a marketing environment. 
		Must be a people person.
    </p>
   </card>
   <card id="job3" title="Job: Chief Admin">
    <do type="prev" label="ACME Vacancies">
     <prev/>
    </do>
    <p>
    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.
    </p>
   </card>
  </wml>

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 'Head of Marketing' was chosen, which goes to the card job2.

Note that, once again, every card in the deck has a <prev/> link to return to the previous card.

12.3 Example Site 3: Perl System Resource Monitor

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.

One language already widely used for Web scripting is the Practical Extraction and Report Language (Perl). Perl's powerful text processing capabilities make it equally suitable for WAP scripting.

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, http://www.awapsite.net/anyscript.pl could execute the Perl script anyscript.pl on the WAP site http://www.awapsite.net/. (Of course, the script's output needs to be in WML, in order to display on a WAP microbrowser.)

To download Perl and to find out more about it, visit www.perl.com. Many books are also available on Perl programming.

The Alligata Server'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.

To view the Alligata Server example Perl site, select 'Sysinfo Perl' from the Site Examples index. You will see the card in Figure 12.7.

From top to bottom, this information is as follows:

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

The WML generated by the Perl script for this file is as follows:

 <?xml version="1.0"?>
 <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
     "http://www.wapforum.org/DTD/wml_1.1.xml">
 <wml>
  <template>
   <do type="prev" name="back" label="Back">
    <prev/>
   </do>
  </template>
  <card id="main" title="apc.acompany.net" newcontext="true">
   <p>
   <a href="#users">
    Linux-2.2.16 19 users
   </a>
   </p>
   <p>
    Up: 11 Days 7h54m
   </p>
   <p>
    CPU: 24%  AVG: 1.18
   </p>
   <p>
    RAM: 98%  SWP: 8%
   </p>
  </card>
  <card id="users" title="users logged in">
   <p>
    atrull fturton ymuller
   </p>
  </card>
 </wml>
12.4

12.4 Example Site 4: PHP System Resource Monitor

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.

PHP is an open source programming language. You can learn about it at the PHP Web site at www.php.net. This site includes a complete online PHP manual, a Quick Reference Guide and a Frequently Asked Questions page.

The Alligata Server package includes two example PHP sites. The first retrieves system information from its host machine's operating system using the uptime and free Linux/UNIX commands and the PHP fsockopen function.

To view the PHP System Resource Monitor, select the link 'Sysinfo PHP' from the Site Examples index.

You will see the site's main index card (see Figure 12.9).

Follow any of the three links, 'Load/Uptime', 'Memory' or 'Port Status', 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 'Load/Uptime' card is explained in the right column; the information in the 'Memory' and the 'Port Status' cards is self-explanatory.

Load/Uptime
--
time: 2:40pm The time according to the system'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's average load over the last minute
load (5): 2.53 The system's average load over the last 5 minutes
load (15): 2.08 The system'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

The PHP-generated information is all held in a single WML deck:

 <?xml version="1.0"?>
 <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
     "http://www.wapforum.org/DTD/wml_1.1.xml">
 <wml>
  <head>
  <meta http-equiv="Cache-Control" content="max-age=0" forua="true"/>
  </head>

  <template>
   <do type="accept">
    <go href="#"/>
   </do>
   <do type="prev" name="back" label="Back">
    <prev/>
   </do>
  </template>

  <card id="init" newcontext="true">
   <p align="center">
   <b>System Resource Monitor:</b>
   </p>
   <p>
   <a href="#up">Load/Uptime</a>
   <br/>
   <a href="#mem">Memory</a>
   <br/>
   <a href="#ports">Port Status</a>
   <br/>
   </p>
  </card>

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

  <card id="mem">
   <p align="center">
   <b>Memory</b>
   <br/>
   --
   </p>
   <p align="left">
   total: 192704
   <br/>
   used: 189652
   <br/>
   free: 3052
   <br/>
   shared: 117292
   <br/>
   buffers: 30056
   <br/>
   cached: 28444
   <br/>
   </p>
  </card>

  <card id="ports">
   <p align="center">
   <b>Port Status</b>
   <br/>
   --
   </p>
   <p align="left">
   21: open
   <br/>
   22: open
   <br/>
   23: open
   <br/>
   53: closed
   <br/>
   80: open
   <br/>
   </p>
  </card>
 </wml>

12.5 Example Site 5: 'PAT' PHP Mail

The Alligata Server's second example PHP site, 'PAT', enables you to read your e-mail from a WAP client device. It uses PHP'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.

Before PAT will work on your system, you need to make one edit to the file index.wml in the directory /home/httpd/alligata/wml/dynamic/complex/pat/ (Linux) or /opt/TGLBallex/alligata/wml/dynamic/complex/pat/ (Solaris). In the <go/> tag, insert the name of your e-mail server after server=. For example, if your e-mail server is imap.asite.net, the tag should be as follows:

<go href="view.php3?username=$username&amp;password=$passwo
rd&amp;server=imap.asite.net"/>

To view the PAT mail site, select the link 'PAT: PHP mail' from the Site Examples index. You will see a login card:

This card is from the file index.wml. Enter your e-mail user name and password and you will be taken to the top of your e-mail inbox:

The inbox shows each message'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 'NEXT 5' at the bottom of the card.

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:

Where a message is longer than 700 characters, it is split into several smaller messages.

PAT is composed of several files. These are summarised in Figure 12.14.

13.1 Implementing SMS Keyword Services

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

Figure 13.2: Example SMS Service group configuration settings

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

This group sets up an SMS service that returns a proverb from the Web page http://www.awebsite.net/potd.html when it receives the message 'proverb' from a mobile device. From the Web page, it retrieves everything between (but not including) the strings <!--beginprov--> and <!--endprov-->. The content of potd.html could look like this:

 <html>
  <head>
        <title>SMS proverb of the day</title>
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
   <!--beginprov-->
   A cat in gloves catches no mice.
   <!--endprov-->
  </body>
 </html>

In this case, a user sending the message 'proverb' to the Alligata Server would receive the reply message

Today's proverb -- A cat in gloves catches no mice.

The Alligata Server does not require the prefix and suffix of the message to be in comments <!--...-->, 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.

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 split-chars and split-suffix. The message is split at an occurrence of one of the characters specified in split-chars, and all sections of the message except the last have the text specified in split-suffix 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 potd.html is a particularly long one:

 <html>
  <head>
      <title>SMS proverb of the day</title>
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
   <!--beginprov-->
   Monday's child is fair of 
	 face, Tuesday's child is 
	 full of grace; Wednesday's 
	 child is full of woe, 
	 Thursday's child has far 
	 to go; Friday's child is 
	 loving and giving, Saturday'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.
   <!--endprov-->
  </body>
 </html>

In this instance, the message needs to be split, and the user will probably receive it in three smaller messages:

Today's proverb -- Monday's child is fair of face, Tuesday's child is full of grace; Wednesday's child is full of woe, Thursday's child has far to go; -cont.-

Today's proverb -- Friday's child is loving and giving, Saturday's child works hard for its living; -cont.-

Today's proverb -- and the child that is born on the Sabbath day, is fair and wise and good and gay.

The string -cont.- 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 split-suffix configuration variable.

Note that the incoming SMS message must only contain the keyword, unless the SMS service allows parameters after it. Parameters are discussed in Section 13.1.1.

keyword = salary
aliases = Salary;SALARY
url = http://intranet.awebsite.net/cgi/salary?user=%s&password=%s&employee=%r
header = "Salary info -- "

13.2 Sending SMS Messages Using HTTP

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.

Figure 13.4: Example Send SMS User group

group = sendsms-user
username = colin
password = AVOcado
user-allow-ip = 10.0.0.5
max-messages = 10
split-chars = .;,
split-suffix = -cont.-
header = "Msg from Colin -- "

This configuration group allows the user colin with the password AVOcado 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 max-messages. The variables split-chars, split-suffix and header work exactly as in SMS Service groups (see Section 13.1).

http://hostname:port/cgi-bin/sendsms? username=username& password=password& from=sender's_number& to=receiver's_number& text=message_text

The elements in bold italic type should be replaced with the relevant information. For example:

http://localhost:13013/cgi-bin/sendsms?username=colin& password=AVOcado&from=0999666666&to=0898999999&text= All+sales+staff+return+to+office+immediately

The URL should contain no carriage returns and no spaces. Spaces in the message should be represented by plus signs +.

 <html>
 <head>
  <title>SMS Message Sender</title>
 </head>
 <body bgcolor="#FFFFFF" text="#000000">
  <h1>SMS Message Sender</h1>
  <form name="sendsms" method="get" 
	    action="http://localhost:13013/cgi-bin/sendsms">
   <input type="hidden" name="username" value="tester">
   <input type="hidden" name="password" value="foobar">
   <input type="hidden" name="from" value="0999666666">
   <p>
    Telephone number:<br>
    <input type="text" size="30" name="to">
   </p>
   <p>
    Message:<br>
    <textarea cols="25" rows="5" name="text">
</textarea>
   </p>
   <p>
    User Data Header (optional):<br>
    <input type="text" size="30" name="udh">
   </p>
   <input type="submit" value="Send Message">
   <br>
  </form>
 </body>
 </html>

13.3 Over-the-air (OTA) Configuration of WAP Client Devices Using SMS

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

The Alligata Server's OTA configuration feature is currently known to work on the Nokia 7110, Nokia 6210 and Nokia 9110i phones.

In order to implement OTA configuration, you need to set up three configuration groups in the configuration file:

• an OTA Configuration group, containing the settings to be sent to the client device

• a Send SMS User group, setting up a user account for sending of OTA messages

• an SMS Service group, pointing to the Alligata Server's sendota CGI application

For details of configuration groups and variables, see Section 9.

An example set of configuration groups for OTA configuration is shown in Figure 13.6.

Figure 13.6: Example settings for OTA configuration

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

group = otaconfig
location = "http://www.asite.net"
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 = ""
user-allow-ip = ""
max-messages = 2
concatenation = 1