RexxTool

RexxTool.cmd is a multi-function tool for Rexx. Most of the functions are things I needed at one time or another, but I have added some variations that I thought other people might want. Formatting Rexx code was the original purpose. It will indent lines correctly, correct the capitalization of variables and functions, and space words and symbols consistently. It can move THEN and THEN DO to fit the style you prefer. It can reformat comments in several ways. It can insert header and footer comments for routines. It can wrap some long lines to fit the page width, but not all of them. It will also check for some common mistakes, including unbalanced quotes, comments, and parentheses; unbalanced DO/END pairs; duplicate labels; and some cmd.exe or 4OS2 commands that I am likely to type by mistake. It will also warn about constructions that are not strictly errors but that I prefer to avoid. As a code analyzer, it will show all the subroutines, where they are called from and which external procedures and built-in functions they call. It can draw a tree diagram of a program or part of it, showing where each subroutine is used. It can show the external routines, built-in functions, and libraries a program depends on. It can show all the variables and where they are used. It can also extract one part of a program with all the procedures it depends on. It can insert code to count how many times each procedure is called. Most important, I have tried to make it practical for people to add more functions to it. Using it: The command line syntax is RexxTool.cmd <command> <filename> [<output filename>] [options] To start, try reformatting a Rexx script with the default options: RexxTool.cmd format OldFile.cmd NewFile.cmd RexxTool.cmd is written in my own particular style: RexxTool.cmd format OldFile.cmd NewFile.cmd -style=akm or you might prefer RexxTool.cmd format OldFile.cmd NewFile.cmd -style=alternate but those are just examples; all the individual options can be changed on the command line. For a list of options type RexxTool.cmd -config For more detailed documentation about formatting, type RexxTool.cmd help format To simply check for errors, type RexxTool.cmd checkonly OldFile.cmd -check=all RexxTool.cmd checkonly OldFile.cmd -check=error,warn,4os2,style You might also try RexxTool.cmd tree FileName.cmd which will draw a nice diagram showing where routines are called for a list of other commands, type RexxTool.cmd help Most commands have additional switches to control what is done or how information is shown Most of the documentation is extracted from the program's comments. It doesn't look elegant, but it is easier for me to maintain this way. Try RexxTool.cmd help for some basic help RexxTool.cmd -config for a list of command-line switches and their current values RexxTool.cmd help <subject> for a longer explanation of a switch or command RexxTool.cmd help all for information about all subjects, which is probably more than you really want. The file RexxTool.help is the output of this command. All commands are safe to use; the original file is never changed. Bugs: There's sure to be some. The only ones I know of are minor cosmetic things. But it has not been tested well on writing styles other than my own. Feedback and bug reports are welcome. Bug fixes are even more welcome. Limitations: RexxTool.cmd is intended for the original ("Classic" or RexxSAA) Rexx for OS/2. It does not understand Object Rexx. It should also work for Regina Rexx on OS/2 and Linux, but see Regina.txt. I have not tried it with Regina/Windows. It expects more-or-less valid Rexx code. If the error-checking task reports errors, you might want to fix the mistakes before accepting the reformatted text. The Recapitalization task will not recapitalize names of procedures or variables that are in quotes. It is impossible to do it with complete safety, so I do not try. Under OS/2 Rexx, the Tree command may fail on a file with deeply-nested subroutines (about 30 levels), with a "control stack full" error message. I don't know if there is anything more I can do about that. The only program I have run across that has that problem is PPWizard.cmd. You could work around it by using Regina, but OS/2 Regina has other problems with very large files. RexxTool.cmd assumes well-structured code. Meaning that a routine has only one entry point, and execution does not fall through to the next label. Like this: LabelA: if a == 1 then LabelB: do say a end If your program does things like that, you will want to avoid the -AddHeader and -ThenDo formatting options. And the Tree, Calls, Depends, and Extract commands may not be accurate. I have even seen a few examples of Rexx code with a label in the middle of a DO...END structure. It is legal in Rexx, but it seems like a bad design. A file like that will be indented correctly but the error-checking task will show a false warning about an unbalanced DO...END. Improving it: One of my goals is to make it possible for other people to add features to it. If you are interested in doing that, try RexxTool.cmd help Hack RexxTool.cmd help Types RexxTool.cmd help ToDo RexxTool.cmd help DevHelp and read the source, of course. There are many comments in it. Credits: This started because I wanted to learn Rexx. Much of the code that I looked at was hard to understand because the indenting was inconsistent, capitalization hard to read, the structure was not obvious, and comments were badly placed. I was surprised to find very few Rexx code formatters at all, and none that satisfied me. I tried writing a formatter and soon understood why there are so few of them. The best way to write a formatter is to break up the code into tokens, but writing a Rexx tokenizer was beyond my ability. Then I found the CheckFunc.cmd program by Toby Thurston, which contains a "mini-tokeniser". I have changed Toby's tokeniser almost beyond recognition, but it is the basis of the tokenizer in RexxTool.cmd. Also thanks to the Regina documentation, which explained some things better than the OS/2 Rexx documentation. Anton Monroe <amonroe5301@gmail.com> --------------------------------------------- RexxMerge.cmd has a couple of tasks that I moved out of RexxTool.cmd because they do not need the tokeniser. RexxMerge.cmd REPLACE <FileA> -from=<FileB> will update procedures in FileA by replacing them with the versions of those procedures from FileB. FileB can be a filespec, in which case all matching files will be searched for updateable procedures. I have a collection of frequently-used internal procedures (the ones in RexxTool.cmd that start with "0"). If I make a change to one of them in the master file, I can use RexxMerge.cmd to update any script that uses that procedure. RexxMerge.cmd IMPORT <FileA> -where=<procedure> will search the %path for an external procedure that matches <procedure> and import it into FileA, making it an internal procedure. See RexxMerge.cmd -help for the details. --------------------------------------------- These are some things I use with RexxTool.cmd, but it does not depend on them. standalone.btm I have a macro library that can be used by any Rexx program I write, but sometimes I want to convert the macro procedures to internal procedures. Usually because internal procedures are faster. This batch file does that using RexxTool.cmd to identify the external procedures used and RexxMerge.cmd to import them. indenter.btm is a 4OS2 batch file that is a front end to my Rexx and BTM formatters. I normally call it from a text editor, but it will work just as well from the command line. It depends on a number of other programs that you probably have already-- grep.exe, expand.exe, diff.exe, eautil.exe. I also use a side-by-side file comparer called tfc.exe. I do not include it here but it is in the ZtreeBold package ztb194a5_upd.zip at hobbes.nmsu.edu. Or as TadziosFileCompare_1-4.zip at hobbesarchive.com. You will need to edit indenter.btm to suit yourself. BTMTool.cmd Is a new project that I work on now and then. It is similar to RexxTool.cmd but for 4OS2 BTM files. So far, all it does is indent, recapitalize, check for errors, and show external dependencies. It needs more work, but it is useful in its present state. --------------------------------------------- I do not normally use Regina, but I thought it would be interesting to see if Rexxtool.cmd would work under Regina. I have done some minimal testing using Regina 3.9.5 on OS/2 and Linux. If you use RexxTool.cmd with Regina, let me know. If there are no Regina users, I probably will not try to improve the Regina support. Regina on OS/2: It works, but The -idle switch does not work under Regina. (I cannot get the SysSetPriority() from Regutil.dll to work) Not really a problem, because Regina does not seem to hog the CPU like OS/2 Rexx does. When doing a large file, Regina sometimes aborts with an error message "System Resources Exhausted". I don't know what that means and probably couldn't do anything about it. The DEPENDS command does not accurately find external commands, because SysSearchPath() doesn't seem to work. The third argument (the "pool") of VALUE must be in upper case Regina on Linux: It seems to work. I know of a couple of limitations: The -idle switch does not work. (as above) The progress display is not as good as on OS/2, because the SysCurPos() function from RegUtil cannot detect the current cursor position, and it seems to send ANSI control codes to stdout instead of the screen. If you redirect stdout, the progress display will be garbled and you will get ANSI strings in the redirected output. If you want to redirect stdout, the only workaround is to turn off the progress display with -progress=0. Regina on Windows: Has not been tested at all. I have re-written several routines to work around differences between OS/2 Rexx and Regina. If you want to add something and keep it portable, here is what I have found so far-- You can check the variables G.0OpSystem and G.0Interpreter to know the current operating system and interpreter. G.0Dialect is the kind of Rexx (RexxSAA or Regina) of the file being examined. It is normally the same as G.0Interpreter, but you can override that with the -dialect= switch. Never use SIGL in a function call, because Regina changes the value of SIGL =before= calling the function. Instead, do something like this OldSIGL = SIGL x = Foo(OldSIGL) Regina always uses the RegUtil library. If you tell it to load RexxUtil, it will silently translate that to RegUtil instead. --rewrote Init to check interpreter and load one or the other, to make it clear what really happens --on Linux load regutil (note lower case) RXU does not work with Regina --in DumpVars, I must use SysDumpVars instead DumpVars is the only place that needs RXU and is not normally used anyway Regina SysSetPriority() uses delta from 20 to -20, but I have not gotten it to work. In OS/2 Regina, SysSearchPath() does not seem to work. Regina variables and labels can have names with $#@ --Should not be a problem now. Tasks that create variables from variable names or labels use c2x(<name>) to avoid illegal variable names. Regina/Linux segfaults on SysCurPos() because it cannot get current row and column --wrote a ShowProgress for Linux, but it uncovered the next problem-- On Linux, SysCurPos() sends ANSI strings to stdout instead of the screen, so they get redirected, garbling screen display and redirected output --only workaround is use -progress=0 if redirecting stdout The OS/2 Rexx linein() function treats an End-Of-File character (Ctrl-Z, '1A'x) as an End-Of-Line, Regina treats it as a printable character. --Tokeniser now changes EOF to an EOL token. in OS/2, the ADDRESS CMD default environment is the shell. The Regina equivalent is ADDRESS SYSTEM, and ADDRESS CMD is the operating system without a shell. I have not discovered how to use ADDRESS <environment> in a way that works on both. If ADDRESS is really needed, the best I can think of is to use INTERPRET-- env = address() str = 'ADDRESS' env 'dir *.*' INTERPRET str in Regina, stream('c', 'query exists') returns 0 for STDOUT OS/2 Rexx returns '' returns '' for NUL OS/2 Rexx returns \DEV\NUL in Regina SysFileTree() does not find the NUL device, OS/2 Rexx returns <current drive>:\NUL