Banking Demo Guide
==================

This demo is an example of a distributed application running over a network.
The application is in the domain of banking, and consists of three types
of "agents" - a directory server, a bank and an automatic teller machine.
The bank agent is written partly in Prolog and partly in Parlog while the
other two are written entirely in Parlog.

Parlog has been used for communication between agents across the network
using TCP.  Prolog has been used mainly for its database capabilities.
Since we have an interface to TCP from Prolog we could have written this
application entirely in Prolog.

Note:  The filename suffix indicates the type of file.
		Parlog source files	".par"
		Parlog executables	".o"
		Prolog source files	".pl"
		Prolog executables	".icp"



Background
==========

There are three types of agents in the demo example.  Here is a brief
overview.

Directory Server Agent
	This agent serves as the directory for services on the network.
	When an agents wishes to offer its services to other agents, it
	registers an address with the Directory Server.  The Directory
	Server stores this information in its database (in Prolog), and
	may answer queries about services.  When a service is terminated,
	the agent should ask the Directory Server to remove its entry from
	the database.  In our example, Banks register their service when
	they start up and de-register when they close down.  The Directory
	Server agent must be at a globally known address for the system to
	work.  This global address is defined in the file "dir_boot.par".

Bank Agent
	This agent offers a banking service to automatic teller machines
	(atm).  Atms can connect to a bank and process transactions such
	as depositing, withdrawing, transferring and querying.  The atms
	obtain the address of the bank through the Directory Server, so
	the Bank must register itself when it starts up.  The account
	information is held in a Prolog database, and three banks have
	been defined in the demo.

		bnp (Banque Nationale de Paris) - a/c nos. 10,11,12
		db (Deutche Bank)		- a/c nos. 20,21,22
		sbc (Swiss Bank Corporation)	- a/c nos. 30,31,32

	The account information is stored in executable form (e.g.
	account info for bnp is in file bnp.icp) and is loaded when
	the bank is started up.  Each account has a Personal Identification
	Number (PIN) associated with it.  For convenience, the PIN
	number for each account has been set to the account number
	(e.g. the PIN number of bnp account no. 11 is 11).  The account
	details are stored as relations of the form

		account(AC_NO, PIN, BALANCE, LIMIT)

	where BALANCE is the current balance on the account, and LIMIT
	is the credit limit (i.e. overdraw limit).

	Since the bank opens a new socket for every connection, the Bank
	Agent is able to process multiple connections concurrently (e.g.
	all three of its customers may be "logged in" at the same time).

ATM Agent
	This agent provides a way for a customer to access her bank account.
	The customer connects to her bank and thereafter requests transactions
	by sending messages to her bank.  The ATM agent is just a slightly
	modified generic user interface agent.  It contains no code specific
	to banking.  In particular, the ATM agent does not need to be altered
	when the Bank provides new services.



Setting Up the Demo
===================

If the demo is going to be run on multiple machines over a network, all the
remote machines must be able to display on the screen of the local machine.
You can ensure this by running

	xhost +

on the local machine before starting the demo.  This allows all machines
to connect to the X server on the local host.

Make sure also that the environment variable DISPLAY on the remote
machines refer to the local machine.  (N.B. this is done automatically on
many systems when you open a window on a remote machine, however you will
need to set it manually if you use 'rlogin' or 'rsh' to get on the remote
machine).

On all the machines, icp should be started in this directory (banking).
This is so that all the files may be located correctly.

The file dir_boot.par contains the port number of the directory server.  It
should be modified if the default port number (7890) is already in use
on your own system (unlikely).  If it is modified, you will need to
recompile the file under Parlog.



Running the Demo
================

1) Start a shell window (an xterm) for each agent (at least three) that you
   want to run.  The xterms can be on the local machine or on remote machines.
   Check that the DISPLAY environment variable is set to the local machine in
   all cases.  For best effect, run each window from a different machine.

2) cd to this directory (example/banking) in all the windows.

3) start icp in all the windows to go straight into parlog.  This can be
   done like this :

	icp -z parlog

4) In one of the windows, load the directory server code.

	| ?- load(dir).

   This loads the directory server program.  To run the server in the
   background type

	| ?- && dir.

   '&&' is a prefix operator which specifies background processing.  The
   prompt returns immediately for further Parlog queries.

5) In another window, load the bank program

	| ?- load(bank).

   Again, start it in the background as follows

	| ?- && bank(bnp).

6) You may wish to start up other banks (db or sbc) in the same way in other
   parlog windows.

7) In yet another parlog window, load the atm program.

	| ?- load(atm).

   Run it (in the foreground) by typing

	| ?- atm(bnp).

   or atm(db) or atm(sbc) depending on which bank you wish to connect to.

8) To connect to a bank, you will be prompted for an account number and
   a PIN.  See the Background section above for valid account numbers and PINs.

9) In the atm window, you can send messages of the following form

	1) credit(N)
	2) deposit(N)		same as 1)
	3) debit(N)
	4) withdraw(N)		same as 3)
	5) transfer(Bank, AC, N)
	6) info
	7) end

   where N is an amount (an integer), Bank is the name of a bank (bnp, db
   or sbc) and AC is an account number.  Remember that a message must be
   terminated by a "." (fullstop) since it is being read by the Parlog term
   reader.

10) Mutiple sessions may be connected to the same bank by running the atm
    program in yet more parlog windows.

11) The accounts database may be displayed by typing

	| ?- list_accounts.

    in the bank agent window.

12) The directory server may be stopped and resumed during its lifetime.
    To stop the directory service, type

	| ?- stop.

    in the directory server window.  When the directory service is not
    running, requests to transfer funds will fail because there is no
    way to find out the address of the destination bank (try it).  New
    banks will also be unable to start up as it cannot register its
    service.

13) To resume the directory service, type

	| ?- continue.

    in the directory server window.

14) To finish an atm session, send the message 'end.'

15) To close a bank, type

	| ?- close_bank.

    in the bank agent window.

16) To shut down the directory server, type

	| ?- end.

    in the directory server window.



NOTES:
======

1)  If a program was started in the foreground by mistake, e.g.

	| ?- bank(bnp).

    was typed instead of 

	| ?- && bank(bnp).

    there will be no prompt available at which to type 'close_bank.'
    To exit, you will need to type CTRL-C or CTRL-\.

2)  To exit Parlog or Prolog, type 'halt' or CTRL-D.

3)  If the directory service is temporarily stopped, it takes maybe
    a minute before the port can be resumed.  If an attempt to resume
    the service is made before it is ready, you will see the error
    message,

	Error: tcp_bind/3: eaddrinuse

    Just wait a while and issue the `continue' command again.
