WMLScript

							WMLScript
        INTRODUCTION
What is WMLScript?

      WMLScript is a client side scripting language based on
   ECMAScript (which is based on Netscape‟s JavaScript
   language), whose purpose is to provide client-side
   procedural logic.
      It provides general scripting capabilities to the Wireless
   Application Protocol (WAP) architecture.
       Specifically, WMLScript complements the Wireless
   Markup Language (WML).
       While WML focuses on content, it is a declarative
   document markup language designed to convey the essence
   of a user-interface.
       WMLScript is imperative language, which focuses on
   procedure and logic.
      WMLScript belongs to the application layer of the WAP
   archicture and makes use of services and facilities of the
   lower layers.
      It causes WML documents to interact with the users.
      WMLScript is to WML, is like JavaScript is to HTML.

      WMLScript is the JavaScript of the wireless world.
      WMLScript has a weak type definition which means that
   variable types are not defined during declaration, the data
   types are determined during execution.

       While the WMLScript code is maintained on the servers,
   the script execution takes place on the local device.
What is WMLScript used for?

       WML, which is based on Extensible Markup Language (XML),
    specifies application content for narrowband devices like cell
    phones.
        WML allows simple formatting to make the user interface
    more readable, but its content is static with the following
    limitations:
       1)checking the validity of user input.
       2)Access to facilities of the device. For example, on a phone,
         allow the programmer to make phone calls, send messages etc.
       3)Generating messages and dialogs locally thereby reducing the
          need for expensive round-trips to show alerts, error messages,
          confirmations, etc.
       4)Allowing extensions to the device software and configuration
          of the device after it has been deployed.
       WMLScript is designed to overcome these limitations and to
    provide programmable functionality that can be used over
    narrowband communication links in clients with limited
    capabilities.
        WmlScript is a function-oriented scripting language , which
    enhances WML applications.
        WMLScript focuses on procedure and logic. It adds dynamic
    code to static WML data. For example, when validating form field
    entries, providing rapid responses and calculations, for expanding
    the normal functions to mobile phones, sending messages and
    dialogs and even for creating games.
       Many of the services that can be used with thin mobile clients
    can be implemented with WML.. Scripting enhances the standard
    browsing and presentation facilities of WML with behavioral
    capabilities.
       They can be used to support more advanced User Interface(UI)
    functions, add intelligence to the client, provide access to the
    device and its peripheral functionality, and reduce the amount of
    bandwidth needed to send data between the server and the client.
             WMLScript Vs JavaScript
          WMLScript is simple scripting language similar to JavaScript
          but there are, quite a lot of differences between the two.
                           While HTML documents normally contain
                       embedded JavaScript code, WML only contains
                       references to the URL addresses of a WMLScript
                       function.
                           Unlike HTML, in which the JavaScript code is
                       compiled along with HTML, WMLScript has to be
                       compiled into binary code before being executed
                       on a WAP device. Therefore a WMLScript Virtual
                       Machine has to be included in the browser that
                       executes the script.
                          To speed up data transfer, WMLScript libraries
                       are pre-compiled and loaded to the user agent‟s
                       memory, providing quick access to the
                       WMLScript script.
                          JavaScript does not support call-by-address
                       whereas it is supported in WMLScript. That is, an
                       argument can be set inside a function and
                       communicated back to the caller. JavaScript, on
                       the other hand supports call-by-value, that is,
                       functions can read parameter values from their
                       caller, but cannot change these values in the
                       caller‟s scope.

   How to call a WMLScript function?
WMLScript code is written in normal text files with the extension
 *.wmls (for example, script1.wmls). These text files are placed on the
 same server as normal WML documents; however, it is also possible to
 call WMLScript functions on other servers from within WML
 documents or from WMLScript code.

A text file is called a compilation unit, and it may contain one or several
  functions. A compilation unit can be placed in the same directory as
  WML documents, or in a separate subdirectory. Functions that have
  similar properties should be placed in the same compilation unit.
When a WML document contains a reference to a WMLScript function,
the call will be routed from the browser through the gateway to the
server. The server will then send the necessary WMLScript compilation,
which is converted into binary format in the gateway.

The reason for this is, that binary file is smaller and therefore easier to
transmit over a wireless network. The binary file is sent from the gateway
to the WAP browser. The WAP browser has an interpreter that is able to
execute WMLScript programs in their binary format.

WMLScripts are not embedded in WML pages. The WML pages only
contain references to script URL‟s.
In the example below, a card is created where you enter a URL, select the
„go‟ label, and then go off to the specified URL.

<?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=“no1” title=“Go to URL”>
<do type=“options” label=“Go”>
<go href=“check.wmls#go_url(„my_url‟)”/>
</do>
<p>
Enter a URL:
<input type=“text” name=“my_url”/>
</p>
</card>
</wml/>

The red line above contains a reference to a WMLScript. The script is in
a file called check.wmls, and the name of the function is go_url.
The go_url function sends you to the URL you entered. The function also
checks if you omitted the “http://” part in the URL.

The same reference system is used for calling WMLScript functions as in
HTML and WWW, which means that resources are referred to with their
relative or absolute addresses. The call should always include the name
of the target WMLScript function and its list of parameters. The call may
be absolute or relative.
The WMLScript function may call functions within the same compilation
unit or functions in other compilation units or libraries.
Here is the WML page called :

                                     check.wmls
Extern function go_url (the_url)
{
  if (String.find(the_url , “http://”) < 0 )
  {
     the_url = “http://” + the_url;
   }
 WMLBrowser.go (the_url);
}
If the WMLScript function is defined with the word extern, it can be
called from any other compilation unit, unless it is protected by access
control programs. The extern keyword is used to allow other functions
access to this function, or WML events outside the .wmls file.

WMLScript Bytecode Interpreter
    WMLScript must be compiled into binary form before it can be
    interpreted by the WMLScript bytecode interpreter. WMLScript
    compiler encodes one WMLScript compilation unit into WMLScript
    bytecode. A WML Compilation unit is a unit containing pragmas and
    any number of WMLScript functions. WMLScript compiler takes one
    compilation unit as input and generates the WMLScript bytecode as
    its output.
    WMLScript interpreter takes WMLScript bytecode as its input and
    executes encoded functions as they are called.
          Call http://www.host.com/script#myFunc(“Test”,12)


             WMLScript                         Interpre
                                                                          WMLScript
              Libraries                           ter                      Bytecode
                                                                            Functions
                Functions                                                     …..
                                                                            myFunc()



                                                 State
                                        IP                Operand Stack
                                    Call Stack              Variables
The WMLScript interpreter can be used to call and execute functions in a
compilation unit encoded as WMLScript bytecode.
Execution of a WMLScript function means interpreting the instructions
residing in the WMLScript bytecode.

  Pragmas
WMLScript is a compiled language and uses Compilation Units and
Pragmas. In addition to collection of functions, a compilation unit also
contains Pragmas, which are the statements interpreted by the compiler.
         A pragma is a directive that generates special behavior from the
       compiler.
         All pragmas are optional, but if used must be preceded by the
       keyword use and appear at the beginning of a compilation unit before
       any function declarations.
 A certain application may include separate scripts that were individually
and independently compiled. A compilation unit can call functions that are
defined in another compilation unit. WMLScript uses pragmas to identify
other compilation units that it uses.

There are 3 WMLScript pragmas :-
      Access Control Pragma-
      A WMLScript computation unit can protect its content by using a
      special access control pragma, which is examined before any
      externally-defined functions are executed.
      A compilation unit may use only one access control pragma. The use
      access pragma is written at the beginning of the WMLScript
      compilation unit.
      For example,
                 use access domain “wap.acta.fi” path “/wap”;

      An access control pragma is specified by the unique word access. The
      level of protection is always checked before the function is executed.
      If the compilation unit contains the defined reserved words use access
      in front of the domain name(with the reserved word domain) and/or a
      path(with reserved word path), the authority of the compilation unit
      that calls the pragma-protected function to execute the function will
      be checked before execution.
  The syntax of access control pragma may be specified in any one of
  the ways:
  use access domain
  use access domain ;
  use access path ;
  Use access domain path ;

Meta Pragma –
  The second type of pragma is the meta pragma. It communicates
  between different players of the wireless communication: originating
  connection servers and user agents. The name meta pragma request
  the originating servers for different kinds of information.

  Meta pragmas convey information to different entities in the WAP
  environment. Compilation units may contain more than one meta
  pragma, but no more than one meta pragma of the same type.

    Syntax:           Meta elementName  “elementvalue”
                     http equiv elementName “elementvalue”
    Use meta


                     User agent elementName “elementvalue”Name

  The second type of “elementvalue”
                      pragma is the meta pragma. It communicates
  between different players of the wireless communication: originating
  connection servers and user agents. The name meta pragma request
  the originating servers for different kinds of information.

                      elementName “elementvalue”
  Meta pragmas convey information to different entities in the WAP
  environment. Compilation units may contain more than one meta
  pragma, but no more than one meta pragma of the same type.

  The Name information is intended for origin servers, and may contain
  such information as copyright assignments. Network servers should
  not emit WMLScripts containing, and user agents should ignore, meta
  pragmas.
  For Example,
      use meta name “Created” “22-May-00”;
http equiv information is used to control HTTP headers. It is used to
specify HTTP header information between intermediating servers that
transfer the compilation unit.
For Example:
   use meta http equiv “keywords” “Script, Language”;
User agent information is reserved for passing information to specific
WAP user agents to implement WAP extensions.
For Example:
  use meta user agent “Type” “Test”;

 URL Pragma –
Functions in WMLScript are accessed by using a URL. To access a
function outside of a compilation unit, one must include a pragma that
associates the URL of the other compilation unit an internal identifier.
The identifier can then be used to access the external function.
Multiple url pragmas are permitted in a compilation unit.
The use url pragma specifies the location (URL) of the external
WMLScript resource and gives it a local name. This name can then be
used inside a function declarations to make external function calls.
For example:
use url DocJS “http://www.docjavascript.com/mywml”;
function divide(nom, denom)
{
  if (denominator == 0) return invalid;
  return DocJS#mydiv(nom, denom);
}
The use url pragma specifies a URL to a WMLScript compilation
unit, http://www.docjavascript.com/mywml. If the file extension is
omitted, the user agent will look for the extension .wmlsc , I.e. it will
look for http://www.docjavascript.com/mywml.wmlsc .
Once the file is found, the function call DocJS#mydiv() triggers the
loading of the external compilation unit,
 http://www.docjavascript.com/mywml.wmlsc.         Upon      successful
loading of the external resource, its content is verified to have the
definition of the mydiv() function, and it is with the calling
parameters, mydiv(nom, denom).
WML Language Syntax
WMLScript syntax is based on the ECMAScript. Following points
summarize some basic syntactical features:
     The smallest unit of execution in WMLScript is a statement and
   each statement must end with a semicolon(;).
       WMLScript is case-sensitive.
       Comments can either be single-line(starting with //) or
   multiline (bracketed by /*…*/).
       A literal character string is defined as any sequence of zero or
   more characters enclosed within double(“ “) or single(„ „).
       New variables are declared using var keyword.
    Boolean literal values correspond to true and false.
       WMLScript is a weakly-typed language.
       Internally, the following data types are supported:
          Boolean, Integer, Floating-point, String, and Invalid.
       Includes assignment, arithmetic, logical, string, comparison,
   and array operations.
          Includes control statements like if-else, for loop, while loop,
   break and continue statements.

Naming Rules
Identifiers within WMLScript can be used to name variables,
functions and pragmas.
When managing names, WMLScript differentiates between three
name spaces:
              function names
              function parameters and variables
              pragmas
It is allowable to use the same name for a function and variable. Like
most languages, WMLScript has a list of reserved words like access,
agent, meta, url, use, etc.

Variables and Data Types
WMLScript is a weakly typed language. No type checking is done at
compile-time and no variable types are declared. Four types of values
can be declared for WMLScript variables:
     integer, floating point, string and Boolean.
The fifth type is invalid, which is reserved for cases when the type
cannot be determined. This may happen in type conversions or when
dividing by zero.
Because the data types are only supported internally, they are not
defined during the declarations, but the type is determined during the
execution of the function.
WMLScript converts between the types if necessary.

Standard Libraries –
While WMLScript does not support the creation of new objects via
object-oriented programming, it does provide six “pre-built” libraries.
        Lang – This library contains a set of functions that are closely
   related to the WMLScript language core. Included in this library
   are functions for data type manipulation, absolute value
   calculations, and random number generation like abort(), abs(),
   etc.
        Float – The Float library is optional and is only supported on
   those clients who have floating-point capabilities. Typical
   functions provided are sqrt(), round(), pow(), etc.
        String – The String library contains a set of functions for
   performing string operations like length(), charAt(), find(), etc.
        URL – This library contains a set of functions for handling
   both absolute URLs and relative URLs. Typical functions included
   are getPath(), getReferer(), and getHost().
        WMLBrowser – This library contains functions by which
   WMLScript can access the associated WML context. These
   functions must not have any side effects and must return invalid in
   cases where the system does not support WMLBrowser. Some of
   the functions included are go(), prev(), next(), refresh(), etc.
        Dialogs – This library contains a set of typical user interface
   functions including prompt(), confirm() and alert().
    The functions in Dialogs library are quite similar to JavaScript
   alerts and message boxes.
Example: Validating User Input
We build a simple WML card that asks the user to input a social
security number (an identification number). We will then use
WMLScript to verify that the user‟s input was formatted correctly.
Following this verification, we‟ll alert the user whether their number
was accepted or not.
First, let us create a normal WML file containing two cards(an input
card and a results card). Accepting the input will result in our
validateSSN() being called.
Note that this function is stored in a separate .wmls file
(WMLScriptExample.wmls) and is declared within that file using the
extern keyword.
                              WMLScriptExample.wml
<wml>
     <card id="SSN" title="SSN:">
        <do type="accept" label="Results">
          <gohref = "WMLScriptExample.wmls#validateSSN($(SSN))“/>
        </do>
        <p>
         Enter SSN: <input type="text" name="SSN"/> </p>
    </card>
    <card id="Results" title="Results:">
<p>
     You entered:
     <br/>
        SSN: $(SSN)
     <br/>
</p>
</card>
</wml>
                            WMLScriptExample.wmls

extern function validateSSN(SSN)
{
  if (String.length(SSN) != 9)
  {
     WMLBrowser.setVar("SSN", "Error: String must be 9 digits long.");
  }
  WMLBrowser.go("WMLScriptExample.wml#Results");
};