C.2.3 Installing the Product

With appropriate installation settings and procedures, Acu4GL will communicate with version 7.3.3, or versions 8.0 and 8i of Oracle. To install the Acu4GL product, perform the following steps:

Step One: Install Oracle

The Oracle RDBMS, version 7.3.3, version 8.0, or version 8i, must be installed and configured prior to the installation of Acu4GL for Oracle.

We also recommend:

Oracle's SQL*Plus product, which is an interactive query tool. This is not mandatory, but it will give you quite a bit of flexibility. SQL*Plus allows you to do database work outside of COBOL, including interactive queries, table creation, table modification, and creation of views, constraints, and relationships between tables.
PRO*C, which can help if you have difficulty linking.
Oracle's "scott/tiger" test schema, which can be used for testing.

Acucorp does not provide these products.

Make sure all environment variables Oracle requires such as ORACLE_HOME, ORACLE_SID, and LD_LIBRARY_PATH (or equivalent, if necessary) are set up in the environment of each user who will be accessing Acu4GL/Oracle (see Oracle documentation for the list of variables required). Verify Oracle's setup and configuration using an oracle tool such as SQL*Plus. Also verify that the PATH references the necessary Oracle subdirectories.

Step Two: Create a new runtime

Complete step 2a through 2c below to create a new runtime that includes the Oracle Acu4GL product.

You may also link your own C routines with the runtime system.

2a. Execute the script.

The ora_inst script is an interactive shell script that determines which libraries your version of Oracle has, and then creates a makefile suitable for linking Acu4GL for Oracle. In the instructions below, bold italicized text within a message indicates that the script will insert what you had previously typed.

Execute the shell script ora_inst by enter the following command:

     sh  ora_inst

Note: You may exit the script at any time by pressing the system interrupt key (usually CTRL+C).

This is the first message that you see:

If this script dies with an error like "VAL=0: command not found", try
executing it with a bourne shell, as in sh ora_inst

If the script does terminate, and if re-entering the command does not work, call Acucorp Technical Support.

When the script begins executing, the following message is displayed (no response is needed):

We first need to determine where you have installed ORACLE.

If the environment variable ORACLE_HOME has been set, the script continues, and the next message you see will be the version inquiry below. If ORACLE_HOME has not been set to the Oracle directory name, the installation script displays this message:

Enter the directory where ORACLE is installed:

Type the name of the directory where you installed Oracle, and then press Enter. The script then determines whether a directory by that name exists; if not, the script displays the following message:

entered directory isn't a directory.

and returns to the Enter the directory prompt to give you another chance. After you have entered a legitimate directory name, the script asks:

Which version of ORACLE do you have installed?

Choose one of the following settings:

1) Oracle 7.3x
2) Oracle 8.0 (32-bit)
3) Oracle 8.0 (64-bit)
4) Oracle 8.1 (32-bit)
5) Oracle 8.1 (64-bit)

If you enter something other than the above choices, the script responds with:

Unsupported version of ORACLE: entered version

and returns to the "Enter the directory" prompt.

After you have entered a legitimate version of Oracle, the script checks the library subdirectory of the directory (this may not necessarily occur for Oracle, version 8.0) you entered above (or the one that was already named in ORACLE_HOME) for the presence of a specific library. If that library cannot be found, the script displays the following message:

ORACLE version entered version doesn't seem to exist in entered directory

and returns to the "Enter the directory" prompt. After you have entered a legitimate version number and libepcpt.a has been found, the script checks the library subdirectory for the presence of the file osn_tab.o. If that file cannot be found, the script displays the following:

osn_tab.o does not exist in library subdirectory, which the installation of ORACLE should have created. Complete the
installation of ORACLE before executing this script.

The script then terminates; you should now go back and check your installation of Oracle.

If all is well up to this point, the script checks for other needed libraries, and displays them.

The next message you see includes the libraries and:

Checking for -lnsl or -lnsl_s

followed by:

using -lnsl
        -or-
using -lnsl_s
        -or-
neither found
Creating Makefile.ora ...
You should now be able to execute a make with the command make -f Makefile.ora in the ... <ACUCOBOL-GT directory>/lib

These are just informative messages.

Note: Be sure to review the "makefile.ora" file and make adjustments as necessary.

2b. Link the runtime system.

If you need to link in your own C routines, add them to the SUBS= line of the file "Makefile.ora". See Appendix C in Book 4, Appendices of the ACUCOBOL-GT compiler documentation for details on linking C subroutines.

Make sure you are in the directory containing the ACUCOBOL-GT runtime system. Then, at the UNIX prompt, enter the following command:

     make -f Makefile.ora

This compiles "sub.c" and "filetbl.c", and then links the runtime system.

Notes: Make sure you have set all of the flags specific to your platform correctly before you relink your library and object files.

If the make fails because of an out-of-date symbol table, execute the following command:

     ranlib *.a

and then execute the make again. If the make fails for any other reason, call Acucorp Technical Support.

If you are relinking your runtime under SCO UNIX, you must add "-lrpc -lsocket" to the "LIBS" section of "Makefile.ora". If you place them on a line by themselves, remember to place a backslash at the end of the previous line. You must also remove these two libraries from the "ACUSERVER_LIBS" line.

2c. Verify the link.

Enter the following command:

     ./runcbl -vv

to verify the link. This returns version information on all of the products linked into your runtime system. Make sure it reports the version of Acu4GL for Oracle.

Shared libraries

If you have relinked the ACUCOBOL-GT runtime and receive an error message of this type when you try to execute it:

"Could not load library; no such file or directory"
"Can't open shared library . . . "

this may mean that your operating system is using shared libraries and cannot find them. This can occur even if the shared libraries reside in the same directory where you are currently located.

Different versions of the UNIX operating system resolve this in different ways, so it is important that you consult your UNIX documentation to resolve this error.

Some versions of UNIX require that you set an environment variable that points to shared libraries on your system.

For example, on an IBM RS/6000 running AIX 4.1, the environment variable LIBPATH must point to the directory where the shared libraries are located.

On HP/UX, the environment variable that must be set to point to shared libraries is SHLIB_PATH. On UNIX SVR4, the environment variable is LD_LIBRARY_PATH.

Be sure to read the system documentation for your operating system to determine the appropriate way to locate shared libraries.

A second way to resolve this type of error is to link the libraries into the runtime with a static link. Different versions of the C development system use different flags to accomplish this link. Please consult the documentation for your C compiler to determine the correct flag for your environment.

Step Three: Copy runcbl to the correct directory

Copy the new "runcbl" file to a directory mentioned in your execution path. This file needs to have execute permission for everyone who will be using the runtime system.

The ACUCOBOL-GT license file for the runtime ("runcbl.alc") and the license file for the Acu4GL product to Oracle ("runcbl.olc") must be copied into the same directory as the runtime executable. If you rename your runtime executable, be sure to rename your license files to use the same base name, with the extensions unchanged. For example, if you rename your runtime to be "myprog.bin", then the license file for the Acu4GL product for Oracle should be renamed "myprog.olc", and the license file for the runtime should be renamed "myprog.alc."

The remaining files can be left in the directory into which they were installed from the distribution medium.