Basic Concepts

GSL - The Gsharp Script Language

 GSL is an interpreted programming language which can be used to control Gsharp and develop graphics applications. The Graph templates used by the Gsharp Web Edition examples are all written in GSL. GSL can be programmed using a text editor, or GSL can generated using the Gsharp Professional Edition distributed on CD. In order to create your own graph templates, you will need to know how to program GSL. If you intend to develop graph templates and you do not have the Gsharp Professional Edition, you are strongly recommended to order this product, which comes with the interactive Script Builder tool and complete documentation and lessons in GSL programming.

GSL programming tips and lessons can also be found on the Web. Try the AVS homepage for links to additional sources of documentation. Another good source of GSL programming information is the Gsharp examples. You will find GSL examples generated using the Gsharp Script Builder tool showing object creation and property setting, as well as programmed examples using more advanced program structure and flow control.

Writing HTML from GSL

The Gsharp Script Language contains specific functions for creating and setting Gsharp graphics, and also functions for general file I/O. The GSL I/O functions can be used to output the HTTP header and HTML commands needed to dynamically construct web pages. This section will guide you through a GSL script that constructs a very simple web page and explain the basic techniques that will be used as you develop your own dynamic web applications.

To output HTML, an output function must be used. GSL includes the following I/O functions, which closely correspond to the ANSI C functions of the same name: 


	fopen(file_name, mode)

	fwrite(access_id, var1[, ... varN]) 

	fclose(access_id)
These functions can be used to output text to stdout or a file. When using standard system files, such as stdout, as the output file, fopen and fclose do not need to be called, as these files are managed by the system. Here are the access id's for the standard system files: 
	stdin        0
	stdout       1
	stdmsg       2
GSL I/O functions can be called from a program to create a simple HTML page. Here is a short example: 

        /*
         * Open file, write out HTML, close file
	 */
	id = fopen("hello.html", "w");
	fwrite(id, "<HTML><BODY BGCOLOR=#FFFFFF>"); 
	fwrite(id, "<TITLE>GsharpWE Greeting</TITLE>"); 
	fwrite(id, "<FONT SIZE=+4><CENTER><B>"); 
	fwrite(id, "Hello Wide World"); 
	fwrite(id, "</B></CENTER></FONT><P>"); 
	fwrite(id, "</BODY></HTML>"); 
	fclose(id);
This program can be run using the command: 

	/bin/GsharpWE hello.gsl
When this GSL is run, the file hello.html is created. Would you like to view the result?

CGI programming with GSL

Now that you have seen how to output HTML from a GSL program, the next step is to use GSL as a Common Gateway Interface and generate the HTML dynamically from the browser. In the the following example, an HTML form is used to request input which is then passed to a GSL program which functions as a CGI. The GSL will generate a web page based on form input.

First a form is needed. Here is the HTML for a simple form which prompts for a single parameter, your name: 

<form method="post" action="http:/cgi-bin/gs_hello1.gsl">
<b>Please type your name: </b><input type="text" size=20 name="name"> 
<input type="submit" value="Enter">
</form>
The action attribute to the HTML form element points to the CGI that handles the form, in this case the GSL script gs_hello1.gsl.

The GSL program created in the previous example can, with a few minor modifications, function as a CGI. First, a comment must be added at the beginning of the script so that UNIX knows how to execute it: 


	#!/bin/GsharpWE
On the Windows NT platform, this is not neccesary as the .gsl extension determines which program is used to run the script. However, it does not harm to include the comment.

Previously, the GSL program only output HTML. When run as a CGI, it must also output a HyperText Transfer Protocol (HTTP) header. This is done with these additional statements added as the first fwrite output: 


	fwrite(id, "Content-type: text/html"); 
	fwrite(id, "");
Next, the output changed from going to a file, to going directly to stdout. The fopen and fclose statements are no longer needed:

	id = 1;
And finally, make a change to the greeting text so that the form input is used: 
	fwrite(id, "Hello ", FORM_name);
You may wonder where the GSL variable FORM_name comes from. GsharpWE will automatically parse form input, either from the environment variable QUERY_STRING when the form method "GET" is used, or from stdin when the method "POST" is used. GsharpWE will append the input name defined by the form to the prefix "FORM_" and create a string variable which is set to the corresponding form value string. Recall the HTML statement from the form:

</b><input type="text" size=20 name="name">
This statement defines a form parameter named "name". GsharpWE parses this parameter from stdin and creates the variable FORM_name which is then used in the GSL fwrite statement.

A complete listing of the modified GSL program follows.

Check Point 


#!/bin/GsharpWE
/*
 * Open file, write out HTML, close file
 */
id = 1;
fwrite(id, "Content-type: text/html"); 
fwrite(id, ""); 
fwrite(id, "<HTML><BODY BGCOLOR=#FFFFFF>"); 
fwrite(id, "<TITLE>GsharpWE Greeting</TITLE>"); 
fwrite(id, "<FONT SIZE=+4><CENTER><B>"); 
fwrite(id, "Hello ", FORM_name); 
fwrite(id, "</B></CENTER></FONT><P>"); 
fwrite(id, "</BODY></HTML>");
To run any cgi program, the program must reside in the cgi-bin directory defined for your server. The GsharpWE install script has linked the file gs_hello1.gsl to your cgi-bin directory. You can try running it using the form below:

Please type your name:

Dynamically Creating a Graph

 The technique of passing information from the browser to the web server via a common gateway interface can be used to dynamically create a graph. The CGI from the previous example can be further developed to invoke a graph template. The term graph template refers to reusable code which makes a graph. GsharpWE graph templates are written in GSL, and create graphical objects and set properties belonging to these objects, thus defining a graph layout.

Let's begin this example by extending the HTML form so that it prompts for an additional parameter, the graph type. The HTML defining the form can be modified as follows to include a selection list: 

<form method="post" action="http:/cgi-bin/gs_hello2.gsl">
<b>Please type your name: </b><input type="text" size=20 name="name"> 
<b>Graph Type: </b><select name="graph">
	<option value="bar">Bar
	<option value="line">Line
	<option value="pie">Pie
        </select>
<input type="submit" value="Enter">
</form>
Next, a graph template is needed. GsharpWE can make a default graph from randomly generated data using these GSL statements: 

	create Viewport page_1.viewport_1 ;
	create Domain page_1.viewport_1.domain_1 ;
	create Graph page_1.viewport_1.domain_1.graph_1 
	   ( XuNyData = "rnd(10)"
	   );
Perhaps you have noticed that this GSL does not make use of the new form information. Recall from the previous discussion of form processing that GsharpWE will automatically create form variables. In this case, a variable named FORM_graph will be created and set to the value of the form selection. This information can be directly used by the GSL create statement to set the graph type: 

	create Graph page_1.viewport_1.domain_1.graph_1 
	   ( XuNyData = "rnd(10)",
	     XuNgraphType = FORM_graph
	   );
The GSL script can also contain logic based on the form variables. For example, the layout of the graph can vary according the graph type selected: 

	if FORM_graph  = "line" then 
	   set page_1.viewport_1.domain_1.graph_1
	      ( XuNsmoothingFactor = 9,
	        XuNcolor = 2
	      );
	elif FORM_graph = "bar" then 
           page_1.viewport_1.domain_1.graph_1.XuNcolor = 4;
	endif
Unlike the GSL from the first CGI example which output HTML, this GSL creates a graph. To keep these two operations seperate, the graph template can be defined as a GSL function:

Check Point


	function makeGraph()
	   string type;
           type = "line";
           if exists(WORK.FORM_graph) type = FORM_graph;
	   create Viewport page_1.viewport_1 ;
	   create Domain page_1.viewport_1.domain_1 ;
	   create Graph page_1.viewport_1.domain_1.graph_1 
	      ( XuNyData = "rnd(10)",
		XuNgraphType = type
	      );
	   if type = "line" then 
	      set page_1.viewport_1.domain_1.graph_1
		 ( XuNsmoothingFactor = 9,
		   XuNcolor = 2
		 );
	   elif type = "bar" then 
	      page_1.viewport_1.domain_1.graph_1.XuNcolor = 4;
	   endif
        endfunction
Notice in the above function that a default setting for graph type has been introduced (type = "line") instead of using the form data directly. This is a coding style that makes template testing easier, since the template will still run if no form input is provided.

Generating an Image

Once the graph template is defined, the next step is to output the graph as a web-compliant image. The Gsharp Web Edition includes several libraries of pre-defined functions, libhtml, and libjava, for commonly used actions such as generating HTTP and HTML headers, and for creating web-compliant images. We can use one of these functions to create in image from the graph template.

Before a GSL library function can be used, the library must be read in. This can be done with the GSL include statement, which should appear in the main portion of the GSL script before the function is referenced. 


	include "$UNIDIR/lib/libhtml.gsl";
$UNIDIR is an environment variable known to GsharpWE, and points to the full path where GsharpWE has been installed. The libhtml library contains the GSL function make_image, defined as: 

	make_image(float xres, float yres, string filename)
The format of the image is determined by the extension part of the filename: 

	".gif"	- GIF image format
	".jpg"	- JPEG image format
	".png"	- PNG image format
	".java" - Java source
Note - PNG is a new image format adopted by the World Wide Web Consortium, W3C, as an alternative to GIF. Unlike GIF, PNG is based entirely on open standards. Depending on the vendor and version number of your browser, PNG may or may not be supported.

Adding this function call to the template will generate an image of the graph: 


	make_image(400, 300, "$UNIDIR/example/hello2.gif");
However, using a fixed image name can give problems if the template is run repeatedly. Most browsers cache a displayed image. This can cause an old version of the image to still be displayed even though a new version has been created. To prevent this from occurring, a unique name can be dynamically created using the getpid() function: 

	image = "/GsharpWE/tmp/hello2"+getpid()+".gif";
Check Point

Here is the final GSL which includes all of the above modifications. The source for this example can be found in example/GsharpWE/misc/hello2.gsl. 


	function makeGraph()
           string type;
           type = "line";
           if exists(WORK.FORM_graph) type = FORM_graph;
	   create Viewport page_1.viewport_1 ;
	   create Domain page_1.viewport_1.domain_1 ;
	   create Graph page_1.viewport_1.domain_1.graph_1 
	      ( XuNyData = "rnd(10)",
		XuNgraphType = type
	      );
	   if type = "line" then 
	      set page_1.viewport_1.domain_1.graph_1
		 ( XuNsmoothingFactor = 9,
		   XuNcolor = 2
		 );
	   elif type = "bar" then 
	      page_1.viewport_1.domain_1.graph_1.XuNcolor = 4;
	   endif
        endfunction

	include "$UNIDIR/lib/libhtml.gsl";
	string image; image = "/GsharpWE/tmp/hello2"+getpid()+".gif";
	/*
	 * create a graph and image
	 */
        makeGraph();
	make_image(400, 300, "$UNIDIR/example/" + image);

        /*
         * write out HTML
	 */
	id = 1;
	fwrite(id, "<HTML><BODY BGCOLOR=#FFFFFF>"); 
	fwrite(id, "<TITLE>GsharpWE Greeting</TITLE>"); 
	fwrite(id, "<CENTER><FONT SIZE=+4><B>"); 
	fwrite(id, "Hello ",FORM_name); 
	fwrite(id, "</B></FONT><P>"); 
	fwrite(id, "<IMG SRC=\"",image,"\">"); 
	fwrite(id, "</CENTER>"); 
	fwrite(id, "</BODY></HTML>");
You can try running this example using the form below:

Please type your name: Graph Type: