#432 regutil35.pdf - RxFuncAdd & SysLoadFuncs confusing

v3.9.1
pending
Mark Hessling
None
5
2015-04-04
2014-08-02
LesK
No

Opened at Mark's request.
The doc says:
--- clip ---
1.3 Using RxFuncAdd
All the routines in RegUtil can be loaded either directly using RxFuncAdd, or indirectly
using SysLoadFuncs. RxFuncAdd takes three arguments – the name of the function as
it will be used in the rexx program, the name of the library from which to load the
function, and the name of the function as it appears in the library.
--- eclip ---

And later:
--- clip ---
2.1 SysLoadFuncs
sysloadfuncs() -> 0
SysLoadFuncs registers all the other routines in the utility package with the Rexx
interpreter. This registration takes less work on your part than registration using rxfuncadd,
and it’s probably faster to use sysloadfuncs whenever you need more than one
utility function, plus it’s less typing.
--- eclip ---

That leads the reader unfamiliar with handling Rexx function packages to think
that SyLoadFuncs can be used directly without using RxFuncAdd, which is NOT
true.

Discussion

  • Paul Kislanko
    Paul Kislanko
    2014-08-10

    This might work as an example. I have taken to using this fragment in any of my Rexx routines that use RegUtil functions:

    tst = value('RexxUtil_?','True',1) / has any other routine loaded RexxUtil? /
    if tst \= "True" then do
    call rxfuncadd 'sysloadfuncs', 'rexxutil', 'sysloadfuncs'
    call sysloadfuncs
    end

    the value(,,1) ensures that the RexxUtil_? variable exists for the life of this instance of the interpreter, since if any subroutine or function performs the sysloadfuncs they are available to all subsequently called subroutines or functions.

    I never call SysDropFuncs because there's no good reason to, but if I did the obvious requirement would be to do it as follows:

    tst = value('RexxUtil_?','False',1) / tell other routines they need to load utils /
    / if tst = 'True' then / not necessary per RegUtil doc / /
    call SysDropFuncs

    And generally, just a rewording of the documentation might make it clearer. Instead of
    "SysLoadFuncs registers all the other routines in the utility package with the Rexx
    interpreter."
    maybe
    "SysLoadFuncs performs an RXFUNCADD for all of the other routines in the package so SysLoadFuncs is the only routine for which you need to explicitly call RXFUNCADD".

    That doesn't scan too well either.

    Maybe just say

    "To include the utilities in your exec include
    call rxfuncadd 'sysloadfuncs', 'rexxutil', 'sysloadfuncs'
    call sysloadfuncs
    "
    and leave it at that.

     
  • Mark Hessling
    Mark Hessling
    2015-04-03

    Have made documentation simpler.

     
  • Mark Hessling
    Mark Hessling
    2015-04-03

    • status: open --> pending
    • assigned_to: Mark Hessling
    • Group: --> Next Release
     
  • Mark Hessling
    Mark Hessling
    2015-04-04

    • Group: Next Release --> v3.9.1