Joined: 03 Jan 2003
|Posted: Sat Dec 03, 2005 11:50 pm Post subject: Introduction to ISPF edit macros
|The basics of ISPF edit macros
ISPF edit macros let you create your own ISPF edit commands. You can use them simply to automate repetitive tasks, or to perform complex data manipulation. Macros can be as simple as a list of editor primary commands such as a series of CHANGE commands or they can be complex commands that read and merge files, create new files, display panels, format data or invoke other programs.
Edit macros are programs that invoke ISPF editor commands. They behave just like built-in ISPF editor commands.
The syntax for edit commands is almost the same as the syntax of the commands that you type into the editor command field. The only difference is that you can also extract values to variables or use variables in the commands.
Macros can be written in almost any language, but the language of choice is usually Rexx. For simple macros, CLIST is OK, but unless there is some insurmountable reason that you have to use CLIST (for anything), use Rexx instead. For very complex macros, it may be useful to take advantage of the speed of a compiled language like COBOL or PL/I. The samples here will be in Rexx.
Creating edit macros
To create an ISPF edit macro, create a new member in a library that is allocated to SYSEXEC or SYSPROC. The name of the member will be the name of the command. In Rexx, edit commands must be run in the ISREDIT subcommand environment, which is accessed by the Address ISREDIT statement. To use ISPF commands, use Address ISPEXEC and to issue TSO commands, use Address TSO.
Macros must start with a MACRO statement. From there on, the macro just issues edit commands as needed. A simple macro that does a few change commands:
/* Rexx a simple macro of 3 change commands */
"C ABC1 DEF1 ALL"
"C ABC2 DEF2 ALL"
"C ABC3 DEF3 ALL"
Usually, macros will use some programming logic rather than simply issing static commands. The same macro could be written as:
| /* Rexx a simple macro of 3 change commands */
Do a = 1 to 3
"C ABC"a" DEF"a" ALL"
You can access the contents of the data being edited, or editor settings by setting variables:
/* Rexx example of using variables in edit macros */
"(MYLINE) = LINE .1" /* get 1st line into variable myline */
"(X) = SESSION" /* get session type edit or view */
line = reverse(line)
"LINE .ZFIRST = (LINE)" /* replace first line with variable line*/
/* .zfirst is a built in label */
Now people with some edit macro experience will tell you that you can also write that last line as
Don't do it! For data assignments, get into the habit of using the name of the variable in parentheses instead of using the value of the variable. Why? Because ISPF does variable substitution on the value of the variable when it sees an ampersand or some other characters so that the value of the variable can affect the results. If you use the syntax that places the variable name in parentheses, ISPF does not do any substitution.
"LINE .ZFIRST = '"||line||"'"
Your macros can also take parameters:
/* REXX example of using parameters */
'C "'p1'" "'p2'" ALL'
As you can see, the change command uses standard Rexx substitution to create an edit command and that command is passed to the editor. You may also have noticed that if values of the variables in this example have quotes in them, then the final command may be an invalid edit command and the command could fail. Very rarely you may need to code around such problems. One way is to use the hexadecimal representations of strings in FIND and CHANGE commands and the Rexx c2x() and x2c() functions can be useful for this.
You can also add non-data lines to show information in the editor. You cannot, however, address the inserted information lines from within a macro, so you cannot change them once they are created.
Edit macros are always primary commands. You can write macros that act as line commands, but you must start them with a primary command and the line commands at the same time. It is awkward, but it works. There is a tool called LMAC, available on the web, that will allow you to write edit macros as line commands which do not require that you enter a primary command, but that capability is not a native part of ISPF.
Edit macros can be run in batch by running ISPF in batch to issue a program that starts the editor with the MACRO() operand. In this case the macro must end the editor with an END or CANCEL command.