Completing the Installation

With appropriate installation settings and procedures, Connector for Oracle communicates with versions 9i or later of Oracle.

To install the Acu4GL product, perform the following steps.

Step 1: Install Oracle

The Oracle RDBMS 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 gives 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.
  • Oracle's "scott/tiger" test schema, which can be used for testing. Micro Focus 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 accessing Acu4GL for Oracle (see your 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 2: Create a new run time system

In the following directions, the term run-time system refers to the run time shared object on systems where the ACUCOBOL-GT run time is a shared object and to runcbl on other systems, where the run time is static. The run time is a shared object on the following systems: AIX 5.1 and later, HP-UX 11 and later, and Solaris 7 and later. To check, look at the contents of the lib subdirectory of your ACUCOBOL-GT installation. If your distribution is a static distribution, complete steps 2a and 2b below. For shared library distributions, continue to step 2c. You must ensure that both the AcuCOBOL lib directory and the Oracle client library are both in your LD_LIBRARY_PATH or LIBPATH variables depending on the system for the runcbl -vv command to list the Acu4GL for oracle version.

Complete steps 2a through 2c below to create a new run time that includes the Oracle Acu4GL product. You may also link your own C routines with the run time 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 inserts what you had previously typed.

Execute the shell script ora_inst by typing the following command:

sh  ora_inst  

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 Technical Services.

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 is 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 in which 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 responds with:

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.

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

2b. Link the run time system

If you need to link in your own C routines, add them to the SUBS= line of the file Makefile.ora. See Working with C and C++ Programs for details on linking C subroutines.

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

make clean

to ensure that you have a clean directory in which to build your runtime.

Now enter the following command:

make -f Makefile.ora

or

makerun  

This compiles sub.c and filetbl.c and then links the run time system.

Make sure you have correctly 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 Technical Services.

If you are relinking your run time 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 run time system. Make sure it reports the version of Acu4GL for Oracle.

Shared libraries

If you have relinked the ACUCOBOL-GT run time 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 in which you are currently located.

If the version of Oracle is not listed in the version information, try using the command ldd coba4ora32.so to determine which shared libraries can not be 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 in which 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. Note that the correct version of the ORACLE_HOME/lib should be in your LD_LIBRARY_PATH. This might be ORACLE_HOME/lib64 or ORACLE_HOME/lib, depending on what the default is for your system. If a lib32 directory exists, the 64-bit libraries may be the default. Please refer to your Oracle release notes for more information.

If the version of Oracle is not listed in the version information, you can try using the command ldd coba4ora32.so to determine which shared libraries can not be located.

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 run time with a static link. Different versions of the C development system use different flags to accomplish this link. Consult the documentation for your C compiler to determine the correct flag for your environment.

Step 3: Copy runcbl to the correct directory

If the run time system is a statically linked runcbl, copy the new executable to a directory mentioned in your execution path. This file needs to have execute permission for everyone using the run time system. The copy step is not necessary when the run time system is a shared library.

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

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