The WebCOMAL Tutorial: Part 1

This is a hands-on tutorial to guide you through creating and running UniCOMAL programs in Web Browsers. It is meant to be used along with the other articles which have appeared so far as part of the WebCOMAL project: WebCOMAL, WebCOMAL: Running Remote and WebCOMAL: Output to a Frame.

You should have a basic knowledge of UniCOMAL programming before you start. You should also have the WebCOMAL package downloaded and all the required software components installed in your computer before going any further.

"Weblet": in this series of tutorials, we refer to "a COMAL program designed to run from a Web Browser" as a "weblet", for short.

The Three Stages

There are three stages in running a COMAL weblet in a browser:

First, the host computer (that is, the computer on which the weblet is stored) must be properly set up. It must have running in it the Java Servlet supplied with the WebCOMAL package, have a COMAL interpreter (COMAL.EXE or COMAL87.EXE) stored in a location accessible to the servlet, and have the source code for the weblet, as a .CML file, saved on it in a location accessible to the browser. This all sounds fairly daunting, but, if the host computer is also the machine on which the browser is running, it's a lot easier to set up than it sounds. From now on, we'll assume that you have a PC set up and ready.
Next, the COMAL weblet. This is an ordinary UniCOMAL program which has a USE internet statement and is written so that its output is in a form which can be displayed by the web browser, that is to say, in HTML format.
Finally, the calling webpage. This is an ordinary HTML page which calls and executes the COMAL weblet. The call can be immediate or invoked by a mouse-click on a link. The calling page can also, by using an HTML form, supply data as input to the weblet.

The Internet Module

The internet module provides a wide range of facilities to help in interacting with weblets. Here is a complete list, for Module Version 0.3:

  remote_addr$          // remote host ip address
  remote_host$          // remote host name
  remote_user$          // remote host user (if available)
  auth_type$            // author type
  character_encoding$   // char encoding
  content_length#       // content length in bytes
  content_type$         // type of content (e.g. html/text)
  method$               // action method ("POST", "GET", etc)
  path_info$            //
  path_translated$      //
  protocol$             // protocol type (e.g. HTTP/1.1)
  query_string$         // query string for script
  scheme$               // scheme
  server_info$          // info about server
  server_name$          // server name
  server_port#          // server port
  servlet_path$         // path of servlet used for webCOMAL
  servlet_in$           // temporary input for COMAL
  servlet_out$          // temporary output for COMAL

  parameter_count#      // # of parameter tags in page
  header_count#         // # of header tags in page

  print_context         // prints the internet context
  get_parameter$()      // get a parameter tag with a certain name
  get_parameter_name$() // get a parameter tag name using an index
  get_header$()         // get a header tag with a certain name
  get_header_name$()    // get a header tag name using an index

The most useful of these items are "parameter_count#", which you can use to find out how many parameters are being passed to a COMAL weblet, and "get_parameter$", which is used in a COMAL weblet to capture information from the HTML page which calls the weblet. Data is passed back to the browser from the weblet using ordinary COMAL PRINT statements. Note that all data passed to, or received from, the browser, is of type string. This means that numbers used in the COMAL weblet have to be converted to strings before being sent to the browser, using the STR$ function. If you want to capture a number from the browser, you must first get it as a string, then evaluate the string in COMAL using the VAL function.

A First Program

As a first example, we'll build a weblet that displays the traditional "Hello World!" string, 50 times, in a browser window. Here's the COMAL code:

  100 // WebCOMAL Tutorial Example 1
  110 USE internet
  120 start_html("WebCOMAL Tutorial Example 1")
  130 FOR string#:=1 TO 50 DO PRINT "Hello World! "
  140 end_html
  150 END
  160 //
  170 PROC start_html(title$)
  180   PRINT "<HTML><BODY><H1>"
  190   PRINT title$
  200   PRINT "</H1>"
  210 ENDPROC start_html
  220 //
  230 PROC end_html
  240   PRINT "</BODY></HTML>"
  250 ENDPROC end_html

The procedures "start_html" and "end_html" are used to keep the "housekeeping" HTML tags separate from the COMAL code, which makes the weblet a bit more legible than it would be with all the HTML stuff mixed in with the COMAL. Also, you can easily modify "start_html" to suit the type of webpage you want to COMAL weblet to generate.

We use ordinary COMAL PRINT statements to send all output to the Webpage. The "USE internet" statement redirects the output from all the PRINT statements to the Java Servlet which is managing the communication to and from the webpage.

Copy-and-paste the above program into your UniCOMAL editor, then SAVE the program into your C:\COMAL folder. Call it "Tutor1".

Now we've got the weblet, we need a simple webpage to CALL it into action. Here is the text for a suitable calling page:

  <HTML>
  <BODY>
  <a HREF=http://localhost:8080/servlet/
  comal.ComalServlet?COMAL_EXE=c:\comal\
  comal.exe&COMAL_PRG=c:\comal\Tutor1.cml>
  Run the Tutor1 COMAL script</a>
  </body>
  </html>

(The "A HREF=...." statement should be all on one line of the HTML source file). Copy-and-paste this text into Notepad, make sure that the "A HREF=...." anchor is all on a single line of text with no spaces or line breaks, then SAVE the file as "Tutor1.html".

Now to try it out. Make sure that your WebCOMAL Servlet is running in your computer, then double-click the "Tutor1.html" file icon. You should get a simple webpage with a link like this:

Run the Tutor1 COMAL script

When you click on that link, the weblet will be invoked and the browser page will change to look like this:

WebCOMAL Tutorial Example 1

Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World! Hello World!

Feedback! Feedback!

We'd love to hear from you. If you're following these tutorials, and have questions, comments, suggestions, or WebCOMAL programs or projects that you'd like to share with others, please email webcomal@macharsoft.co.uk. Everyone's input will be acknowledged.

Updated 28 April 2000