Path: utzoo!attcan!uunet!samsung!brutus.cs.uiuc.edu!psuvax1!psuvm!cjs
From: CJS@PSUVM.BITNET
Newsgroups: comp.lang.rexx,psu.vm.rexx
Subject: Re: Programming style
Message-ID: <89321.090814CJS@PSUVM.BITNET>
Date: 17 Nov 89 14:08:14 GMT
References: <89320.222332JXS118@PSUVM.BITNET>
Organization: Penn State University
Lines: 130

It is not merely a matter of style . . . it is proper coding vs.
improper coding.  (Or GOOD vs. BAD, or RUDE vs. POLITE or SMART vs.
STUPID.)

Any REXX EXEC or XEDIT macro that issues CMS and CP commands that is
going to be used by other than the author should have "ADDRESS COMMAND"
at the beginning, and should make external calls properly.

Here is an excerpt from an unfinished "REXX Programmer's Guide".

ADDRESS COMMAND and ADDRESS CMS

Here is an attempt at an explanation of when to use the ADDRESS statement
in Rexx.  Simply put, always use an "address command" statement in an
EXEC.  It will be faster and will be less likely to fail.  Here's why.

The Default

For an EXEC, the default environment to which a command is passed is CMS,
so that any interpreted line that is not a Rexx statement has the same
result as if the user typed that line on the terminal, that is, "full
command resolution".  Case does not matter, the user's synonyms are
checked, and the command can be any EXEC, module, or CP or CMS command.

EXECs with lines such as:

           l
           filel
           globalv select group list
           mytrash

may work, but are for personal use by casual CMS users, not for public
distribution.

A Rule

A general rule could be to always code "address command" at the beginning
of an EXEC, but there are always exceptions, so the programmer must
understand CMS.

Usually one wants to be sure that CMS commands like GLOBALV, MAKEBUF,
LISTFILE, and so on, are exuecuted, and not a user synonym or EXEC with
the same name.

The statement "address command" (a synonym is address '') implies "basic
CMS SVC 202 command resolution", which essentially bypasses user synonyms
and EXECs with the same name as modules or CMS commands.  The command has
to be in upper case and should be in quotes so the value of a Rexx
variable is not substituted.  EXECs must have EXEC in front, since
"implied EXEC" is effectively off, and CP commands must have CP in front,
since "implied CP" is also effectively off.

The SVC 202 command resolution is also significantly faster than full CMS
command resolution.

Exceptions

Sometimes it is desirable to have full CMS command resolution.  Executing
a user-supplied command is a common example:

       say 'Enter a command, bozo:'
       parse external Cmd
       address 'CMS' Cmd

We cannot think of other reasons to use address CMS, other than pure
laziness.  Someone once commented that they use address CMS so that error
messages would be displayed on the screen.  But, the only message that
would be displayed is FILE NOT FOUND by ERASE, LISTFILE, RENAME, and
STATE.

This may be useful in development, but we think production EXECs should
check return codes from CMS command and take appropriate action, and we
don't think a production EXEC should let users see system error messages.

XEDIT

An XEDIT macro is a little different.  The command environment defaults
to XEDIT.  To issue a CMS command that does not display anything, address
command should be used:

      address '' 'GLOBALV SELECT BIPBOP GET SLIPSLAP'

XEDIT will not refresh the screen because it did not know a command was
issued to CMS.  When an XEDIT macro causes the screen to blink, it is
usually because a CMS command was issued without "address command".

For years, those with ASCII terminals have been unaware of this because
Yale ASCII is smart enough to know the screen hasn't been changed, so IT
doesn't re-paint it.  (But as some of us know, the I/O still takes
place!)

When issuing CMS commands that output to the terminal, the XEDIT command
CMS is better:

      'CMS EXEC NAMES'

XEDIT will refresh the screen after the command because it does not know
what the command did.

CP Commands

Nearly always, an EXEC or XEDIT macro that issues a CP command needs to
obtain the output of the command or, at least, check the return code.
The Rexx functions DIAG and DIAGRC are most convenient for this.  (A
"diagnose" instruction is the way a virtual machine can request a CP
service; diagnose instruction number 8 is a "console function", that is,
a command that is usually typed on the terminal.)

The output from the DIAG function is returned to the Rexx program rather
than the terminal.

One can code:

     call diag 8,'Q DETACH 100'

for which no output returned or checked.  Better would be:

     R = diag(8,'Q DETACH 100')
     /* now check R for messages */

Even better is:

     parse value diagrc(8,'Q DETACH 100') with cprc . msg
     if cprc <> 0 then . . .        /* Command failed */

There is seldom a reason to issue a CP command from Rexx like:

     'CP Q TIME'

unless you want the user to see the output from the command.