Re: [Bug-GnuCOBOL] using separately-compiled user-defined functions

[Simon Sobisch]

Am 16.08.2018 um 07:18 schrieb James K. Lowden:
> I had some difficulty understanding from the manual how to call a
> separately compiled user-defined function.  I have it working now, but
> think I have found a bug.  No matter what I do, the cobol runtime
> library searches only two places for my function:
> 
> 1.  /usr/local/lib/gnucobol
> 2.  the current working directory

Yes. That is actually what the manual *should* have told you. Please
provide a patch for gnucobol.texi to make the manual better.

The details that should provide you with the information needed follow.

GnuCOBOL will *only* look at its internal library search path when
resolving modules or functions.
The normal system paths (often $LD_LIBRARY_PATH or on Windows %PATH%)
will be searched by default because of the security issues you've mentioned.

The internal search path is COB_LIBRARY_PATH.

You can see its value by using `cobcrun --runtime-conf`.

In general the entries "." and the install directory will be appended
internally, the later one because this is where modules shipped (all
that you find in "extras" directory, currently only CBL_OC_DUMP) are
installed to.

If you 'really' want to use the system path you may add it (in this case
adding the two other paths before):

COB_LIBRARY_PATH=.:yourmoduledir:yourinstalldir:$LD_LIBRARY_PATH

You may either use the environment or the system-wide runtime
configuration file or a separate runtime configuration file to specify this.

> 
> My function:
> 
>     identification division.
>     function-id. HelloWorld.
>     
>     [...]
>     
> compiled as:
> 
>       $ cobc -m -free -o HELLOWORLD.so func/hello.cbl 
> 
> Notes:
> 
> 1.  uppercase required

That is actually not true.

If the UDF is not already available in the current COBOL process it will
be searched for using the paths specified by COB_LIBRARY_PATH and the
uppercase name.

You can make it available *before* the use by two means:

a) You use COB_PRE_LOAD (gets a shared object file without the
extension), this will be tried to resolve with the paths from
COB_LIBRARY_PATH (a full specified name including the extension in
COB_PRE_LOAD would be possible, too).
That way you can also combine multiple UDFs into your UDF-library and
preload it before anything is started.

Check `cobcrun --runtime-conf` to see if the resolve did work.


b) *very* dynamic: use a "dynamic COBOL UDF library" - just add an
additional mini-program "PROGRAM-ID. 'HelloLoader'." to your source (and
name the outputfile HelloLoader.so).
When starting the COBOL runtime nothing will be preloaded, before you
actually use your HELLOWORLD function you'd do

        CALL 'HelloLoader'
          ON EXCEPTION DISPLAY 'Hello functions not available!'

Using this way you will only load the UDF module if actually needed
*and* can do something if the module isn't found.
To even make this more flexible (did anybody ever said COBOL is
old-school?):

   EVALUATE your-var
     WHEN 'CONSOLE'
        CALL 'HelloConsoleLoader'
          ON EXCEPTION
             DISPLAY 'Hello functions not available!'
             STOP RUN RETURNING -1
     WHEN 'WEB'
        CALL 'HelloWebLoader'
          ON EXCEPTION
             DISPLAY 'Hello functions for web not available!'
             CALL 'HelloConsoleLoader'
               ON EXCEPTION
                 DISPLAY 'Hello functions not available!'
               NOT ON EXCEPTION
                 DISPLAY 'Fallback to Console'
             END-CALL
     WHEN 'X'
        CALL 'HelloXLoader'
          ON EXCEPTION
             DISPLAY 'Hello functions for X not available!'
             CALL 'HelloConsoleLoader'
               ON EXCEPTION
                 DISPLAY 'Hello functions not available!'
               NOT ON EXCEPTION
                 DISPLAY 'Fallback to Console'
             END-CALL
    END-EVALUATE
    WRITE log-rec FROM FUNCTION helloworld (yourparam)

Note:
UDF are by definition case-insensitive.


> 2.  current working directory require

See note above, you just did not specified any search path.
> 
> The manual says that LD_LIBRARY_PATH can be used to specify a search
> path for cobol modules.  I do not believe that to be true.

This would be a plain error. Please provide a patch to fix it.

> In any case, LD_LIBRARY_PATH should be the last resort: it is the
> variable that coerces the runtime linker into finding a library
> outside its configured search path.  That's considered a security
> weakness because unprivleged users can introduce (potentially
> malicious) libraries.  Better to rely on the RPATH, and to give
> users a convenient way to set the RPATH in the executable.

and even more better: COB_LIBRARY_PATH

> 
> If the above analysis is correct, may I suggest:
> 
> 1.  Do not coerce the searched name to be upper case.  Rely on the
> symbol as presented in the source code, verbatim.

As noted: UDF are by definition case-insensitive.
cobc/libcob "solves" this issue by generating upper-case function names
which are used by libcob to resolve them and for dynamic module loading
if the upper-case name is not already "in scope".

> 2.  Do not prefix the filename with "./" when searching for it.  Let
> ld.so do its thing.

ld.so get's only something to do if you
        cobc -lyourlib your.cob -o your.so
As soon as GnuCOBOL will even *try* to load your.so ld.so will try to
get the correct yourlib.so using LD_LIBRARY_PATH. (similar for the
library lookup with PATH on Windows).

> 3.  Make RPATH more convenient to set.

I see no need for this given the current options explained above.
Do you agree?

> 
> 4.  Update the manual to explain better how to make and use a
> separately compiled user-defined function.  

Yes, this should be done. Please provide a patch for gnucobol.texi.

> 
> --jkl
> 

Simon