Rexx Language Association
2011 Symposium

Transforming THE to be more
than JUST an editor by using Rexx macros

Les Koehler

5 Dec 2011


Table of Contents

Abstract

Notes about this presentation

No profile

With profile

Macros

Example - SHOWS

Example - Favorite DIRS

Example - Virtual DIR

Example - VIEW

Example - SCANFILE

Example - RUN

Summary


Abstract

I will demonstrate Rexx macros that expand the basic operations of THE from those of a typical Eastern Orthodox Editor to a powerful tool that multiplies the productivity of the user.

We will explore some of the most used macros, as well as the less used but most powerful.

If time permits we can explore the code for individual macros, as needed.


Notes about this presentation

This presentation was written after the actual online demonstation given during the Symposium, where I used the headers herein as a guide to what I wanted to demonstrate.

I've attempted to reproduce the main points of the demonstration, both in prose and screenshots. Of course I can't guarantee a one-for-one correlation. There may be either more or less here!

This is not an "Introduction to THE", however it does include some of THE's basic features so you can see the expanded capabilities that improve productivity.


No profile

When run from the command window with the "-n" flag set, THE will display the current directory. Here I've navigated to the THE directory, so it shows the directory that it was launched from, just like it would if it was launched from a shortcut:


Just like Xedit, what you get is very basic. To actually start using THE, you have to become familiar with its documentation:

Help

Screen Navigation

Home key
Toggles between the command line and where the cursor was.
F12
Toggles between the file area and the prefix area.
Selecting a file to edit
From DIR.DIR:
Position the cursor to the entry of interest, either in the file area or prefix area, and press ALT-X. Note that a (dir) entry points to another directory and if selected will replace the current one. The '..' entry points to the next higher directory. You can also use the command line and the DIR command to switch to the directory of your choice.
From the command line enter:
the complete_filepath
Adding a file to the ring
Either navigate to a DIR and select a file as above, or simply use the THE command and specify a full filepath.
Navigating the ring of files - F2
F2 will take you to the next file in the ring of files.
File area
The file area is where you input or change the contents of the file you are working on. By default, the cursor must be in the filearea in order to use F12 to get to the prefix area and the Home key must be used to get to the command line.
Arrow keys
The arrow keys position the cursor within the filearea. If the upper, lower, left or right limit of the visible screen is reached, the screen will scroll appropriately.

Here are some screenshots, created by some of my macros, that show some of these default settings:


With profile

profile then gets control back and runs checkfile.the to compare the folder name against a list of "normal" folders, issuing a one time warning message if needed.

The final result looks like this:

The command line has been moved to the top, where I prefer it, there are reserved lines at the bottom to display the function and shift-function keys and the status line now shows the userid and screen dimensions.

Notice that there is no function key to navigate to the prefix area. That is because the filearea is no longer bounded and doesn't scroll automatically. This is more like how Xedit behaves, and what I'm used to. I can use the arrow keys or the number pad '+' key (from the filearea) to get to the prefix area.


Macros

The true power and flexibility of THE is in the macros you use. The ones supplied are just a starting point, demonstrating some of the things that you can do.

Here's a list of the macros that I have indexed for the Extended Help Facility that I wrote:
altered Display altered/new lines
append Append string to targeted lines
att Collect/insert Attachment filenames. See Note
bkup SET BACKUP for my USERPROF
both Issue a command against both split screen files
boxes Draw enhanced boxes
check_for_newest Compare thumbs to C drive for newest files
checkfile Check for non-owned disk/folder
clearpf Clear defines for pfkeys to revert to defaults
cmdsave Save cmdline commands for smart_enter for recall by retrieve
cmdx Extract setting and put cmd setting in command line
ctls Repository for various CTL sequences
decode Decode an encoded string
defkeys Define hot keys
defmouse Define mouse settings
delay Read and execute keybd keys, optionally returning key sequence
delaymsg Delay clearing of a msg by using DELAY to usurp CLEARERRORKEY
desktop Set or show if desktop is to be connected to lan
diff Improved version of Mark's original diff macro
dir_colors Set colors for DIR file
dirs Show popup to select from favorite DIRs
doline Execute the current line as a command
dolist Execute commands against a list of files
dostack Emulate Xedit stack... needs more work
drawchars Variable settings for drawing. Hex table included
editvx EDITV eXtended for easier use
Excel_Constants Get Excel Constants and add to bottom of file
explode Explode a .PKG file
ff Flip flop between files in the ring
fileencode Encode N lines of a file
filelist Build a list of a subset of DIR.DIR
fix_income_expense Tidy up HOA report
fix_path Fix the PATH setting to include MyRexxStuff
fix_pkg Fix .PKG files to point to recipients folders
fixdo Fix standalone DO statements by joining to previous line
fixfind Convert FIND() to WORDPOS()
fixoocmt Change ooRexx comments (double-dash) to Classic Rexx
fixpdf Change 4 dots to 3 dots to make a Table of Contents narrower
fixprops A model for multiple changes to a file
flow Flow text.
flscreen Emulate Xedit FLSCREEN command
format_dumpvars In process
get_unused_keys Find all unused keys
getvar Get tailoring variable
goodargs Generic routine for passing args for validating
helpx THE Help eXtended
helpx_user Help Extended user exit
helpxmenu THE Help Extended menu manager
helpxusermenu Helpx User Exit menu manager
how Tell/return how program was invoked
index_help_cmds Helpx indexing command
index_help_query Helpx indexing cmd
index_help_set Helpx index SET
index_help_sos Helpx index SOS
index_helps Index all helps
lesk_how Tell/return how program was invoked
leskl Rewrite of L. In progress
leskll Rewrite of LL. In progress
less Remove lines from the ALL display
listf Help maintain EDITV LISTF settings
locatecursor Emphasize cursor in filearea
me Insert Rexx code to self identify
more Add lines to the ALL display
msglog Sample code for writing to a message log
namefind Look up a name in the Tbird exported LDAP file
newfile Initialize a new file and update chicken tracks
nico Game
nico1 Game
noprof Edit a file w/o running the profile but w/additional cmds
note Create a note
ok Set flag to filter selected error msgs
oldfile Update chicken tracks and invoke CHECKFILE
oo2rexx Convert ooRexx comments to Classic Rexx
oofix Convert mainframe disallowed var chars to ooRexx standard
oofix Convert mainframe disallowed var chars to ooRexx standard
package Build zip files for an EXPLODEd .PKG file
packages Build a list of all the .PKG files in the current DIR
pause Collect THE information for RESUME. Defunct; use Hibernate
pickfile Resolve command/prefix/filearea for selecting a file
pkg Set/Add to a .PKG file
pkgprefix Set the pkg prefix string
pop Pop a setting that has been PUSHed - Incomplete
popcurs Pop the cursor setting
popdef Pop a DEFINE setting
poppf Pop a pfkey setting
prefixcmd Allow a THE command from the prefix area
prefixg Prefix Get - Incomplete
prefixhelpxmenu Drive the special Helpxmenu 'selection' from a list
prefixhelpxusermenu Drive the special Helpxusermenu 'selection' from a list
prefixll Prefix LL - Incomplete
prefixmark Prefix HH
prefixpt Prefix PUT
prefixxc Prefix copy to clipboard
prefixxfp Prefix copy from clipboard to file
present Change colors for presenting
profile Copy of my profile
push Generalized PUSH. Doesn't work all that well
pushcurs Push the cursor values
pushdef Push the DEFINE values
pushpf Push the pfkey settings so they can be changed and then popped
register_notes Notes from Rony on manipulating the Windows Registry
reload Quit and Redit the current file
reserveable_lines Display/return list of reservable lines
retrieve Retrieve a CMDSAVE line
rextry Experimental REXTRY for THE
rexx_colors Captured Rexx colors
rexxedit Execute Rexx commands from the THE/Xedit session
rexxfmt Format a Rexx/THE program. Doesn't handle ooRexx comments
ringlist Display a popup of all the files in the ring
rm Remove a file from the DIR
run Run the code being edited. Improved version of MH's RUNIT
scanfile Scan all the tiles of the filetype passed for a string
sendmail Send the mail item being edited
set_thumbs Set EDITV vars for thumb drives. Requires tailoring!
setpfkeys Set pfkeys and prose to display
showalph Show the alphabetic key settings
showdirs Show the preferred directories. Invokes DIRS
showecolor Show extended colors in a popup
showhex Show hex in a popup
showmouse Show mouse settings in a popup
showother Show 'other' key settings in a popup
showpath Show the system path setting
showpf Show the pfkey settings in a popup
shows Show a popup of all the SHOW... macros
smart_enter Enhance the ENTER key for Rexx code completion, etc.
splitone Split the lines of a one-lined Rexx program
statusarea Maintain the STATUSOPT area of the STATUSLINE
synonyms Set SYNONYM values
timeit Show the execution time of a macro
tosub Position to the subroutine called on the focus line
total Total the numbers in a marked block and insert the answer
uniqueid Emulate Xedit UNIQUEID command
usable_screen_size Calculate usable screen size
userprof My extension to PROFILE
version Display the version of Windows, THE and Rexx. Needs expanding
view View the Windows file
words Count the number of words to the target
xtohtml Convert an X2 edit sesstion to HTML. Wesley Miller
xtract Show an EXTRACT result
y A replacement for SOS EDIT, with added functionality


Example - SHOWS

Below are some screenshots of some of the first macros I wrote to help me with some of the various shortcuts that enhance productivity.

All of them use the POPUP command to display a selection menu that is navigated with the arrow keys.








Example - Favorite DIRS

It is usually the case that files of interest are scattered across multiple directories. Generally, this means that you do a lot of typing to either change directories or use the full filepath to edit the file.

This slows your productivity, not only from the typing itself, but also from the typing errors that you might make.

My solution to this problem is the DIRS macro, which produces this popup menu of my favorite folders for me to select from:


I have it defined as the CTL-D hotkey combination so it is always readily available.

The popup is built from Favorite and Ignore entries in getvar.the. See my other presentation:

OS and Rexx interpreter neutral application tailoring

Here I've captured only the first screen, as indicated by the blue horizontal separator line. It is optionally added when the drive letter changes.


Example - Virtual DIRS

THE can only have one DIR.DIR file in the ring, but this is often not sufficient for the way I like to work. To overcome this restriction, I've written a macro (y.the) that handles an arbitrary list of files just as if it were a DIR.DIR. For example:


Each .PKG file is a list of files that belong to that package of code. Essentially an inventory of the dependencies for the package. Selecting one with CTL-X, as shown earlier, adds that file to the ring, as you can see:


Although the above doesn't show it, such a list is not restricted to only one file path. It can point to files anywhere on the pc. The .PKG extension used here has special meaning to other macros that I've written to help me automate the process of creating 7zip files for my packages.

y.the also recognizes other special files that have extra data after the fileid:

Thus one hotkey (CTL-X) handles pretty much everything that might be a list of files. You might, for instance, create lists by project, programmer, department, programming language or any other criteria that makes sense to YOU!


Example - VIEW

The view macro is a front-end to the Windows 'Start' command. It uses THE commands to pass the fileid to Windows and then restores the THE window.

Its obvious use is for displaying Windows files from a (virtual) DIR. Not so obvious is the idea of putting file or internet references as stand alone entries within a comment block that you can use later when you're working on the code.


Example - SCANFILE

This macro, named after a VM/CMS program, scans files to locate a character string of interest. Options allow you to: The resulting file might look like this:
C:\MyTHEstuff\kok.the (HIT macro list - :14 1 ) -   'macro list ADD OK.0 0'
C:\MyTHEstuff\kok.the (HIT macro list - :26 1 ) - --    'macro list OK.0 ~' z
C:\MyTHEstuff\kok.the (HIT macro list - :41 1 ) - --    'macro list OK.0 ~' f
C:\MyTHEstuff\kok.the (HIT macro list - :42 1 ) -     'macro list ADD OK.'f ok.f
C:\MyTHEstuff\list.the (HIT macro list - :8 1 ) -  Syntax: MACRO LIST
C:\MyTHEstuff\list.the (HIT macro list - :9 1 ) -          MACRO LIST ADD MASTERKEY ~data
C:\MyTHEstuff\listf.the (HIT macro list - :8 1 ) -  Syntax: MACRO LISTF
C:\MyTHEstuff\listf.the (HIT macro list - :9 1 ) -          MACRO LISTF ADD MASTERKEY ~data
C:\MyTHEstuff\userprof.the (HIT macro list - :66 1 ) -   "MACRO LIST ADD RINGLISTORDER NAME_FIRST"
showing you the following information:

The file is a Virtual DIR, so positioning the cursor and pressing CTL-X will take you directly to that line number in the file. Another hotkey definition, CTL-F, will take you directly to the file, without positioning to the line.


Example - RUN

RUN executes the code that you're editing, without you having to save it. You can use it to experiment with changes to code or to simply execute some example you may have found. Output is captured by the command:
   rexxoutput file
having been issued by the profile.

It will try to ensure that the PATH is correctly set, but some BSF4OORexx code can confuse it.


Summary

The macros you've seen demonstrate elevating THE from the realm of "Just an editor" to that of a "Productivity tool", just as has happened with Xedit on z/VM with FILELIST, RDRLIST and others.