Building and executing Pro*COBOL applications on UNIX

Problem:

• How do I build Pro*COBOL applications on UNIX?
• Why, when executing my application, do I receive an RTS173 against SQLADR or SQLBEX?
• Why, when executing my application, do I receive an RTS114 against SQLBEX?
• Why, when executing my application, do I receive an RTS114 at program termination.
• Why, on HP-UX platforms do I receive an RTS118 at execution-time?
• Why, when executing my application with rtsora or rtsora32, do I can get an invalid magic number error against libwtc9.so?
• How do I call a Pro*COBOL application from Java ?
• Why, when compiling my application, do I get a procob not found error?
• Why, when compiling my application, do I get a procob18 not found error?
• Why, when relinking rtsora, do I get a "library could not be found" error?
• Why, when compiling my Oracle application, do I get an RTS114 against token ?

Resolution:

• Summary
• Background
• Oracle Environment
• Resolution

Summary

When using Pro*COBOL -- or the Cobsql preprocessor -- to precompile Pro*COBOL applications on UNIX, you need to be aware of the following information. Detailed reference material can be found later in this article.

Background

Pro*COBOL will precompile your EXEC SQL statements into one or more calls to internal Oracle APIs. In order to execute or debug your application, those calls will need to be resolved by the COBOL run-time.

If you are building your application to executable, linking your application to executable will resolve these API calls. We recommend that you base your build command-line on that as shown by the Oracle sample programs, under $ORACLE_HOME/precomp/demo/procob2 . Note that if you are using Oracle 10, the sample programs are only available from the Oracle Companion CD.

If, however, you wish to execute or debug your application as intermediate code (.int), generated code (.gnt), or as a callable shared object (.so, or .sl on HP-UX PA-RISC), you need to explicitly resolve those Oracle API calls prior to executing or debugging your application.

Oracle environment

Depending on the UNIX platform, Oracle may provide client-side support for 32-bit only, 64-bit only, or 32-bit and 64-bit. Under the Oracle installation directory, $ORACLE_HOME, you will typically see either :

lib32 lib

or

lib lib64

directories, which contain the 32-bit and 64-bit Oracle shared objects etc. respectively.

That is, the directory will be $ORACLE_HOME/lib for a 32-bit only Oracle product, and $ORACLE_HOME/lib32 or $ORACLE_HOME/lib for a combined 32/64 Oracle product, depending on whether you are operating in 32-bit or 64-bit mode.

We need to ensure that the setting of LD_LIBRARY_PATH/LIBPATH/SHLIB_PATH -- depending on the OS involved -- is set to the appropriate Oracle "lib" directory to match the effective working mode, i.e. cobmode, of the UNIX COBOL product.

If you invoke the "mfsupport" command, the resultant mfpoll.txt will show your current COBOL working mode, and also the setting of LD_LIBRARY_PATH/LIBPATH/SHLIB_PATH, to assist in verifying your current environment configuration.

Oracle's COBOL precompiler, Pro*COBOL will typically be provided as a 32-bit and 64-bit executable, named either procob/procob32 and procob64/procob for 32-bit or 64-bit environments.

The 32-bit and 64-bit versions of Pro*COBOL will generate different COBOL code, for example different sizes for data-items defined as USAGE POINTER, so it's important that you use the correct version of Pro*COBOL for your target environment. If you end up with a mismatch of Pro*COBOL environment against the COBOL working mode, you will likely see RTS114 errors at execution time.

Note that Cobsql does some verification of the user environment, along with which Pro*COBOL executables it finds on the PATH, to invoke the correct version. If, when using Cobsql, you get an error such as

"procob" not found

then either :

• The Oracle environment is not set up correctly
• You have not installed Pro*COBOL as part of your Oracle client installation. Note that the option to install Pro*COBOL is only enabled if your COBOL environment is set up prior to invoking the Oracle installation program.

If you pass the SQLDEBUG option to Cobsql, it will output the exact command it is trying to invoke. You should confirm that the Pro*COBOL executable it is looking for resides within your $ORACLE_HOME/bin directory.

If you're not sure which "bitness" the Pro*COBOL executables are, you should be able to use the OS command, file, to determine which is which. Here's what you'll see on a couple of the more common environments from executing:

file $ORACLE_HOME/bin/procob*

• x86-64 / Linux

  procob: ELF 64-bit LSB executable, AMD x86-64, version 1 (SYSV), for GNU/Linux 2.6.4, dynamically linked (uses shared libs), for GNU/Linux 2.6.4, not strippedprocob32: ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV), for GNU/Linux 2.6.4, dynamically linked (uses shared libs), for GNU/Linux 2.6.4, not stripped

• IBM System p / AIX

  procob:         64-bit XCOFF executable or object module not strippedprocob32:       executable (RISC System/6000) or object module not stripped

• Itanium / HP/UX

  procob: ELF-64 executable object file - IA64procob32: ELF-32 executable object file - IA64

• SPARC / Solaris

  procob:         ELF 64-bit MSB executable SPARCV9 Version 1, dynamically linked, not strippedprocob32:       ELF 32-bit MSB executable SPARC Version 1, dynamically linked, not stripped

• IBM System z / Linux

  procob: ELF 64-bit MSB executable, IBM S/390, version 1 (SYSV), for GNU/Linux 2.6.4, dynamically linked (uses shared libs), for GNU/Linux 2.6.4, not strippedprocob32: ELF 32-bit MSB executable, IBM S/390, version 1 (SYSV), for GNU/Linux 2.2.10, dynamically linked (uses shared libs), for GNU/Linux 2.2.10, not stripped

• PA-RISC / HP/UX

  procob:         ELF-64 executable object file - PA-RISC 2.0 (LP64)procob32:       PA-RISC1.1 shared executable dynamically linked -not stripped

If you have used the wrong Pro*COBOL executable to precompile the code, for example, you've used 'procob', but are running in 32-bit mode, you will most likely see RTS114 errors at execution time.

Resolution

On most UNIX platforms, the Oracle client-side libraries themselves require the threaded C run-time. You must therefore build and execute your application using the threaded COBOL run-time.

When you install the Pro*COBOL precompiler as part of your Oracle installation, the Oracle installer will relink the COBOL run-time to pull in Oracle client-side support. These files are located in your $ORACLE_HOME/bin directory, and are typically named rtsora or rtsora32 (for 64-bit and 32-bit support respectively). On 32-bit only platforms, the executable is typically named rtsora. The linking of these re-linked COBOL run-time modules will resolve the calls to the Oracle APIs, as generated by Pro*COBOL.

These executables are effectively a replacement for the threaded COBOL run-time executables as provided with Server Express, i.e. $COBDIR/bin/rts32_t or $COBDIR/bin/rts64_t .

In order to execute your Pro*COBOL application, you need to utilise the rtsora* executables as your trigger program, for example

$COBDIR/bin/rtsora32 my32bitapp.int$COBDIR/bin/rtsora my64bitapp.int

For debugging your application, you would have to set the COBSW environment variable to +A.

Should you wish to, you can -- after having made a backup! -- replace these rts??_t modules with the rtsora equivalent files, e.g. (logged in as the root user) :

mv $COBDIR/bin/rts32_t $COBDIR/bin/rts32.oldcp $ORACLE_HOME/bin/rtsora32 $COBDIR/bin/rts32_t

Having done this, you would be able to use the regular trigger programs, cobrun_t (for execution) or anim_t (for debugging) your application.

To avoid rebuilding the COBOL run-time to resolve the Oracle API calls, there is an alternate approach you can use. This approach will create a callable shared object, which you can then preload from your application, by compiling your source with the INITCALL "sharedobjectname" compiler directive.

If your application has a Java front-end -- i.e. you use cobjrun as the trigger -- or you are deploying your application under Enterprise Server , you must utilise this alternate method.

To create the callable shared object, firstly download makeorarts.zip from the Attachments link at the end of this article. You should then extract the makeorarts.sh script , and then execute the script as follows, having firstly configured your COBOL and Oracle environment :

sh ./makeorarts.sh

The script will create rtsora_t.so (or .sl on HP-UX PA-RISC) in your current working directory, which is the callable shared object. It will also rebuild the 'rtsora' executable in the current directory, as rtsora32 (32-bit) or rtsora (64-bit).

You can then compile your program with -C 'initcall "rtsora_t.so"' (or .sl for HP-UX PA-RISC platforms), and you will be able to execute or debug your application .

NOTE. If you are working on HP/UX platforms (both Itanium and PA-RISC), when using the second approach, you need to perform a couple of additional steps, otherwise you may receive an RTS118 error at execution-time. This is documented within the Server Express product readme .

If you are creating a callable shared object to resolve the calls to Oracle APIs, and you are working on either HP-UX 11.0 or 11.11 (11i), you may firstly need to install an operating system patch from Hewlett Packard. For HP-UX 11.0, you need to install PHSS_30969, and for HP-UX 11.11, PHSS_30970. Note that these patches may have been superseded by later versions, so you should install the latest recommended patch. For later versions of the Operating System, e.g. HP-UX 11.23,  no OS patches should be necessary.

Having installed the patch, you need to set an environment variable, LD_PRELOAD, to point to the Oracle client shared library, for example on HP/UX Itanium:

LD_PRELOAD=$ORACLE_HOME/lib32/libclntsh.so cobrun_t myapp.int

or on HP/UX PA-RISC :

LD_PRELOAD=$ORACLE_HOME/lib32/libclntsh.sl cobrun_t myapp.int

(for 64-bit HP-UX operation, substitute lib32 for lib)

If you wish to work with both Java and Pro*COBOL on HP-UX, you therefore need to build your application as follows :

# Compile the Pro*COBOL application using Cobsqlcob -itk mycobapp.pco -C 'initcall "rtsora_t.so" p(cobsql)'# Compile the main java program javac *.java# Compile the application to be called directly from Javacob -it mainapp.cblLD_PRELOAD=Oracle_lib_dir/libclntsh.so:rtsora_t.so cobjrun JavaClientAp

where Oracle_lib_dir will be $ORACLE_HOME/lib for a 32-bit only Oracle product, and $ORACLE_HOME/lib32 or $ORACLE_HOME/lib for a combined 32/64 Oracle product, depending on whether you are operating in 32-bit or 64-bit mode (see section 2. above for more details on this).