=========================================================================
M I C R O F O C U S C O B O L T O O L B O X
V3.1.39
=========================================================================
THE COOPERATIVE PROCESSING DEMONSTRATION PROGRAMS
=================================================
TABLE OF CONTENTS
=================
INTRODUCTION
FILES PROVIDED FOR THE DEMONSTRATION
THE NETWORK
RUNNING THE DISTRIBUTED, CLIENT/SERVER APPLICATION.
One Machine, No Server
One Machine, One Service/Client
One Machine, Multiple Services/Clients
Two UNIX Machines, One Registration Process
Two UNIX Machines, Two Registration Processes
One UNIX Machine, One PC, One Registration Process
One UNIX Machine, One PC, Two Registration Processes
Other Combinations
Conclusion
INTRODUCTION
============
The Common Communications Interface (CCI) defined by Micro Focus provides
the ideal, simple interface required for co-operative processing. There
are several implementations of CCI available from Micro Focus for various
networks and protocols, all using the same interface. This means that an
application written for one implementation will also work with any other
implementation.
The implementation of CCI provided under Unix is CCITCP which uses the
Unix sockets library to connect via the TCP/IP ethernet protocol. There
are similar implementations of CCITCP2 provided with Micro Focus' DOS and
OS/2 products that allow co-operative processing between Unix and PC
platforms.
These notes describe a demonstration suitable for running with Micro
Focus' Unix products. The examples demonstrate how a user application
can distribute the user interface between machines.
These notes assume you have read the chapter on CCI in the Toolbox
Reference manual.
FILES PROVIDED FOR THE DEMONSTRATION
====================================
For the server, the following files are provided:
application source: customer.cbl
copyfiles: customer.cpb
ds-cntrl.v1
server routine source: appservr.cbl
For the client, the following files are provided:
client driver source: services.cbl
copyfile: services.cpb
selection routine src: select1.cbl
copyfiles: select1.cpb
ds-cntrl.v1
char screenset: select.s
GUI screenset: select.gs
DS simulation: dummydsa.cbl
application screensets: customer.s
customer.gs
DS simulation: dummydsb.cbl
You will also need the CCITCP support file:
CCITCP registration: ccitcp2
THE NETWORK
===========
For the demonstrations to work successfully, it is necessary that the
TCP/IP network is fully configured and working. This means that each
machine must have the ethernet hardware present, together with the
appropriate software drivers and that the network is correctly connected
together. Each machine on the network must have an entry in the
/etc/hosts file and must have a mfcobol entry in the /etc/services file
(See the chapter on CCI in the Toolbox Reference manual). Each machine
must at least respond to each other using the 'ping' command. In
addition, CCITCP uses the net broadcast facility. Some machines are
configure such that this is disabled. In this case the CCITCP2
environment variable will have to be used to direct service registration
to an appropriate machine such that broadcasts are not necessary. Where
networks are connected (eg. Unix ethernet to PC Token Ring network) via a
bridge, gateway or router, it is important that each machine is aware of
this. The 'route add' command may be required for this.
If a machine cannot broadcast, then ensure that the CCITCP2 environment
variable for client processes point to the server machine. Where
broadcasts are fully enabled, then the service registration process
ccitcp2 can be located anywhere on the network.
Note that the ccitcp2 process requires to be run with root or superuser
permissions.
RUNNING THE DISTRIBUTED, CLIENT/SERVER APPLICATION
==================================================
The demonstration program is a simple Dialog System application for Sales
Order processing. Dialog System must be present for the most effective
demonstration that uses the Graphical User Interface (GUI) on the PC.
However, the demonstration can be run without Dialog System being present
as two emulations programs are provided that effectively simulate Dialog
System running the select.s and the customer.s screensets.
The Dialog System demonstration program has been modified slightly to:
1) change the called program from 'dsrun' to 'appservr'
2) change the stop run to a go to start of program
It will be convenient to build up the demonstration in stages. If Dialog
System is installed, then Dialog System will control the screens. If it
is not installed, then the simulation programs will be called
automatically. To animate first set COBSW=+A. For debugging messages
set the flag debug-active to val-true in appservr.cbl.
First compile the following:
cob customer.cbl services.cbl select1.cbl
cob dummydsa.cbl dummydsb.cbl appservr.cbl
One Machine, No Server
======================
Run the customer program (CCITCP will not be used):
cobrun customer
this calls appservr, which notices there is not an environment variable
'appservr' set and so calls Dialog System. The application screen should
now be shown. Key data into the fields and select Save to write the
details to file. Then try the clear option and hit the Exit or escape
key. Notice that the program does not end; this is because when it runs
as a server we do not want it to stop but to disconnect and continue
ready for the next client. Use the Unix interrupt or kill keys to stop
the program.
If you experience any problems with the screen display or the keys
available, then check that the environment variable TERM is set to the
correct value for your terminal and that the corresponding terminfo entry
has all the terminal information required by the COBOL system.
One Machine, One Service/Client
===============================
If there is no ccitcp2 process running on your machine, then start it up
now. Log in with superuser privileges and run the ccitcp2 executable as
a background process:
ccitcp2 &
Alternatively you can check what is happening by turning on debug
displays:
ccitcp2 -d
Exit and login as a normal user. Start up the server by setting the
number of services in the environment variable 'appservr':
appservr=1
export appservr
cobrun customer
Note: When using the appservr environment variable, if you do not
start the ccitcp2 process before running the demos you will get
the message "Invalid session ID given" and run-time error 154
("PERFORM nested too deeply"). If further attempts to run the
customer program fail, make sure that any remaining customer
processes are killed off by using the system 'ps' and 'kill'
commands.
It will display the message "* appservr version 3.0" and wait for clients
to attach. When you wish to close the service, use the UNIX interrupt or
kill key, the services will close down correctly (see the exit processing
in appservr.cbl).
Login and start up another process for a client. Run the services
program to select the service required.
cobrun services
It calls the routine 'select1' to provide the user interface through
Dialog System. Only the 'Customer' service is provided. Select it and
it will connect to the server. Key the customer code entered previously
and select Load to display the details. Exit the service and you return
to the list of services available again. You can repeat the connection
or exit back to the system prompt at this point.
What has happened is that the services program called the select1 routine
that allowed you to select the service. It returned the details to
services which then uses the CCITCP routines to establish a connection to
the service via the ccitcp2 process. Once connected it simply routes the
customer program's Dialog System parameters through to a local Dialog
System routine. Once the customer application flags the end of the
session, the connection is broken and the services program calls the
select1 routine once again.
One Machine, Multiple Services/Clients
======================================
This run is exactly the same as the previous one except that we set the
number of services available to two:
set appservr=2
export appservr
cobrun customer
Start up and run two client processes. Enter the same customer code as
before and load in both processes. Note that one of them will indicate
that the record is locked by another client. Try starting up a third
client process and you will find that it rejects the request saying that
the service is busy and that you should try again later.
What has happened this time is that the customer program calls appservr
as before and appserver notices that the environment variable 'appservr'
is set to two. Prior to starting up the service it carries out a system
call to 'fork' to duplicate the process. (Notice that the customer
application must have no files open at this point.) Two services are
registered with the ccitcp2 process: appservr and appservr2.
A client tries to connect to appservr. If the service is busy it tells
the client how many copies of that service is running and the client
tries each service in turn.
Two UNIX Machines, One Registration Process
===========================================
Both machines require the COBOL system to be installed together and for
the demonstration programs to be present and compiled.
Start up the service as in the previous run. Now login to another UNIX
machine to start up the client. First we need to indicate to the client
where the service registration process ccitcp2 is running (the default is
on the local machine) by setting the environment variable to the name of
the machine that is running the service. The name must be that used in
the /etc/hosts file:
set CCITCP2=machine-name
export CCITCP2
cobrun services
The appserver server routine starts up and registers with the locally
running ccitcp2 process. The client checks if the required service is
registered with the ccitcp2 process on the machine named in the
environment variable. The ccitcp2 process matches the client and server,
passing each the other machine's network address. The client and server
then communicate directly from then, rather than using the ccitcp2
process as a 'go-between'.
Two UNIX Machines, Two Registration Processes
=============================================
Start up the service as in the previous run. Now login to another UNIX
machine and start up a ccitcp2 process running in the background so there
is one such process on each machine. Now start up the client, this time
without setting the environment variable to indicate a remote ccitcp2
process.
cobrun services
The appserver server routine starts up and registers with the locally
running ccitcp2 process. The client starts up on the second machine and
checks if the required service is registered with the local ccitcp2
process. It will not be, so the ccitcp2 process broadcasts (assuming the
software/hardware configuration allows this) to everyone on the network
requesting the 'appservr' named service. Any ccitcp2 process running on
any machine on the network will hear the broadcast and check it's table
of registered services. If there is a match then it will send a message
back to the broadcasting ccitcp2 process. The broadcasting process will
take the first reply that offers the required service and pass the
address of the machine to the client. The client and server will not
communicate directly.
One UNIX Machine, One PC, One Registration Process
==================================================
The PC requires Micro Focus' Toolset or Workbench v3.0 product which
includes CCITCP2 in the bundled OSX product. The CCITCP2 software for
the PC is designed to work with PCTCP communications driver software from
FTP. This must be fully configured and working.
Copy the demonstration files from UNIX to the PC. The .cbl, .cpb and .v1
files should be copied as text ensuring the line terminators are
translated properly. The .s and .gs files should be copied as binary
files. Edit the first four lines of the appservr.cbl and services.cbl
program to select the appropriate environment. The first line should not
be changed as it is generally applicable. The next three are $set lines
giving compiler directives appropriate for the UNIX, DOS and OS/2
environments. Change the $ (dollar) symbol on the UNIX line to an *
(asterisk) and change the * to a $ on the line corresponding to the PC
environment. Then compile all the .cbl programs.
Start the service on the UNIX machine as before. On the PC, set the
environment variable CCITCP2 to the name of the machine running the
service and then start the client. If you have Dialog System installed,
then the client will use Graphical User Interface (GUI) mode, GUI
emulation or character mode as appropriate. If Dialog System is not
present, then a simulation will be run. Enter:
set CCITCP2=machine-name
run services
The client and server will be connected as between two UNIX machines.
One UNIX Machine, One PC, Two Registration Processes
====================================================
This can only be sensibly run from a multi-tasking environment: Windows
or OD/2. Run as in the previous example, except start up a local ccitcp2
process on the PC and omit the set CCITCP2 line when running the client.
The process is exactly the same as for two UNIX machines each running a
ccitcp2 service. Broadcasting must be available otherwise the client and
server will not connect.
Other Combinations
==================
The number of combinations is limited only by your imagination.
Any number of services and clients can be set up on any number of
machines on the network, PC and UNIX. Note that the appservr program is
set to spawn an arbitrary maximum of three service instances. This limit
can be readily increased by editing the source.
Where a machine is connected to a remote service using two registration
processes, should any problem develop on the service machine, a backup
service can be readily started up on another machine, perhaps even
locally. When the client next requests the service then it will
preferentially pick up the local service or can be redirected to the
backup service via the broadcast or by setting the CCITCP2 environment
variable.
Server and client can both use the CCITCP2 environment variable to point
to a ccitcp2 process running on a third machine. This might be handy for
debugging purposes or where one machine does not handle broadcasts
correctly.
The demonstration programs can be readily enhanced so that the services
menu lists several different network protocols to use apart from TCP/IP,
although these are currently only accessible to the PC processes.
The demonstration programs can be readily changed so that rather than
connecting via broadcasts or the CCITCP2 environment variable, the client
can directly request a named machine.
Conclusion
==========
The demonstrations listed above are intended to give an idea of the power
of co-operative processing using the CCI interface. The examples deal
solely with distributing the user interface. The Fileshare 2 product
uses the same CCI interface to distribute the COBOL file handling.
However there is no reason why applications cannot share other portions
of the workload between machines in a similar manner. The CCI technology
is very powerful and flexible yet relatively simple to use.
The example programs have been designed to be readily usable with any
existing Dialog System application. Just let the application call
"appservr" in place of "dsrun", move the Dialog System screensets to the
client environment and edit the select.cbl program to modify the service
selection menu.
=========================================================================
Micro Focus is a registered trademark of Micro Focus Limited.
Micro Focus COBOL Toolbox and Dialog System are trademarks of Micro Focus
Limited.
OS/2 and PC are registered trademarks of International Business Machines
Corporation.
Windows is a trademark of Microsoft Corporation.
UNIX is a registered trademark of UNIX System Laboratories Inc.
=========================================================================
@(#)/Vrn/coopdemo.1/3.1.03/15Jul93/nrV
Copyright (C) 1992-93 Micro Focus Limited