Functional Reference

Built-in Functions

This chapter describes functionality unique to the Gsharp Web Edition. For a complete description of all Gsharp functions, please refer to the Gsharp User's Guide which is included with the Gsharp CD distribution kit.

getpid()

Category	String
Syntax	getpid()
Usage	Returns the process id of Gsharp formatted as a string. Will always return 0 under Windows NT.
Example

pid = getpid();
echo("pid = ",pid,", type = ",typeof(pid));

Result

pid = 27696, type = string

tmpnam()

Category	String
Syntax	tmpnam()
Usage	Returns a unique filename in a temporary area. On UNIX this will typically be in /tmp or /var/tmp. On NT it will typically be in either C: or C:\TMP. No file is created.
Example

tmp = tmpnam();
echo("tmp = ",tmp,", type = ",typeof(tmp));

Result

tmp = /var/tmp/bcaa006kk, type = string

bounding_polygon()

Category	Float
Syntax	bounding_polygon(string objname, float &nvert, float &xpoly, float &ypoly)
Usage	bounding_polygon will return the number of polygons which makes up the bounding polygons of all graphic elements of the object specified by name. The array returned in nvert will contain an entry for each object describing how many vertices each polygon has. The xpoly and ypoly contains the coordinates for all bounding polygons returned.
Example

function show_polygons(string obj)
   float nvert, xpoly, ypoly, i, j, n, offset;
   string str;
   n =  bounding_polygon(obj, nvert, xpoly, ypoly);
   echo("");echo(obj," has ", n, " polygon",if(n=1,"","s"));
   if n = 0 return;   
   offset = 0;
   for i = 1 to n
     echo("   Polygon no. ", i, " has ", nvert[i], " vertices");
     str = "   ";     
     for j = 1 to nvert[i]
       str = str + "(" + xpoly[j+offset] + "," + ypoly[j+offset] + ") ";
       if mod(j,3) = 0 then
          echo(str);
          str = "   ";     
       endif
     endfor
     offset = offset + nvert[i];
     echo(str);echo("");
   endfor
endfunction

function string branchof(string root)
  string branch, limbs, ptr;
  branch = root;
  limbs = branch + "." + childrenof($branch);
  if limbs <> branch  + "." 
     for node in limbs
        branch = branch // branchof(node);
     endfor
  return branch;
endfunction

function create_graph(string type)
   create Viewport page_1.viewport_1;
   create Title page_1.viewport_1.title_1
      ( XuNtitleText = type + "graph"
      );
   create Domain page_1.viewport_1.domain_1;
   page_1.viewport_1.domain_1.legend.XuNobjectEnabled=true;
   create Graph page_1.viewport_1.domain_1.graph_1
      ( XuNgraphType = type,
	XuNyData = "rnd(5)"
      );
endfunction

/*
 * main program
 */
reset all;
graph_type = "line"//"pie"//"bar";
create_graph(graph_type[1]);
repaint;  #repaint is necessary to set object sizes
hierarchy = branchof("page_1");
for object in hierarchy
   show_polygons(object);
endfor

Result

page_1 has 0 polygons

page_1.viewport_1 has 1 polygon
   Polygon no. 1 has 5 vertices
   (44.8,35.84) (232,35.84) (232,197.12) 
   (44.8,197.12) (44.8,35.84) 

...

libhtml GSL Functions

The following functions are defined in libhtml.gsl:

set_image(float npx, float npy, string filename)

set_image() sets the canvas to the required size and then creates an image based on the extension of the filename:

   .gif   GIF
   .jpg   JPEG
   .png   PNG
   .java  Java

You should use set_image() to set the canvas size, when you want to use HTMLbounding_polygon() on an object that is effected by the canvas size, such as a note.

make_image(float npx, float npy, string filename)

make_image() calls set_image() and then calls print.

float HTMLbounding_polygon(string object, float nvertices, float x, float y, float imagewidth, float imageheight)

HTMLbounding_polygon is a wrapper for the built-in function bounding_polygon(). You are recommended to use HTMLbounding_polygon() as it automatically deals with the conversion to pixel co-ordinates.

Use of this function is explained in more detail in the section Dynamically Generating Image Maps

HTML*()

libhtml.gsl contains many other convenience functions for creating HTML code. They all output formatted strings using the Gsharp function fwrite().

As an example, rather than using


	fwrite(1,"<IMG SRC=\""+imgfile+"\">");

you can use


	HTMLimage(stdout,imgfile);

Calls to HTML*() functions can be mixed with standard fwrite() calls.

The first argument to all these function is always the stream number (returned by fopen()) which makes it easy to write to files or to stdout. File output can be useful when testing, output to stdout is required when running the script as a CGI. The script can be written to handle both cases:


stdout = 1;
if batch() then
  f = stdout;
else
  f = fopen("myfile.html","w");
endif

HTMLheader(f,"Title","Author");
HTMLheading(f,1,"Hello Wide World");
HTMLfooter(f);

if not batch() fclose(f);

libjava GSL Functions

libjava.gsl is a library of functions for writing Java code. It is an example of how GSL functions can be used to perform reusable tasks. It was written as part of the GsharpWE Java example, and contains functions that you may find directly useful or as a basis for your own code development.

The functions java*() output java source code via the Gsharp function fwrite(). Calls to java*() functions can be freely mixed with calls to fwrite().

libjava contains the following functions:

function javaappletheaders(float i)

function javaawtheaders(float i)

function javastartappletclass(float i, string name)

function javastartclass(float i, string name)

function javaendclass(float i)

function javamethod(float i,string name, string method)

function javapaintmethod(float i,string method)

function javamousedragmethod(float i,string method)

function javaexportfloat(float i, string name, float dat)

function javaexportint(float i, string name, float dat)

function javainclude(float i, string includefile)

Examples of using libjava functions can be found in the section Writing Java Applets.

Selecting an Image Format

A function make_image() is provided in $UNIDIR/lib/libhtml.gsl. If you want to modify this or to use your own routine, then the following information will be useful.

Selecting a Device

The output image format is set in GSL using the property hardcopy.XuNdevice. It must be set to the name of a token representing the output device.

  harcopy.XuNdevice = "ggifl8";i

The list of tokens for web-compliant image formats, are listed in the tables below.

Declaring a Device

Any devices you wish to use should be declared in the Gsharp startup file $UNIDIR/base/Gsharprc.gsl or in the user startup file $HOME/.Gsharprc.gsl. The devices in bold below are included by default. The built-in function define_device() is used to declare devices.

  define_device(string token, string description,
                pagesize,x,y,orien,string default_filename);

For image devices, such as GIF and JPEF, pagesize,x,y,orien should be set to 0,,,,

So to create an image using "SJPGI8 - RGB Intensity Device", add the following call to $UNIDIR/base/Gsharprc.gsl:

  define_device("sjpgi8","JPEG (RGB)",0,,,,"gsharp.jpg",);

You can now create the image like so:

  hardcopy.XuNdevice = "sjpgi8";
  print;

Image size

The size of the image that is created is based on the size of your page. Each device has a different number of pixels for each mm of the page. Each driver includes one device which has 1 pixel for 1 mm of the page - this is the token without the H,M or L suffix. This device is used by default. To create a GIF, px pixels by py pixels, use the following commands:

  hardcopy.XuNdevice = "ggifl8";
  page_1.XuNsize = (px,py),
  print;

File names

The property hardcopy.XuNfilename is used to specify the name of the image. e.g.

  hardcopy.XuNfilename = "myplot.gif";

GIF Images

GIF is an 8bpp format with up to 256 colors. The device tokens for GIF are listed below.

GGIFL8        CMY Lookup Device 1 d.p.mm
GGIFL8H       CMY Lookup Device 300 d.p.i
GGIFL8M       CMY Lookup Device 150 d.p.i
GGIFL8L       CMY Lookup Device 75 d.p.i
SGIFL8        RGB Lookup Device 1 d.p.mm
SGIFL8H       RGB Lookup Device 300 d.p.i
SGIFL8M       RGB Lookup Device 150 d.p.i
SGIFL8L       RGB Lookup Device 75 d.p.i

The GIF iamge format contains a patented compression algorithm which Advanced Visual Systems has licensed from UNISYS. According to this contract, users of the Gsharp Web Edition are allowed to use GIF driver driver under the following conditions:

"A portion of this product is licensed under U.S. Patent No. 4,558,302 and foreign counterparts. You may only use this product on the personal computer or workstation for which you have obtained a licensed from the products vender. If you will be using PDF and/or TIFF -LZW and/or GIF and/or PostScript Interpreter and/or proprietary LZW graphics capability, You are prohibited from publishing, distributing, disclosing, modifying or copying the software (except that an end user may make one copy for archival or backup purposes)."

If you have any questions regarding the terms of the Advanced Visual Systems GIF license, please contact Advanced Visual Systems.

JPEG Images

JPEG is a 24 bbp image format supporting high data compression. The high data compression is due, in part, to the fact that a "lossy" compression algorithm is used, resulting in lost pixels. To minimize pixel loss, the Gsharp driver uses the highest image quality, lowest data compression possible. Despite this, pixel loss is still noticeable around image lines and text, which appear to have pixel "clouds" around them. For this reason JPEG is not particularly well suited to vector graphics. Gsharp PNG and GIF image output will provide higher data compression and better image quality. Gsharp JPEG uses 24 bbp, resulting in up to 256**3 colors. The device tokens for JPEG are listed below.

GJPGI8        CMY Intensity Device 1 d.p.mm
GJPGI8H       CMY Intensity Device 300 d.p.i
GJPGI8M       CMY Intensity Device 150 d.p.i
GJPGI8L       CMY Intensity Device 75 d.p.i
SJPGI8        RGB Intensity Device 1 d.p.mm
SJPGI8H       RGB Intensity Device 300 d.p.i
SJPGI8M       RGB Intensity Device 150 d.p.i
SJPGI8L       RGB Intensity Device 75 d.p.i

PNG Images

PNG, "Portable Network Graphics", is an image format designed specifically for the Web. PNG is a true color format supporting up to 48 bbp. Gsharp uses 8 bbp, resulting in up to 256 colors. The device tokens for PNG are listed below.

GPNGL8        CMY Lookup Device 1 d.p.mm
GPNGI8        CMY Intensity Device 1 d.p.mm
GPNGL8H       CMY Lookup Device 300 d.p.i
GPNGI8H       CMY Intensity Device 300 d.p.i
GPNGL8M       CMY Lookup Device 150 d.p.i
GPNGI8M       CMY Intensity Device 150 d.p.i
GPNGL8L       CMY Lookup Device 75 d.p.i
GPNGI8L       CMY Intensity Device 75 d.p.i
SPNGL8        RGB Lookup Device  1 d.p.mm
SPNGI8        RGB Intensity Device 1 d.p.mm
SPNGL8H       RGB Lookup Device 300 d.p.i
SPNGI8H       RGB Intensity Device 300 d.p.i
SPNGL8M       RGB Lookup Device 150 d.p.i
SPNGI8M       RGB Intensity Device 150 d.p.i
SPNGL8L       RGB Lookup Device 75 d.p.i
SPNGI8L       RGB Intensity Device 75 d.p.i

Java Output

ljava         Java Draw Method Driver