-----Original Message-----
From: John.C.Ford@HealthPartners.Com
[mailto:John.C.Ford@HealthPartners.Com]
Sent: Thursday, June 08, 2000 03:05 PM
To: VSE Discussion List
Subject: Rexx return code Trivia


REXX/VSE fans (others may bail out now):

In researching my "ARX0950E" problem, I found that REXX/VSE handles return
codes differently than other Rexx implementations I've worked with (VM, TSO,
OS2). Zero still means "all went well", and non-zero still means "something
went wrong". It's handling the "something went wrong" where the difference
comes up. And I guess it only matters if you're really bent on making Rexx
work EXACTLY the way you want (which means you're warped like me).

At first I was confused, then I thought I had found a documentation problem,
but I gradually figured out that REXX/VSE just works in a way that is
adapted to VSE. The REXX/VSE Reference manual is largely cloned from a
"standard" Rexx Reference (why not?), so this VSE-specific anomaly is
documented in an obscure (to me) fashion. I've spent a few hours chasing
this down, and I hope it is of SOME value so SOMEONE out there.

OK. Here's the deal.

In general, when you issue a command, such as...

  'ADDRESS POWER PDISPLAY LST,A'

....you get a return code (rc) you can test. As a general rule in all Rexx
implementations, return code 0 means no errors, > 0 means something didn't
work, and < 0 means you better stop what you're doing because something's
very wrong.

The TRACE command supports this notion, by defaulting to a mode (TRACE
NORMAL) where it will display a trace message for "any command resulting in
a negative return code after execution". This is also referred to as a
FAILURE of a command. You can also TRACE ERROR, for "any command resulting
in an error or failure after execution". The assumption is that an ERROR
(that isn't a FAILURE) means the return code is > 0.

So far, so good. Another aspect of Rexx that is affected by return codes is
Condition Traps. Not used often, but uses the same rules and terminology as
TRACE.

Sure enough the manual says, in the description of Condition Traps, "SIGNAL
ON ERROR traps all positive return codes ... SIGNAL ON FAILURE traps all
negative return codes", thus defining FAILURE vs. ERROR.

At this point, rc<0 means FAILURE, rc>0 means ERROR, right?

But wait... way down in 20.4.4 (Replaceable Routines and Exits, Host Command
Environment Routine, Return Codes),  there's also a table "Return Codes for
the Host Command Environment Routine", which explicitly says that return
codes greater than or equal to +13 indicate a command failure and "a TRACE
NEGATIVE condition and a FAILURE condition is trapped".

So, for the purposes of return codes as they affect tracing and condition
trapping, "negative" means "less than -12 or greater than +12". Go back to
the section on the TRACE NORMAL, and notice that they say "a negative return
code", not "rc < 0". If you accept, or at least understand, this twist of
semantics, then the main part of the Rexx Reference still makes sense. You
just have to remember this special definition of "negative".

Now, I suppose REXX/VSE does this because VSE normally uses return code +16
for disastrous errors (like in JCL, where the default is "ON $RC>=16 GOTO
$EOJ").

Regards,
-jcf
__________________________
VSE/ESA 2.3.2 CICS/VSE 2.3
John Ford @ HealthPartners
Minneapolis, Minnesota USA