home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 18 REXX
/
18-REXX.zip
/
skeleton.zip
/
Skeleton.doc
< prev
next >
Wrap
Text File
|
1995-08-03
|
29KB
|
645 lines
The REXX Skeleton
A REXX Program Services Provider for You and Your Users
Author: Bob Rice - CompuServe: 72421,3016
Copyright (c) 1995 Empirical Heuristics
Documentation for Prolog version 1.0
________
Abstract
The REXX Skeleton is a code shell that is very easy to use when
developing a new REXX program, and fairly simple to retrofit into
your existing programs. It provides services to the user of your
programs as well as to you, the developer, during code development
and testing. Below is the feature list of services Skeleton performs
for you.
________
Audience
Skeleton is simple enough to use by a beginning REXX programmer and,
in fact, will likely provide substantial benefit as he or she learns
the ins and outs of REXX programming. For the more advanced REXX
programmer, Skeleton provides the convenience of getting started on
that next code file quickly and with a degree of standardization
that will prove useful as more and more code files proliferate.
Designed primarily for those of us who wish to avoid the overhead of
those GUI REXX development systems, Skeleton provides features and
services to each of your programs in a standardized manner.
____________
Feature List
Skeleton provides these features and services:
* Display of embedded help code at several levels:
+ Brief abstract and syntax only
+ The above with description of syntax and inclusion of usage
notes
+ The above with the addition of technical information
* Extraction of embedded help code to a file (possibly for later use
in the construction of a compendium of all your REXX programs).
* Automatic initialization of several "global" variables with values
specific to the particular program being run and the environment
in which it is running. These may be used by your program to
simplify your own code.
* Automatic external function registration.
* Automatic trapping of REXX execution time events and errors:
+ Events include error, failure, halt, novalue, and certain
syntax errors
+ Organized display of event information including the:
- name of the program experiencing the event or error
- type of event or error
- REXX interpreter error code
- description of the error code
- name of the dump file generated as a result of the event
- source line responsible for the event or error
- optional elaboration of the error code description
+ Generation of a dump file showing:
- an optionally sorted list of the names and values of all
variables visible to the program at the time of the event
- the contents of the current data queue, and the SESSION
queue as well, if they are not the same
+ Automatic display of the dump file and the program file with:
- Automatic positioning of the editor cursor on the source
line causing the error in the program file
- Ability to specify your favorite file editor and file viewer
* Debug assistance:
+ Sensitivity to the value of the TRACE environment variable or
the /TRACE parameter to provide code tracing without having to
edit the program.
+ Sensitivity to the value of the DEBUG environment variable or
the /DEBUG parameter to provide a "global" debug flag which you
can use to selectively execute portions of your code.
+ A handy debug procedure to dump all or selected variables and
their values to a file for examination when problems arise.
Full descriptions of these features and services are provided later
in this document in the FEATURE EXPLANATION section.
____________
Requirements
The REXX Skeleton requires only that you have REXX support enabled on
your OS/2 system, and that the EPM editor that comes with OS/2 is
available. Not all Skeleton features listed above will be available,
however, unless you also have REXXLIB installed on your system.
REXXLIB is a commercial library of external REXX functions available
from Quercus Systems. They currently have a demo version of REXXLIB
available for download as REXXLB.ZIP from library 11 of the PCVENA
forum on CompuServe, as well as from various other network and BBS
locations. Quercus Systems supports their products in section 11 of
the same forum. I might add that the while Skeleton uses only a very
few functions provided by REXXLIB, the package is rich in function
and is a very good investment for the beginning REXX programmer as
well as the more advanced programmer. See the section, REXXLIB
Availability, below for information on how to contact Quercus
Systems.
________________________
License and Registration
Copyright (c) 1995 Empirical Heuristics.
Permission is granted to any individual or institution to use, copy,
or redistribute this software so long as all of the original files
are included, that none of the files are modified, that it is not
sold for profit, and that this copyright notice is retained.
The REXX Skeleton package is Shareware with a $0 registration fee.
What, you say? Why not just call it Freeware? Because if you
register the software by sending an e-mail note to CompuServe address
72421,3016 with your name, company affiliation if any, and your
e-mail address, assuming you like and use the package of course, you
will be notified when bug fixes, enhancements, and additional
packages become available.
Here are answers to some frequently asked questions:
Q. Can I distribute Skeleton sources and/or executables?
A. You may redistribute the latest official distributions, so long
as no modification is made, without even asking for permission. You
can charge for the cost of the distribution media and a small copying
fee. You must not distribute beta versions. The latest official
distributions are available on CompuServe as file SKELETON.ZIP in
library 11 (Quercus Systems) of the PCVENA forum as well as library 6
(REXX/Other Language) of the OS2DF1 forum.
Q. Can I use the Skeleton code in my software?
A. Yes, so long as you make it clear in the product documentation
that Skeleton is not being sold, that the source code is freely
available, and that there are no extra or hidden charges resulting
from its use by, or inclusion with, the commercial product. Here is
an example of a suitable notice:
NOTE: <Product> is packaged on this diskette using Empirical
Heuristics' error handling utility. <Product> uses Skeleton to trap
and process REXX errors, providing information in dump files useful
in determining the source of the errors. Empirical Heuristics'
Skeleton is free and can be obtained as source code from various
sources, including on CompuServe as file SKELETON.ZIP in library 11
(Quercus Systems) of the PCVENA forum as well as library 6
(REXX/Other Language) of the OS2DF1 forum.
Q. Can I use the source code of Skeleton in my commercial
application?
A. Yes, so long as you include in your product an acknowledgment and
an offer of the original Skeleton package for free or for a small
copying fee, and make clear that there are no extra or hidden charges
resulting from the use of the Skeleton code by your product. In
other words, you are allowed to sell only your own work, not ours.
______________________
Warranty and Liability
This software is available to you "as is", that is, without any
warranty whatsoever of any kind. Empirical Heuristics excludes any
and all implied warranties, including warranties of merchantability
and fitness for a particular purpose. Empirical Heuristics
specifically excludes any warranty coverage for incidental and
consequential damages.
_________________________
Files Included in Package
See the file Skeleton.pkg.
____________
Installation
Installation is very simple. The easiest way is to copy all files to
a directory listed in the PATH statement in your CONFIG.SYS file. Be
sure no files with these names already exist in that directory, or
the copy command will overwrite them.
Alternatively, create a new directory to contain the files, copy them
there, add the path and name of the new directory to your PATH
statement, and then reboot.
You may discard the Skeleton.pkg file, although it might be handy at
some time in the future to retain it to identify the files belonging
to the package.
_____________________________________________________________________
__________________
USING THE SKELETON
____________
Getting Help
The first thing to note is that you can obtain help on using each of
the programs (except SkelTest.cmd) in the package by simply typing
its name on the command line followed by a space and a question mark.
For example, typing
Skeleton ?
will provide help regarding the Skeleton.cmd file. Any program you
write using Skeleton as its basis, utilizes the prolog in the
Skeleton to provide this kind of help. The other programs in this
package do not make use of the Skeleton, and instead have been
specifically coded to use TellHelp.cmd to provide help.
The programs will also accept ?? and ??? instead of ? to provide
additional help. In addition using ???? will place the help in a
file which you can then view with your favorite file viewer.
________________________
Developing a New Program
To begin work on a new program code file, copy Skeleton.cmd to a new
file. For example,
COPY Skeleton.cmd MyPgm.cmd
Now, edit MyPgm.cmd, add help information specific to your new
program, and develop your own program code immediately after the
comment box marked START OF PROGRAM. That's all there is to it!
Your new program now embraces all the features and services provided
by Skeleton.
A full explanation of how to use the Skeleton can be found by typing
skeleton ??? to view the information on the screen
or
skeleton ???? to dump the info to a file to view it
______________________________________
Adding Skeleton to an Existing Program
The procedure for adding Skeleton to your existing programs is quite
similar to that described above for a new program, except that
instead of developing your own code, you simply import your existing
code immediately after the START OF PROGRAM comment box.
________________________
Getting to Know Skeleton
If you want a quick demo of Skeleton to see what it can do for your
REXX coding efforts, you can do this very easily. First, take a look
at the code in the file SkelTest.cmd. Pay particular attention to
the comment blocks. Then, run SkelTest.cmd from the command line.
Notice how REXX handles the error. Try it again. Now let's make use
of the Skeleton.
Copy the Skeleton to a new file so we can work with it, maybe:
copy Skeleton.cmd SkelDemo.cmd
Now edit SkelDemo.cmd and paste the entire SkelTest.cmd file into it
just after the START OF PROGRAM comment block. Save the file and run
it from the command line. Notice how Skeleton handles the error.
First of all, the display of the error is quite a bit more organized,
but essentially it's the same information that REXX provides for the
error when the Skeleton is not used. But Skeleton goes the extra
mile, providing more information to help you debug your program by
offering, when appropriate, to elaborate on the error description,
and generating a dump file containing a list of all the variables,
and their values, that were visible to the program at the point the
error occurred.
Skeleton also makes it convenient for you to see the dump file by
offering to open it for you in your favorite file viewer (EPM by
default). Skeleton even offers to sort the file for you so the
variable names are in alphanumerical order. This is the default
option if you just press Enter at the prompt. You may also press v
to view the file without sorting. This may be useful when there a
very large number of variables and the sort process is too slow for
you. Or you can press n to skip seeing the file.
NOTE: Skeleton does not build this dump file if REXXLIB is not
installed on your system. Contact Quercus Systems to obtain a copy
of REXXLIB. See the end of this document for more information on
contacting Quercus Systems.
Page down through this dump file. Notice that the content of the
REXX data queue has also been captured. Take a good look at this
information. The program places only five lines in the queue. Why
are there so many? Have you ever played around with data queues and
had a dickens of a time trying to find out what was happening? Could
it be that some previous program left some data in the queue? That's
what has happened here. When you ran SkelTest.cmd and hit the
failure, REXX quit, leaving some data on the queue.
With Skeleton, extra data in the queue will no longer be a problem
since the queue is flushed of all data when Skeleton processes it.
To prove it, run SkelDemo.cmd again -- but not just yet because we're
not finished discussing Skeleton. You will notice only five lines in
the queue this time, those put there by the current run.
When you're done viewing the dump file, just close your editor or
viewer and Skeleton will then ask you whether or not you want to edit
the command file that failed with the error. If you respond y, the
default, it will open the file in your favorite editor (EPM by
default) and position the cursor on the line in error.
The dump file generated by Skeleton has the name of the failing
program and a file extent of .DMP, so if you need to, you can bring
that file into the editor (assuming your editor has the capability to
edit at least two files at the same time, which EPM does) as you edit
the command file.
The above is just some of the convenience Skeleton provides your
programs. Wouldn't it be nice if your users could send you the .DMP
file when a problem occurs? In addition, there is the embedded help
capability which makes it very easy for users to obtain help
information specific to your program, the trace and debug facilities,
the automatic external function registration, and the handy "global"
variables Skeleton provides, all of which are described in more
detail later in this document.
__________________
File Usage Caution
Programs employing Skeleton will generate a dump file when an error
or event is trapped. This file will have the name of the program
experiencing the error or event and a file extent of .DMP and will be
created in the current directory. The file is created without
checking if it will overlay any file by the same name.
Using a parameter of ???? to request embedded help be placed in an
abstract file will create a file with the name of the program and a
file extent of .ABS in the current directory. The file is created
without checking if it will overlay any file of the same name.
_____________________________________________________________________
___________________
FEATURE EXPLANATION
____________________________________
Embedded Help Display and Extraction
These features are discussed in the embedded help of the Skeleton.cmd
and TellHelp.cmd files. Type
Skeleton ???
and
TellHelp ???
for complete information on these features.
______________________________________________
Automatic Initialization of "Global" Variables
Type
Skeleton ???
for a list and explanation of these variables.
________________________________________
Automatic External Function Registration
In order for your programs to make use of external REXX function
libraries, they must be registered with the system so REXX can
recognize them. The program FuncReg.cmd is called by the Skeleton to
perform this function for you. This is a general purpose routine
that is not specific to the Skeleton (although it is required by the
Skeleton). You may call it at any time from the command line. As a
matter of fact, I suggest you call it from your STARTUP.CMD file to
ensure that the functions are automatically registered at boot time.
___________________________________________________________
Automatic Trapping of REXX Execution Time Events and Errors
These features are pretty well summarized in the Feature List above.
Perhaps the best way to see what this is all about is to create an
error and see what happens. To do this, edit Skeleton.cmd and insert
the line
a = b
just after the START OF PROGRAM comment and before the exit
statement, then type
Skeleton
on the command line. What you should see is the Skeleton trapping
the error (the value of b was never set), displaying it nicely in a
box on the screen, generating a .DMP file, giving you the opportunity
to view that file, and then opening your program file in the editor
with the cursor positioned on the line in error. Note that unless
you have REXXLIB installed, the .DMP file will not be generated.
NOTE: Don't forget to remove that a = b line from Skeleton when
you're done.
_______________________________________________
Specifying Your Favorite File Editor and Viewer
Two programs, ErhEdit.cmd and ErhView.cmd, are designed so that you
can specify your favorite file editor and viewer, respectively. Edit
these programs to use your favorites. The help in these programs
tell you what parameters will be supplied when they are called by the
error handler in Skeleton. As supplied, they use the EPM editor that
comes with REXX.
________________
Debug Assistance
Tracing
Tracing can be initiated in one of two ways. You can set the value
of the TRACE environment variable to a valid REXX trace instruction
parameter value. (See "OS/2 Procedures Language 2/REXX" online help
for an explanation of the trace instruction. You can see this
information by typing START VIEW REXX TRACE on the command line.)
You can set this value with the OS/2 SET command. For example, if
you wanted to set tracing to "?r", you would type
SET TRACE=?r
on the command line. To turn tracing off, type
SET TRACE=
on the command line.
In addition to the TRACE environment variable, you can also initiate
tracing by using the /TRACE parameter when invoking your program.
For example, if your program is called MyPgm.cmd, you would type
MyPgm /TRACE ?r
on the command line if you wanted to use the same trace parameter.
If your program requires parameters, you would place them after your
program name and before the /TRACE parameter.
Debugging
While no specific debug code is built into the Skeleton, you can use
the /DEBUG parameter to set the value of EH.debug to 1. Then you can
use the this variable in your code to control, for example, the
display of certain information about your program. For example,
/* your code */
.
.
.
if EH.debug then say 'Debug is turned on.'
.
.
.
Obviously, you can use this variable for other purposes as well, but
that's up to you. Its value will always be either 0 or 1.
In a manner similar to the TRACE environment variable, the DEBUG
environment variable can be set. However, its only permissible
values are 0, 1, and null. If set to 1, then EH.debug will be 1. If
set to anything else, EH.debug will be 0. Also like TRACE, the value
of the parameter will override the value of the environment variable.
_____________________________________________________________________
_____________________
TECHNICAL INFORMATION
The calling hierarchy of the various component commands:
Skeleton
|--ErhTrap
| |--AskUser
| | '--TellHelp
| | '--AskUser
| |--ErhEdit
| | '--TellHelp
| | '--AskUser
| |--ErhView
| | '--TellHelp
| | '--AskUser
| |--QueDump
| | |--AskUser
| | |--Exist
| | | '--TellHelp
| | | '--AskUser
| | '--TellHelp
| | '--AskUser
| '--TellHelp
| '--AskUser
|--FuncReg
| '--TellHelp
| '--AskUser
'--TellHelp
'--AskUser
________________________
General Purpose Programs
The ErhTrap program is intended solely for the use of the Skeleton.
You need not worry about it.
See the section Specifying Your Favorite File Editor and Viewer above
for information on the ErhEdit and ErhView programs.
The remaining programs are of a general nature and can be called by
you in your own code to make use of the functions they offer.
AskUser
Anytime you need to put a one-line query on the screen to ask the
user a question requiring a single character response, you can use
this program.
Exist
This program is handy for checking for the existence of one or more
files or directories. It's easier to use than the SysFileTree
function of REXXUTIL when all you're trying to determine is if a
file or directory exists.
FuncReg
This is discussed above in the section Automatic External Function
Registration.
QueCmd
Capturing the output of an OS/2 command and placing it in the REXX
data queue for use by your program is trivial with this program.
QueDump
This provides a debugging feature which enables you to dump the
contents of a data queue to a file so you can see its contents.
Handy whenever you are having problems with data queues.
TellHelp
Displays embedded help text from programs employing such help.
Optionally places the help text in an abstract file.
_____________________________________________________________________
_______________
PROGRAM SUPPORT
I am interested primarily in supplying you with quality software.
While I believe that the software I release is without bugs, I must
emphasize that it has been tested in a limited environment. Should
you discover a problem with this software on your system, I certainly
would like to know about it. I will work with you as best I can to
resolve the problem, and if it requires a change in my software, I
will make any appropriate changes.
I am also open to your suggestions for additional features or
enhancement of existing features.
I usually frequent the following CompuServe forum sections,
especially the last one listed:
Forum Section
-------- ------------------------
OS2BVEN 1 - OS/2 Shareware
OS2DF1 6 - REXX/Other Language
OS2SUPPO 10 - REXX/Lang. Quest.
PCVENA 11 - Quercus Systems
You can also reach me via e-mail on CompuServe:
Bob Rice - 74241,3016
Empirical Heuristics
P.O. Box 189
West Hurley, NY 12491
_____________________________________________________________________
____________
FUTURE PLANS
Skeleton is the basis for many of the utilities I write. I have
several under development now.
One of the utilities will scan your hard drives and catalog all your
.CMD files. Another utility will scan a REXX code file and build a
cross reference of all function calls. Still another utility will
monitor the OS/2 boot process and provide a log of how long the
system has been running from bootup to shutdown or crash. There's
even a utility to read CIS .MSG files and copy certain messages from
it to another file. These are still in the development stage and may
or may not become a reality, but this will give you some idea of my
plans.
I plan to release another Shareware (but probably not for Zero-cost)
package of these and other utilities that I have found useful and may
also be useful to you.
_____________________________________________________________________
____________________
REXXLIB Availability
If you wish to obtain REXXLIB, you may contact Quercus Systems at:
Quercus Systems
P. O. Box 2157
Saratoga, CA 95070
phones: (408) 867-7399, (800) 440-5944
fax: (408) 867-7489
bbs: (408) 867-7488
email: 75300.2450@compuserve.com
ftp/www: (coming soon)
_____________________________________________________________________
Document Data:
$Revision: 1.0 $
$Date: 03 Aug 1995 20:11:32 $
$Log: Q:/rxdv/skeleton/vcs/skeleton.do! $
Rev 1.0 03 Aug 1995 20:11:32
Initial revision.
