=========================================================================
M I C R O F O C U S C O B O L T O O L B O X
V3.2.20
=========================================================================
THE COOPERATIVE ANIMATION DEMONSTRATION
=======================================
TABLE OF CONTENTS
=================
INTRODUCTION
FILES REQUIRED FOR THE DEMONSTRATION
THE NETWORK
RUNNING THE DEMONSTRATION
UNIX Machine Preparation
PC Preparation
Starting the UNIX Session
Running The Animation Session on the PC
Conclusion
INTRODUCTION
============
These notes describe how you can use the Workbench Graphical User
Interface to Animator on a PC to animate a COBOL application running on a
remote Unix machine.
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.
The Micro Focus COBOL Toolset and Workbench products include a facility
for co-operative Animation whereby the animator presents the application
source code in one session whilst running the user application, typically
one that uses a Graphical User Interface (GUI), in a second session. The
two sessions are connected by CCI, typically CCINETB, and can either both
reside on the one machine or can each reside on separate machines that
are connected by a network.
This facility can be demonstrated with Workbench running on a PC and the
user application session running on a Unix machine. The two machines
must be connected by an ethernet network running TCP/IP. Please read
your Workbench documentation relating to Co-operative Animation and the
chapter on CCI in the Toolbox Reference manual before attempting the
demonstration.
Note that the Unix version of animuser is a prototype for demonstration
purposes only and is not suitable for serious development work.
FILES REQUIRED FOR THE DEMONSTRATION
====================================
The following are required:
A PC running OS/2 with an ethernet or token ring network card
A copy of FTP's PCTCP for OD/2 network software installed
A copy of Micro Focus Workbench for DOS and OS/2 V3.0 installed
(must be V3.0.24 or later)
A machine running UNIX with an ethernet card which is connected
to the PC network
A copy of Micro Focus Toolbox for UNIX V3.0 installed
You will also need the CCITCP support files from Toolbox:
CCITCP registration: ccitcp2
CCITCP library: libosx.a
and the user application harness components for Toolbox:
animuser.gnt
dbgee.gnt
A suitable simple example application to animate is the demonstration
program from Toolbox, pi.cbl.
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. For the PC, this must be the PCTCP software from FTP. 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 under UNIX.
RUNNING THE DEMONSTRATION
=========================
UNIX Machine Preparation
========================
Set up a working directory on the UNIX machine and copy the animuser.gnt,
dbgee.gnt and pi.cbl demonstration files into it. Compile the example
application:
cob pi.cbl
Build a COBOL run time with the CCI routines linked in:
cob -xve "" -o newrts -I CCITCP
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 &
PC Preparation
==============
Copy the files pi.cbl, pi.int and pi.idy from the UNIX machine onto the
PC, ensuring that the pi.cbl text file has the line terminators
translated so that the file is suitable for use under OS/2.
If you are confident that both the UNIX machine and the PC can handle
ethernet broadcasts correctly, then you can start up a CCITCP2 process in
a background OS/2 session. In general it is safer to enter the following
before starting up Animator:
set CCITCP2=machine-name
where machine-name is the name of the remote UNIX machine, as listed in
the /etc/hosts file.
Now start up Animator as a CCITCP service. Animator can be invoked from
the Workbench menu, character mode or graphical mode or from the command
line interface to Animator that is also available in Toolset. If the PC
is running OS/2 and you require the graphical interface, enter the
following at the command line:
anim2pm pi commstype(ccitcp) user-machine(coopanim)
For the character mode interface enter:
animate pi commstype(ccitcp) user-machine(coopanim)
If you select Animator from the Workbench menu, set the file to animate
to 'pi' and hit function keys F9 and F10 to enable and set the animator
directives. Remove the default parameter 'end' and enter
"commstype(ccitcp) user-machine(coopanim)".
Animator will load and register itself as a service and just wait until
the remote user animation session connects.
The name of the service will be "coopanim". If more than one co-
operative session is being conducted on the network, then each will have
to select a different service name in place of coopanim.
Starting the UNIX Session
=========================
Once the Animator service is started on the PC, then the UNIX session can
be started to connect to it. Enter the following:
./newrts animuser
or if the process name is "name" not "coopanim", then enter:
./newrts animuser user-machine"(name)"
All user application displays will appear on the UNIX terminal.
Running The Animation Session on the PC
=======================================
Once the UNIX session has started, there will be a pause whilst Animator
completes loading, and then the application source will be displayed.
You can now animate as usual. The speed of execution will be slower than
usual because of the network traffic between the PC and UNIX sessions.
The more monitors you have, the slower will be execution.
Note that all the application display appears on the UNIX terminal. Try
the Animator Do command, entering for example 'DISPLAY "Hello world!" AT
1010'. After a moments pause, you will see this appear on the UNIX
terminal. As the application is running on the UNIX machine, you can use
any C or UNIX system calls as normal.
Conclusion
==========
The demonstration given above is intended to give an idea of the power of
co-operative processing using the CCI interface. Although it is for
demonstration purposes only, it may be suitable for mixed C and COBOL
programming where the UNIX debugger sdb can be used on the UNIX terminal
with the COBOL debugging being carried out on the PC. The displays of
the two debuggers need not conflict.
The example shows how a user interface may be distributed. 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.
=========================================================================
Micro Focus and Animator are registered trademarks of Micro Focus
Limited.
Micro Focus COBOL Toolbox, Micro Focus COBOL Toolset and Micro Focus
COBOL Workbench are trademarks of Micro Focus Limited.
OS/2, PC and AT are registered trademarks of International Business
Machines Corporation.
UNIX is a registered trademark of UNIX System Laboratories, Inc.
=========================================================================
@(#)Vrn/coopanim.1/3.2.00/29Mar94/nrV
Copyright (C) 1992-94 Micro Focus Limited