How to use the GainServer interface class and Gain client GUI



				version 0.9, May 31 2002
				revised for Geant4.4.1 release, July 03
				revised 17 January 2003

				H. Yoshida, H. Minamimoto
				Naruto University of Education

A) Features of GainServer class and its client partner "Gain"

This new class belongs to the "interfaces" category and provides
a user interface  using socket connection with a remote client GUI Gain. 
The new client Gain is quite similar with GAG in that it provides the 
fully graphical user interface to steer execution of the Geant4 simulation. 

The new features using a socket connection are as follows;
 
  1) GainServer uses TCP/IP socket to communicate with the
	client GUI tool Gain.
	In general, a server may be decoupled from the terminal
	(or the control terminal) on which it was invoked and run
	as a daemon (daemon mode).
	The present Gain server class doesn't behave as a daemon, but
	it requires the control terminal on which the Geant4 application 
	has been invoked and is coupled as long as 
	it is running (terminal mode).

	In the terminal mode, all outputs from G4cout and G4cerr are
	sent to the client by default and can be displayed 
	on the client remote terminal.

	If you want to run Geant4 simulation even after having logged out,
	the shell command "nohup" can be used (Linux and Solaris).
	You have to run a Geant4 application like;

		%nohup $G4WORKDIR/exampleN02 > exampleN02 &

	and then log out.

		%exit
	
	
  2) The partner  client GUI software is "Gain" which runs
	on any platform running Java Virtual Machine, i.e.,
	Windows, Linux etc.. Gain can be invoked from the
	command line (pseudo-terminal in the X windows or
	cygwin in Windows) or newly can be invoked directly from 
	the Web browser like Netscape/Mozilla and Internet Explorer, 
	when they are equipped with the plugin software "Java Web Start". 
	This new facility will be explained in the later sections.

B) Making the library
 G4UIGainServer is a part of Geant4 distribution since Grant-4.4 or Geant-5.0.
GainServer class uses the standard socket implementation which is 
usually found in the platforms like Solaris or Linux. It is tested against
G4SYSTEM=SUN-CC and Linux-g++ and WIN32-g++(Cygwin).

 This new class depends on no external libraries (except the default system
libraries) so that no new environment variables G4UI_BUILD_XX is required.
GainServer.cc/hh files are located in source/interfaces/GAG and the
corresponding library is archived in the libG4UIGAG.a(so). 

	It is simple to make the library.

	1. go to the directory "interfaces/GAG".
	2. make (or gmake)
	3. and you will have a libG4UIGAG.a (so)


C) How to use GainServer in your application
 The way how to use it completely similar to G4UIterminal or G4UIGAG class.

 In your main program

	1. include the header file
		#include "G4UIGainServer.hh"
	2. instantiate the session and run
		  G4UIsession* session = new G4UIGainServer();
		  session->SessionStart();
		  delete session;

 Your application can be compiled just like the ones using G4UIterminal
or G4UIGAG interface classes. No new environment variables are required 
to use this new class.

D) How to get and run the Gain client

 GainServer must communicate with its partner GUI Gain. Gain is
written in Java and Gain is distributed in two compiled forms.
In any forms, you have to install Java, i.e., j2sdk.
(See www.javasoft.com)

  1. command line mode
  	One form is the common jar (Java archive) format; Gain.jar which
	is provided at http://erpc1.naruto-u.ac.jp/~geant4/Sources.html.
	To run it, you have to invoke Java Virtual Machine on your terminal;
  	 % java -cp foobar/Gain.jar Gain
	where foobar is the directory containing Gain.jar file.
	On Windowz, use cygwin for the terminal.

  2. Web Start mode
	Another form is easier to use, once all set-up steps have been
	completed. In this mode, Gain can be invoked by a simple mouse click
	on the link in the Web page, which is provided by the Geant4
	developer. 

	1. You connect to the Java site and install "Web Start" in your
	   PC, following the instructions. If you are using Mozilla/Netscape,
	   you have to add a new MIME type (JNLP) to your list of "Helper
	   programs".
	2. Try if the examples associated with the Java Web Start kit 
	   run correctly. Note that applications which
	   requires file I/O on your system asks you to go out of the
	   "sandbox" environment (three times on Windows). 
	   This execution of Java applications including local I/O operation
	   is only allowed by your permission. To get your permission,
	   demos provided by Java Soft are digitally signed. 
	3. Then connect to http://erpc1.naruto-u.ac.jp/~geant4/Sources.html
	   and run Gain. It is digitally signed by the Geant4 developer
	   at Naruto University of Education.

	On Windows, you may have the icon for "Java Web Start Manager" in which
	Gain will be listed as one of the verified applications. Then, you can
	use Gain directly from Java Web Start without the Internet connection.

	The Manager also provides a focility to log the output from the
	application. It will be helpful to see runtime warnings or error 
	messages as well as to see the G4cout of the Geant4 application.
 
E) What you can do with Gain
  Gain has a graphical interface quite similar to that of GAG. 
 In addition, it provides a function to connect pluriel remote GainServers
simultaneously. Each connection has an independent GUI window in Gain 
so that you can run several Geant4 applications on different remote sites 
and run them simultaneously with the help of Gain which is running on your PC.

 Gain and GainServers can run on the same host (localhost). The free ports are
allocated automatically to respective GainServer.

E) How to run GainServer ans Gain together

 As stated above, the present implementation of GainServer doesn't run in the
daemon mode. So, you have to keep your terminal session as long as your 
application is running.

 The steps are as follows;

   1. login to the remote host(s) on which you are going to run your
	Geant4 application(s)
   2. run your application. GainServer displays the message;
	"GainServer waiting at port 40000"
     	The port number starting from 40000 is automatically allocated to
	your application(s). This port number is used to connect Gain
	client to the server.
	If you run another Geant4 application on the same remote machine, 
	another port number is automatically allocated and displayed.

   3. run Gain client on your PC. The upper left menu urges you to
	type in the port number and host name. Select "localhost", if
	GainServer is running on your PC.

  	When connection is established, you will have the commands tree
	and parameter window just like those of GAG.

	If you connect to another Geant4 application, another tabbed pane
	is created to manage that connection.

   4. You can disconnect one or all connections. By this disconnection, 
	corresponding Geant4 applications exit using a gentle exit command
	of Geant4, so that normal exitng procedures of Geant4 is performed.

F) How to use VRML viewer together with Gain (Under test)
  A prototype implementation of Gain is available (2002 end July)
which incorporates Geant4's vrmlview.
You can use VRML viewer to visualize the geometry and events.
Thus, you can use and run Geant4 on your PC running Java (i.e., Windows,
Linux, Solaris, MacOSX etc.) with Gain to control the execution and
with your VRML viewer of your choice to visualize, while your simulation
is being executed on a remote compute server (maybe with bad Java support).