Goldwater Examples How-To
-------------------------

Contents
--------

A. Compilation and installation of Example Servers (tserver and ToUpper.pl)
B. Configuring Goldwater to Boot Example Servers
C. Starting The Goldwater Administrative Processes
D. Booting the Example Servers
E. The Example Services
F. Running the Test Clients and Viewing the Results
G. Viewing the Logfile
H. Stopping Goldwater
I. Going Alone
J. Quick Reference Guide



A. Compilation and installation of Example Servers
--------------------------------------------------
Building Goldwater will also build the example clients and servers in the
examples directory.  To make sure you can compile them again:

shell> cd examples
shell> make clean
shell> make
shell> ls

You should see the following files:
gwclient.pl   - Perl test client
gwtclient     - Binary test client (from C)
ToUpper.pl    - Perl test server
tserver       - Binary test server (from C)


The servers should be copied into a designated 'bin' directory.  
The configuration file (see next section) will define this directory to be
MYHOMEDIRECTORY/gwbin.  This directory probably won't exist yet so create
it now:

shell> mkdir $HOME/gwbin
shell> mkdir $HOME/gwlog 

Goldwater also creates some logfiles, and the example configuration file will 
define logfiles within MYHOMEDIRECTORY/gwlog.  Again this directory probably 
won't exist yet so the second mkdir above above addresses that.

Now you can copy the test servers into the gwbin directory.  You might as well
copy the test clients into this directory as well, so you can keep them all
together:

shell> cp tserver     $HOME/gwbin
shell> cp ToUpper.pl  $HOME/gwbin
shell> cp gwtclient   $HOME/gwbin
shell> cp gwclient.pl $HOME/gwbin


To summarise, we've built a selection of clients and servers and installed them
in a suitable directory where Goldwater may be configured to look.

We've also created a directory that Goldwater may write its log files.



B. Configuring Goldwater to Boot Example Servers
------------------------------------------------

The examples directory contains a configuration file suitable for use with the
example servers we've just built and installed.

There are several items within it that need to be edited to match your local
environment.  First make a copy of the example configuration file, and then
edit that copy.

shell> cp gwconf_eg1.xml $HOME
shell> vi $HOME/gwconf_eg1.xml

Change MYMACHNAME to be the name of your local machine, eg titania
Change MYHOMEDIRECTORY to be the path of your home directory.
For example, if $HOME is /home/chris then change MYHOMEDIRECTORY to be
/home/chris so that for instance exedir="MYHOMEDIRECTORY/gwbin" becomes
exedir="/home/chris/gwbin".


Once a configuration file has been created it needs to be compiled before
Goldwater can use it.

Goldwater looks for a compiled configuration file by examining the environment
variable $GWCONFIG.  We must ALWAYS have this environment variable set when
we are doing anything with Goldwater.  For this example we will point it at
$HOME/gwconfig.bin:

shell> export GWCONFIG=$HOME/gwconfig.bin

Now we can compile our XML configuration file into a binary form.  This is done
with the gwmkcfg command.  It takes as an argument the filename of the XML
configuration file to compile, and writes the binary form to $GWCONFIG.

shell> gwmkcfg gwconf_eg1.xml
Goldwater Configuration Compiler - v1.2 - (c)2002 netFluid Technology.

/home/chris/gwconfig.bin created - 3807 bytes


You should now find that file $GWCONFIG has been created:

shell> ls -l $GWCONFIG
-rw-r--r--    1 chris    users      3823 Mar 24 13:36 /home/chris/gwconfig.bin


To summarise, we've created our XML configuration file and set essential paths
such as exedir and logfile to point at suitable locations.  We've set the 
essential environment variable GWCONFIG to a suitable filename, compiled 
our XML configuration file and written it to $GWCONFIG.

Warning: Do Not Compile and Overwrite a Binary Configuration File Whilst
         Goldwater Is Running.  You Will Leave The System In An Unstable State!
         (gwmkcfg warns you at compile time if it needs to)


C. Starting The Goldwater Administrative Processes
--------------------------------------------------

Once the environment variable GWCONFIG is pointing to a compiled configuration
file, and the example servers have been placed in the directory referenced by
exedir="" within the configuration file, then we can start the Goldwater
application.

The first step is to start the Goldwater administrative processes.  These
set up the Goldwater applicaiton environment and provided the framework within
which our (example )application servers may be booted.

Start the administrative processes:

shell> goldwater start

A quick check will validate if everything is okay:

shell> ps -fe | grep guardian
chris    10572     1  0 Mar23 ?     00:00:00 guardian titania 1 1 42369024 16



D. Booting the Example Servers
------------------------------

Once Goldwater is running we can start our example application servers.
To do this we'll enter Goldwater's management tool in interactive mode.

shell> goldwater
Welcome to the Goldwater Administrator (version 0.0.9)

Type 'help' or '?' for a list of commands.

goldwater> 


This tool allows command line completion of commands, and a bash like shell
history.

The command we're interested in right now is 'boot'.  boot may be used with
several command line options, but for now we'll use it in its vanilla form:

goldwater> boot


This will boot two instances of tserver and two instances of ToUpper.pl
[ The number of instances booted is defined by the min="" parameter for each
  servers <server><class ...> entry in the configuration file ].

You can examine the servers that have been booted with the srvl command (or
sl for short):

goldwater> srvl
Currently booted servers:

Server         Class  ID     Domain          Pid   Done    FRst Status         
-------------- ------ ------ --------------- ----- ------- ---- ---------------
guardian       1      1      titania         22902 8       0    Ready          
tserver        1000   1000   titania         22933 0       0    Ready          
tserver        1000   1001   titania         22934 0       0    Ready          
ToUpper.pl     1010   1010   titania         22935 0       0    Ready          
ToUpper.pl     1010   1011   titania         22936 0       0    Ready          

5 servers listed from a total of 5 booted.


The interesting columns are 'Done' and 'Status'.
Done reflects the number of service requests satisfied by a particular server,
and 'Status' indicates what the server is currently doing.  When a server is
actively processing a request, the name of the service within that server that
has been invoked will be shown in the Status column.


If you want to see what services are exported by the servers and what functions
they invoke, then you can use the Service List command 'svcl' (or sl for short).

goldwater> svcl
Active Service Table:

Service                   Function        Class  ID     Domain          Done   
------------------------- --------------- ------ ------ --------------- -------
/C/abcd/svc01             service01       1000   1000   titania         0      
/C/abcd/svc02             service02       1000   1000   titania         0      
/C/abcd/svc01             service01       1000   1001   titania         0      
/C/abcd/svc02             service02       1000   1001   titania         0      
/perl/efgh/psvc01         ToUpper         1010   1010   titania         0      
/perl/efgh/psvc01         ToUpper         1010   1011   titania         0      

6 services listed from a total of 7.


Again this table gives you a 'Done' count for the number of requests for a
particular service that have been satisfied.
'Function' gives the name of the function within the server which should be
invoked to satisfy a request for the service.  All servers are identified by
their Class and ID.  These Class and ID pairs are cross-referenced with the
process-list table (srvl) to find the actual server process that is supplying
the requested service.  The process identified is then sent the request for
completion.



E. The Example Services
-----------------------

Three example services are provided by two servers - one written in C, the
other in Perl.

/C/abcd/svc01 and /C/abcd/svc02 are supplied by the C server 'tserver', and
/perl/efgh/psvc01 by the Perl server 'ToUpper.pl'.

The services perform the following tasks:
/C/abcd/svc01 takes an ASCII buffer, converts it to upper case, appends the
string 'Service01 made the above data uppercase' and returns the resultant text.

/C/abcd/svc02 takes an ASCII buffer, adds the string 'This text was added by 
service02' to the end of it, sends it to /C/abcd/svc01 to convert it to 
upper case and returns the resultant text.  This illustrates a service acting
as a client by calling another service.

/perl/efgh/psvc01 takes and ASCII buffer, converts it to upper case and returns
the resultant text.



F. Running the Test Clients
--------------------------

The simplest of clients gwclient.pl simply sends the string 'This is a test
string' to service /perl/efgh/psvc01 and displays the text buffer that is
returned.

The client gwtclient is just as simple as the perl version, but written in C.
It takes as an argument the name of a text file to send to service
/C/abcd/svc01.  Once it has sent it and received a reply the resultant text
is displayed.  Keep in mind that the bigger the file you send to /C/abcd/svc01
the longer it will take to process.


Whilst the services are converting the request data to uppercase you may watch
what is going on through the management tool.

Using the svcl and srvl commands you can watch the state of each server and
see the Done count of each server and service increment.  Note that the Done
count for a server will be equal to the sum of the Done counts for it's
services.

Also try tail'ing the goldwater logfile $HOME/gwlog/goldwater.log whist you
run the test clients.  You'll see the test clients attach and detach from the
Goldwater application, plus the logging generated by both the clients and the
servers.

Note that anything written to STDOUT or STDERR will be redirected to the
stdout and stderr files in $HOME/gwlog/.  It is particularly important to note
this if there are any problems with Perl servers.



G. Viewing the Logfile
----------------------

The logfile $HOME/gwlog/goldwater.log has a fixed format, and is thus very
easy to read.

Format:

Date Time Pid:ID:Service:LogType > .... log details ....

Date and Time are self explanatory,
Pid     - the PID of the client/server that is generating this log entry.
ID      - the SERVER ID of the server that is generating this log entry.
Service - the service within the server that is generating this log entry.
          For clients Service is just 'client'.
LogType - the type of log entry being written.  They are identified to aid in
          processing of the log, either visually or automatically.
          Types are: ERR - Error
                     DTA - Data Specific
                     FLW - Flow Control
                     DBG - Debug
                     INF - Information
                     AUD - Audit info
                     WRN - System Warning
                     SER - System Serious Error
                     IDB - Internal Debug Entries



H. Stopping Goldwater
---------------------

Stopping Goldwater involves two steps.
1. Halting the application servers, and
2. Halting the administrative processes.

You halt the application servers by issuing the 'halt' command at the goldwater 
prompt within the management tool.

You halt the administrative processes by exiting the management tool and
running:

shell> goldwater stop

at the shell command line.

If you have forgotten to shutdown the application servers from within the
management tool, Goldwater will stop them for you at this point.


If you get problems shutting servers down (a ps reveals they are still there)
then you can kill them off with the gwcipc tool.  This tool removes all
shared memory and other resources essential for the operation of Goldwater.
In fact, it removes ALL IPC resources currently assigned to the userid of the
user who runs this command, so USE WITH CARE!!!!!
You should rarely need this tool, but if you're having problems it will help
restore everything to a stable state.



I. Going Alone
--------------

You should now be in a position to try things out for yourself.  Here are a
few experiments that could be carried out.

1. Try modifying either the Perl or the C test client to call service
   /C/abcd/svc02.  A single invocation of the test client should then cause both
   /C/abcd/svc02 and /C/abcd/svc01 to be called, but NOT the pair in the same
   server.  The reason for this is that when service svc02 calls service svc01 
   it does so by queuing a Goldwater request - just like any client.  Now the o
   server that made this request will not complete until it has received the 
   reply, and so is busy.  Thus this server cannot satisfy the request for 
   service svc01 - or to put it another way, a server cannot satisfy its own 
   service requests. 
   This is why you see the other instance of 'tserver' satisfying the svc01
   request.

   Run the client for service /C/abcd/svc02 and watch the Done counts on both
   services and servers.  Also review the Goldwater logfile in $HOME/gwlog/
   use the Pid, Class and Service identifier sections of the log to track what 
   is going on.

2. Try getting the clients to call non-existent services.  Again review the
   svcl and srvl tables, along with the Goldwater logfile.

3. Try setting your own service name to point to a function within a server
   (done through the XML configuration file, which must be compiled before it 
   can be used).  This should prove to you that service names are completely 
   arbitrary.
   A service name may be a single word or hierarchical.

4. Can you see that Server ID of each booted server starts at that servers
   Class ID and increments for each server instance booted?
   What would happen if two servers were given Class ID's of 1000 and 1001
   respectively and both with min="" values greater than 1?
   Try this to see.
   What if servers are given the SAME Class ID's ?



J. Quick Reference
------------------

o Make sure GWCONFIG points to the compiled configuration file.
o XML Configuration files are compiled with gwmkcfg
  Warning: Do Not Compile and Overwrite a Binary Configuration File While
           Goldwater Is Running. You Will Leave The System In An Unstable State
           (gwmkcfg warns you at compile time if it needs to)
o Goldwater's Administrative Processes are started with 'shell> goldwater start'
o Goldwater's Administrative Processes are stopped with 'shell> goldwater stop'


-------------------------------------------------------------------------------
Chris Smith - 24/03/2002 - chris@nfluid.co.uk

