
BOOMERANG SAMPLE PROGRAM
------------------------
------------------------

The Boomerang utility sample program demonstrates how you can 
use ACUCOBOL-GT, AcuConnect in thin client mode, AcuServer, 
and Oracle Pro*COBOL to maintain a relational database like 
Oracle on a UNIX server; pre-compile ESQL source files on 
that server; and then execute these programs on the server.  
Oracle Pro*COBOL is a pre-compiler that enables you to embed 
SQL statements in a host COBOL program and use that program 
to access an Oracle database.  The pre-compiler accepts the 
host COBOL program as input; translates the embedded SQL 
statements into standard COBOL CALL statements that call 
the Oracle libraries; and generates a source program that 
you can compile, link, and execute in the usual way.

When properly configured, the Boomerang utility sends the 
source file for pre-compilation to the UNIX server using 
AcuServer.  Using AcuConnect, it executes a script that 
starts the pre-compilation process.  The pre-compiled 
program returns to the client via AcuServer.  Finally, 
Boomerang compiles the program locally and sends the 
resulting object file to a specified directory on the 
client or server.

------------------------------------------------------------
Please note that Boomerang is not a supported ACUCOBOL-GT 
feature.  If you have any questions about the use of this 
utility, please contact our Systems Engineering department 
or your Acucorp Sales Professional.
------------------------------------------------------------

SYSTEM REQUIREMENTS
-------------------

In addition to the contents of the "boomerang" sample 
program file, the following system requirements must 
be met before you can run the utility.

You need the following components on the Windows client 
machine:

ACUCOBOL-GT development system (compiler and runtime) 
Version 7.0
ACUCOBOL-GT Thin Client Version 7.0
gzip utility version 1.2.4

You need the following components on the UNIX server 
machine:

ACUCOBOL-GT runtime Version 7.0
AcuServer Version 7.0
AcuConnect Version 7.0
gzip utility version 1.2.4
Oracle Pro*COBOL versions 9, 9i, or 10g

The gzip utility is not included with the Boomerang sample.  
It may be downloaded from www.gzip.org.  

PROGRAM SETUP
-------------

The "boomerang" directory contains the files you need to 
install before you can run the sample program.  The "server" 
directory contains a copy of the files you need for the server, 
and the "client" directory contains the files that should be 
placed on the client.  The following paragraphs briefly 
describe these files, along with any modifications you need 
to make to them in order to run Boomerang on your system.  

Server files 
------------

The "server" directory should be copied to the UNIX server 
machine.  You also need to create a "tmp" directory for 
temporary files and an "obj" directory to receive your 
COBOL object files.  Some files in the "server" directory 
need to be modified based on your individual implementation.  

The "acutools.cfg" file contains configuration file 
entries for AcuConnect and AcuServer.  ACCESS_FILE 
should point to the location of the AcuAccess file, and 
SERVER_ALIAS_FILE should contain the location of the 
thin client server alias file.

The script in "buildserver.sh" is used to compile the 
Boomerang utility "pcompile.cbl" on the server.  

The "init.sh" script changes the value of the PATH 
environment variable to include the absolute pathname 
of the ACUCOBOL-GT "bin" directory.  Use the dot command 
to invoke this script (i.e., ". ./init.sh").  You also 
need to set any necessary Oracle environment variables 
here, like LD_LIBRARY_PATH, ORACLE_HOME, and ORACLE_SID.    

The "startAcutools.sh" script is responsible primarily 
for starting AcuServer and AcuConnect with the correct 
parameters.  Update the port numbers in the script for 
these two server processes, if necessary.  This script 
also checks permissions (by calling "permOk.sh") and for 
the presence of the Pro*COBOL pre-compiler.  Note that 
the procob command must be in your PATH for this script 
to run.

The "killAcutools" script closes the AcuServer and 
AcuConnect processes.  Again, you need to update the 
port numbers in this script, if necessary.

The "permOk.sh" script checks ownerships 
and permissions.  

The "pcompile.sh" script executes the Pro*COBOL 
pre-compilation process on the server after being 
called by "pcompile.acu", the Boomerang engine.  

Client files
------------

The "buildclient.cmd" script is used to compile 
"pcompile.cbl" on the client.  The resulting 
"pcompile.acu" file should be copied to the 
ACUCOBOL-GT "bin" directory.  Other files in the 
Boomerang "client" folder must be also be copied to 
that directory.  These files include:

"boomerang.cmd", which launches the Boomerang process.  
Update this file to reference the "pcompile.acu" path, 
if necessary.
  
"boomerangDebug.cmd", which launches Boomerang in debug 
mode.  Update this file to reference the "pcompile.acu" 
path, if necessary.

The "sample" subdirectory contains the files needed to 
build and run the sample program using Boomerang:

"buildprg.cmd", which builds/compiles the sample program 
using the Boomerang utility

"runprg.cmd", which executes the sample program via 
AcuConnect

"sample.pco", a sample program that contains embedded SQL

"userpassw", which contains the sample program's 
COPY files  

Client environment 
------------------

Boomerang operation requires some modifications to client 
environment settings, as indicated:  

ACUSERVER_PORT and ACURCL_PORT to their respective ports 
on the server

COMPILERNAME to the "boomerang.cmd" path (or the 
"boomerangDebug.cmd" path)

COPYPATH to the directory containing the COPY files needed 
by the sample program (in this case, the "sample" directory)

PCOMPILE to the "pcompile.acu" path on the client

SERVERPROCOBSH to the path of the "pcompile.sh" script on 
the server; may be relative to the AcuConnect starting 
directory

SERVERPROCOBSTART to "pcompile.acu" on the server

SERVERTMPPATH to the "tmp" directory path on the UNIX server; 
may be relative to the AcuServer starting directory

TEMP to the temporary directory ("tmp") on the client machine

UNIQUENUMBERNAME to the name of a file shared by all client 
stations using Boomerang; this setting ensures that multiple 
users can pre-compile simultaneously

ACULOCALDEST to the path for resulting COBOL object files, 
if they are being stored on the client rather than the 
server; this setting is optional

PROGRAM EXECUTION
-----------------

After you have completed the setup, you are ready to run 
the Boomerang utility.  You should ensure that the ACUCOBOL-GT 
runtime is relinked to your Oracle Pro*COBOL libraries 
for the sample project to run.

1. Execute the "init.sh" script to change the PATH environment 
variable to include the ACUCOBOL-GT "bin" directory, as shown:

PATH=[ACUCOBOL-GT pathname]:$PATH

2. Execute the "buildserver.sh" script to compile the 
"pcompile.cbl" Boomerang source program on the server:

[ACUCOBOL-GT pathname]/ccbl -o @.acu -x -Ga -Zd pcompile.cbl

3. Ensure that the "AcuAccess" file reflects the appropriate 
ownerships and permissions.  "AcuAccess" and "acutools.cfg" 
files must be owned and writable only by root.  The local 
user, as defined in "AcuAccess", should have the read and 
execute permissions for the "pcompile.sh" script, which 
triggers the pre-compilation process.  

Modify the "permOk.sh" script to agree with your "AcuAccess" 
file.  If you map all the clients with a single local user, 
you should modify the "chown user:group pcompile.sh" line 
in the script, replacing "user" with the name of the local 
user, and "group" with the group of the local user.  If 
you map distinct client users with distinct local users, 
you should replace that line with individual commands that 
give the file's read and execute mode for each local 
user referenced in "AcuAccess".

Ensure that the server "obj" directory is owned by the 
local user and that the server "tmp" directory is 
accessible by all users.  

4. Execute the "startAcutools.sh" script to start the 
AcuServer and AcuConnect processes.

5. Execute the "buildclient.cmd" script to compile the 
"pcompile.cbl" Boomerang source program on the client: 
 
[ACUCOBOL-GT pathname]\ccbl32 -o @.acu -x -Ga -Zd pcompile.cbl 

Copy the "pcompile.acu" object file to the ACUCOBOL-GT "bin" 
directory, along with the "boomerang.cmd" (or 
"boomerangDebug.cmd") script.

6. Execute the "buildpgm.cmd" script to build and compile 
"sample.pco" with the Boomerang utility.

boomerang.cmd -o acurfap://[server-name]:[port-number]:
[server-object-directory-pathname]/@.acu -x -Ga -Zd 
-Lo listing.lst [client-sample-file-directory-pathname]\%1

where "%1" is the program name.  

7. Create your AcuConnect server alias file using the 
acurcl alias command.  

8. Run your program with the "runprg.cmd" script:

[ACUCOBOL-GT pathname]\acuthin [server-name]:[port-number] %1

where "%1" is the server alias name.  

