8.5.3 Regina Notes for the Variable Pool

Due to the subtleties described at the end of the previous
subsection, some notes on how Regina handles RXSHV_NEXTV requests
for compound variables are in order. The following rules applies:

·    Both the stem variable FOO. and the compound variable having
  FOO. as stem and a nullstring as tail, are returned with the name
  of  FOO.. In this situation, a sequence of  RXSHV_NEXTV requests
  may seem to return values for the same variable twice. This is
  unfortunate, but it seems to be the only  way. In any case, you'll
  have to perform the RXSHV_SYFET in order to determine which is
  which.
·    If a stem variable has not been assigned a value, its
  compound variables are only returned if they have been assigned an
  explicit value. i.e. compound variables for that stem that have
  either never been assigned a value, or have been dropped, will not
  be reported  by RXSHV_NEXTV. There is nothing strange about this.
·    If a stem variable has been assigned a value, then its
  compound  variables will be reported in two cases: Firstly, the
  compound variables having explicitly been assigned a value
  afterwards.  Secondly, the compound variables which have been
  dropped  afterwards, which are reported to have their initial
  value, and the  flag RXSHV_NEWV is set in shvret.

It may sound a bit stupid that unset variables are listed when the
request is to list all variables which have been set, but that is
about the best I can do, if I am to stay within the standard
definition and return a complete and exact status of the variable
pool.

If the return code from RexxVariablePool() is less than 128,
Regina is guaranteed to have tried to process all requests in the
chain.  If the return code is  above 127, some requests may not
have been
processed. Actually, the number 127 (or 128) is a bit
inconvenient, since it will be an problem for later expansion of
the standard. A much better approach would be to have a
preprocessor symbol (say,
RXSHV_FATAL, and if the return code from the RexxVariablePool()
function was larger than that, it would be a direct error code,
and not a composite  error code built from the shvret fields of
the requests. The RXSHV_FATAL would then have to be the addition
of all the atomic composite error codes.

(Warning: author mounting the soapbox.)
     The   right  way  to  fix  this,  is  to  let  the   function
     RexxVariablePool()  set another flag in shvret  (e.g.   named
     RXSHV_STEM)  during  RXSHV_NEXTV if and  only  if  the  value
     returned  is  a  stem  variable.  That way,  the  application
     programmer would be able to differ between stem variables and
     compound variable with a null string tail.
     
     To  handle  the  other  problem with compound  variables  and
     RXSHV_NEXTV,  I would have liked to return a null  string  in
     shvvalue  if and only if the variable is a compound  variable
     having  its  initial  value, and the stem  of  that  compound
     variable  has been assigned a value. Then, the value  of  the
     compound  variable is equal to its name, and is available  in
     the shvname field.
     
     I'd  also like to see that the  shvret value contained  other
     information  concerning  the  variables,  e.g.  whether   the
     variable  was  exposed  at the current  procedure  level.  Of
     course,  Regina  does not contain any of  these  extra,  non-
     standard features.
(Author is dismounting the soapbox.)

When Regina is returning variables with RXSHV_NEXTV, the variables
are returned in the order in which they occur in the open
hashtable in the interpreter. i.e. the order in which variables
belonging to different bins are returned is consistent, but the
order in which variables hashed to the same bin are returned, is
non-deterministic. Note that all compound variables belonging to
the same stem are returned in one sequence.


 PREV   NEXT