14Edit macros – Create and apply

In this chapter, you will learn how you create and use edit macros. With edit macros will recurring tasks are performed quickly and elegantly. To get the full benefit of the ISPF editor, edit macros in my opinion are indispensable.

We have already extensively worked in the first part of this book on the operation of the ISPF editor; therefore, we now want get to know another very interesting part of the ISPF editor. There are many activities in ISPF where a certain automation may be helpful. These are, for example, the preparation and the SUBMIT batch jobs, the edit output lists, etc.

For such tasks, the use of edit macro is a very nice aid. This recurring work can be always greatly accelerated and facilitated. The SMART ISPF utilities contains a series of such useful macros. In the literature collection for ISPF there is a brochure in which next to the description of the manual operation of the editor, also the creation of edit macro is described.

This brochure is ISPF Edit and Edit Macros.

14.1What is an edit macro?

An edit macro is a REXX procedure that contains special commands for the ISPF editor beside the REXX commands. These edit commands are passed to the ISPF editor to run under the ADDRESS label ISREDIT. Of course, in an edit macro, all other commands are possible, which can occur in REXX procedures.

Edit macros can be executed as follows:

–Enter in the command line of ISPF editor the name of the edit macro procedure. This is the normal way to execute edit macro.

–Use the command EDIT DATASET(dsn) MACRO(name) in a REXX procedure.

–Define initial and/or end macros for editing data.

14.1.1Naming conventions for edit macros

The name of an edit macro must only correspond to those of REXX procedures. However, I have found in the course of my work in the ISPF that it may be well of advantage to use a naming convention for the edit macros. The advantage is that you can distinguish them from the rest of REXX procedures. I always start the name of my edit macro with the # character. This has the advantage that the names of my edit macro stand on the top in the REXX procedures data set directory consecutively. Even if I look for a template for a new edit macro, I need only look up the members that start with #. In addition, it is abundantly clear that you can never call an edit macro like a normal procedure. The commands that are addressed to the editor are only executable when the REXX procedure runs under control of the editor.

If an edit macro is called from within a REXX procedure using the EDIT command, I call it up the same way as calling the REXX procedure by prefixing the procedure name with the # character.

14.1.2Example of two very useful edit macros

Before we go into the details of programming edit macros, I want to show you a simple example what an edit macro can supply.

The first macro #SSS

The SMART ISPF utilities contain the program SSS. SSS stands for Smart Super Search. This program uses the standard ISPF program ISRSUPC to perform the search. This program produces a list output. This list is very elaborate. It contains many needless lines. I have therefore written an edit macro, which removes all unnecessary texts from this list. According to the naming conventions mentioned above, the name of the macro is #SSS.

The second macro #SSSCH

When the editor displays the resulting list of the search, you can change some lines in this list. If you then call the macro #SSSCH, the lines currently being edited replace the lines in the members. Using this technique, you can perform mass changes in all members of a PDS very easy and very quickly.

The program SSS works as follows:

1The program SSS is called by entering SSS in front of a DSN in a DSLIST display panel. The search will be performed for all members of this partitioned data set.

2The program then displays a panel, which is designed to enter the search arguments.

3After pressing ENTER, the program calls ISRSUPC and the search starts. The program ISRSUPC writes the search results in a temporary sequential data set.

4The ISPF editor is called in the REXX program using the following statement “EDIT DATAID(“UTID”) MACRO(#SSS)” The DATAID UTID was established by a LMINIT command earlier in the program.

5The macro #SSS removes all needless lines from the data set before the list is displayed.

Example for using of both above mentioned macros:

Task: I would like to know in which programs of the SMART ISPF utilities the ISPF service QUERYENQ is used.

Step 1:

I enter SSS in front of the PDS where the SMART ISPF utility programs are located. The following panel will displayed. In the field 1. = I enter the search text QUERYENQ.

Screen 14.1: Panel SSSP1 for entering search arguments

When enter is pressed, the search will performed and the following edit panel is displayed:

Screen 14.2: Resulting panel after executing a SSS search

The program ISRSUPC produces a list with LRECL=133. Therefore, the lines of this display are cut off on the right side. To see what lines by the macro #SSS were removed, here is the origin output of the program ISRSUPC:

Screen 14.3: Original output list of program ISRSUPC

As you can see, the list is reduced from 33 lines to 17 lines.

Step 2:

As you can see in line 487 of the program SLE, the word Paramter is wrong. I will now correct this error. First, I remove all unneeded lines and correct the wrong word to Parameter. Then the following edit panel remains:

I enter #SSSCH in the command line and press enter. The following display appears:

What shall the macro #SSS do with the list produced by ISRSUPC?

–Remove any blank lines.

–Remove all lines that start with the following texts: ISRSUPC, PROCESS OPTIONS USED, THE FOLLOWING PROCESS.

–Shift the lines where the name of the text SEARCH DNS: scanned data set appears together with the DSN as far to the left that the DSN text starts at column one.

–Remove the lines that begin with LINES-FOUND together with the next line.

–At the beginning of the revised text put a notice that this data set has been optimized by macro #SSS.

–Inserting a row by pointing out that using the edit macros #SSSCH, the edited and possibly changed lines can be written back to the members.

Here the source codes of both macros:

Program 14.1: Edit macro #SSS

Program 14.2: Edit macro #SSSCH

14.2Table of edit macro commands

Edit macro command types:

The edit macro commands are generally divided into two types:

First type: editor action command:

“CURSOR = line col”.

This command positions the cursor on line line and column col in the edited data.

Second type: assignment commands

This commands set values into variables:

“(line,col) = cursor”.

The variable line contains the cursor position of the current line and the variable col the column in the line of the data currently being edited.

As you can see in the following table, many edit macro commands offer both possibilities.

The following table is a condensed summary of the main edit macro commands as can be used in a REXX procedure. Of course, the IBM brochure Edit and edit Macros also contains a description of the edit macro commands. However, this is presented in a very confusing manner. Incidentally, this is one of the reasons why this book has been written. Therefore, I make an effort to present the reader a focused summary in the following table.

Table 14.1: Edit macro commands

14.3Operands and abbreviations used in the edit macro commands

To help you work with the macro commands as listed in the table above, please find below a brief description of those operands and abbreviations that are not always self-explanatory by their name:

Table 14.2: Operands and abbreviations of edit macro commands

Operands	Meaning
(var1,var2,..)	Here are some variables specified, depending on the function.
(var)	The name of a variable must be specified. This name must be not longer than 8 characters. If the (var) is on an assignment statement on the left side, the editor stores into the variable a value. If (var) is on the right side in an assignment statement, the REXX program must have been previously stored a value into the variable.
[FIRST] [LAST]	A search for the first or last occurrence of the text is performed in the data currently being edited.
[NEXT] [PREV]	Starts at the current cursor location and performs the operation forward [NEXT] or backward [PREV] in the data currently being edited.
[PREFIX] [SUFFIX]	The specified text is used in the search as a prefix or suffix.
[x] [nx]	The operation in question is performed only for EXCLUDED lines (x) or the NOT EXCLUDED lines (nx).
ALL	This operation will affect all lines of the data currently being edited.
amt	amt defines the relative number of elements in shift or jump operations. (amt = amount)
col-1 col-2	Two integers, which limits an operation on the designated columns.
col1 col2
data	Denotes a text enclosed in quotes.
labelname	Name of a labeled line. e.g. .AA, .XY etc.
label-range	Consists of two line labels of the form .LA and .LB. These can either be standard labels such as .ZF And .ZL or user-defined edit labels. The characters after the point may be just letters.
linenum-range	Two integer variable or constant that designate a start and an end line for an operation.
lptr col	Integers that contain a line number and a column number.
lptr-range	Two integers that specify the first and last line for an operation.
string	Text that does not have to be enclosed in quotation marks.

14.4Test aids in the creating macros

In this chapter, I will introduce the test facilities that can be used in the creation of edit macros.

14.4.1Prototyping

Unfortunately, there is no macro recorder for the ISPF editor available. I recommend the edit commands, before you use them it in a REXX program to test them by manually entering in the editor. Therefore, you should prototype commands after you have seen that the result is right, gather in a second data set using the clipboard, and then you can create the edit macro from this collection.

14.4.2The REXX TRACE command as developing aid

The undoubtedly most useful support facility in the creation of edit macro is the TRACE facility of REXX language. Here, mainly the variation of the TRACE command with the ?i option is helpful because it provides the complete development of contents of variables when executing a REXX command. By specifying ? you have instructed the REXX interpreter to stop after each command. This results in the ability to entering commands manually at this point. E.g. to display contents of any variables using the SAY command.

Example:

The following sample macro determines some values using macro commands. I inserted trace ?i at the beginning. Thus, the development of the variable is displayed and the macro stops after each command. I entered SAY commands to display contents of variables at the stop points.

Program 14.3:#TT1 – Using the TRACE command in the macro development

Here is the run of the macro. I have entered by hand (in gray) at some stops further macro commands. Of course, you can also enter any other REXX command there.

I entered the shaded commands by hand each time when the TRACE stops. As you can see, the echo print of the REXX commands contain the REXX source line number.

14.4.3The program ISREMSPY

During run of the macro, you can use the program ISREMSPY to look at the data currently being edited at this time. This program is a purely formal TSO program. Therefore, it must be run under ADDRESS TSO. It can only be used within an edit session or during the execution of edit macros. To demonstrate the application of this program, I wrote the following small macro.

Program 14.4: Example program for using the macro testing aid ISREMSPY

I called this macro in the edit session of the data set displayed on the following screen. On the pages thereafter, you will find the generated screens on each call of ISREMSPY.

I received the following displays successively during the execution of the macro. The program ISREMSPY inserted the shaded lines. You can see that these panels are provided by ISREMSPY program. I left each these ads with PF3.

14.5System variables of the ISPF editor

The system variables of the editor are valuable especially when creating an edit macro. The name of these variables is always preceded by a point. They can be used in the source code of the macro because they are actually line labels of the data currently being edited. I put these variables together in the following table:

Table 14.3: System variables of the ISPF editor

Name	Content
.ZCSR	Contains the line number where the cursor is currently located.
.ZFIRST	Contains the line number of the first row of the data currently being edited. You can abbreviate it with .ZF.
.ZLAST	Contains the line number of the last row of the data currently being edited. You can abbreviate it with .ZL.

14.6Passing parameters to macros

If call parameters should be passed to a macro, you have to define the MACRO command with a parameter list.

Format:

MACRO (parm1,parm2,..)

The variable names in macro parameters must not be longer than eight characters. parml and parm2 are variables that must be known in the calling REXX program.

Example:

The edit macro #ALTXT of the SMART ISPF utilities requires two or four parameters.

Program 14.5: #ALTXT – Use of parameter passing to edit macros

The Help panel of this edit macro:

14.7Examples for editing and SUBMIT batch jobs

Edit macros are often used to assemble and SUBMIT batch jobs. The SMART ISPF utilities contain three such macros:

Table 14.4: Edit macros of SMART ISPF utilities to assemble and submit batch jobs

#ISPFB	Edit macro to submit a batch job to execute the REXX procedure currently being edited within an ISPF environment.
#TSOB	Edit macro to submit a batch job that executes the REXX procedure currently being edited within a TSO environment.
#SU	Submit a JCL containing no JOB statement.

14.8 Mnemonics for macro programming

–If you do not yet have extensive experience in programming macros, remember to develop the complex statements by previous manual testing in an edit session.

–Use for testing the macros the REXX TRACE mechanism and the test program ISREMSPY. See section 14.4.3 The program ISREMSPY on page 249.

–Use the advantage the EXCLUDE statement offers. Most macro commands can be applied on both, the excludet lines (using the option X) as well as on the visible lines (using the option NX).

–If a command sequence does not have the desired success, perhaps it may be that the cursor is incorrectly positioned. This problem can be usually solved by examining the incorrect place of the cursor with a TRACE ?i pass and determining the position of the cursor manually as follows:

“ISREDIT (L1,C1) = CURSOR”
SAY L1 C1