Writing REXX and CLIST Edit Macros

Writing REXX and CLIST edit macros allows you to automate ISPF editor tasks with custom scripts. This tutorial provides step-by-step guidance and practical examples for creating simple macros. You'll learn the essential structure, common ISREDIT commands, parameter handling, error checking, and see complete working examples that you can adapt for your needs.

By learning to write macros, you can automate repetitive tasks, standardize operations, and extend the capabilities of the ISPF editor. This tutorial focuses on practical, working examples that demonstrate real-world macro writing techniques.

REXX Macro Basics

REXX macros start with setting the environment and using ISREDIT commands.

Basic REXX Structure

Every REXX edit macro needs:

• Address ISREDIT: Sets environment to ISPF editor
• "MACRO": Indicates this is an edit macro
• ISREDIT commands: Commands to interact with the editor
• Exit: Ends the macro

Simple REXX Macro Example

Here's a simple macro that adds a comment line at the top:

1
2
3
4
5
/* REXX Macro: Add header comment */
Address ISREDIT
"MACRO"
"LINE_AFTER 0 SET" "/* File Header */"
Exit

This macro inserts "/* File Header */" as the first line (after line 0, which is before line 1).

REXX Macro with Parameters

Here's a macro that accepts a parameter:

1
2
3
4
5
6
/* REXX Macro: Add custom comment */
Address ISREDIT
"MACRO"
Parse Arg comment
"LINE_AFTER 0 SET" "/*" comment "*/"
Exit

Invoke it with: MACRONAME "My Comment"

CLIST Macro Basics

CLIST macros use ISREDIT commands with CLIST syntax.

Basic CLIST Structure

Every CLIST edit macro needs:

• PROC 0: Indicates a procedure with no parameters (or PROC with parameters)
• CONTROL MAIN NOMSG: Control statement
• ISREDIT MACRO: Indicates this is an edit macro
• ISREDIT commands: Commands to interact with the editor
• END: Ends the macro

Simple CLIST Macro Example

Here's a simple CLIST macro that adds a comment line:

1
2
3
4
5
PROC 0
CONTROL MAIN NOMSG
ISREDIT MACRO
ISREDIT LINE_AFTER 0 SET "/* File Header */"
END

This macro inserts "/* File Header */" as the first line.

CLIST Macro with Parameters

Here's a CLIST macro that accepts a parameter:

1
2
3
4
5
PROC 1 COMMENT
CONTROL MAIN NOMSG
ISREDIT MACRO
ISREDIT LINE_AFTER 0 SET "/*" "&COMMENT" "*/"
END

Invoke it with: MACRONAME "My Comment"

Common ISREDIT Commands

These ISREDIT commands are essential for writing macros.

Line Manipulation Commands

Commands for working with lines:

• LINE_AFTER n SET "text": Insert line after line n
• LINE_BEFORE n SET "text": Insert line before line n
• LINE_DELETE n: Delete line n
• LINE_GET n LINE: Get line n into variable LINE
• LINE_PUT n SET "text": Replace line n with text

Search and Replace Commands

Commands for finding and changing text:

• FIND "text": Find text in the file
• CHANGE "old" "new" ALL: Replace all occurrences
• CHANGE "old" "new": Replace next occurrence

Range Processing Commands

Commands for processing ranges:

• PROCESS RANGE ALL: Process all lines
• PROCESS RANGE start end: Process lines start through end

Practical REXX Examples

Here are practical REXX macro examples you can use and modify.

Example 1: Add Header Comment

Adds a standard header comment at the top of the file:

1
2
3
4
5
6
7
8
9
/* REXX: Add header comment */
Address ISREDIT
"MACRO"
Parse Arg filename
"LINE_AFTER 0 SET" "/*"
"LINE_AFTER 1 SET" "/* File:" filename
"LINE_AFTER 2 SET" "/* Created:" Date()
"LINE_AFTER 3 SET" "*/"
Exit

Example 2: Remove Blank Lines

Removes all blank lines from the file:

1
2
3
4
5
6
7
8
9
10
11
12
13
/* REXX: Remove blank lines */
Address ISREDIT
"MACRO"
"PROCESS RANGE ALL"
Do i = 1 to 1000
  rc = LINE_GET(i, 'LINE')
  If rc <> 0 Then Leave
  If Strip(LINE) = '' Then Do
    "LINE_DELETE" i
    i = i - 1
  End
End
Exit

Example 3: Number Lines

Adds line numbers as comments at the end of each line:

1
2
3
4
5
6
7
8
9
10
11
/* REXX: Add line numbers */
Address ISREDIT
"MACRO"
"PROCESS RANGE ALL"
Do i = 1 to 1000
  rc = LINE_GET(i, 'LINE')
  If rc <> 0 Then Leave
  newline = LINE "/* Line" i "*/"
  "LINE_PUT" i "SET" newline
End
Exit

Example 4: Convert to Uppercase

Converts the entire file to uppercase:

1
2
3
4
5
6
7
8
9
10
11
/* REXX: Convert to uppercase */
Address ISREDIT
"MACRO"
"PROCESS RANGE ALL"
Do i = 1 to 1000
  rc = LINE_GET(i, 'LINE')
  If rc <> 0 Then Leave
  upperline = Translate(LINE)
  "LINE_PUT" i "SET" upperline
End
Exit

Practical CLIST Examples

Here are practical CLIST macro examples.

Example 1: Add Header Comment

Adds a standard header comment:

1
2
3
4
5
6
7
PROC 1 FILENAME
CONTROL MAIN NOMSG
ISREDIT MACRO
ISREDIT LINE_AFTER 0 SET "/*"
ISREDIT LINE_AFTER 1 SET "/* File:" "&FILENAME"
ISREDIT LINE_AFTER 2 SET "*/"
END

Example 2: Find and Replace

Finds and replaces text (CLIST version):

1
2
3
4
5
PROC 2 OLD NEW
CONTROL MAIN NOMSG
ISREDIT MACRO
ISREDIT CHANGE "&OLD" "&NEW" ALL
END

Example 3: Delete Empty Lines

Deletes empty lines (simplified CLIST version):

1
2
3
4
5
6
7
8
PROC 0
CONTROL MAIN NOMSG
ISREDIT MACRO
ISREDIT PROCESS RANGE ALL
ISREDIT FIND "" FIRST
/* Note: CLIST has limited loop capabilities */
/* This is a simplified example */
END

Parameter Handling

Both REXX and CLIST support parameters, but the syntax differs.

REXX Parameter Handling

In REXX, use ARG or PARSE ARG:

1
2
3
4
5
6
/* REXX: Get parameters */
Address ISREDIT
"MACRO"
Parse Arg param1 param2 param3
/* Use param1, param2, param3 */
Exit

Or with ARG:

1
2
3
4
5
6
/* REXX: Get parameters with ARG */
Address ISREDIT
"MACRO"
Arg param1 param2
/* Use param1, param2 */
Exit

CLIST Parameter Handling

In CLIST, use PROC with parameter count and & variables:

1
2
3
4
5
PROC 2 PARAM1 PARAM2
CONTROL MAIN NOMSG
ISREDIT MACRO
/* Use &PARAM1 and &PARAM2 */
END

Or access by position:

1
2
3
4
5
6
7
PROC 0
CONTROL MAIN NOMSG
ISREDIT MACRO
SET &PARAM1 = &1
SET &PARAM2 = &2
/* Use &PARAM1 and &PARAM2 */
END

Error Handling

Proper error handling makes macros more robust.

REXX Error Handling

Check return codes in REXX:

1
2
3
4
5
6
7
8
9
10
/* REXX: Error handling */
Address ISREDIT
"MACRO"
rc = LINE_GET(1, 'LINE')
If rc <> 0 Then Do
  Say "Error: Could not get line 1"
  Exit 8
End
/* Process LINE */
Exit

CLIST Error Handling

Check return codes in CLIST:

1
2
3
4
5
6
7
8
9
10
PROC 0
CONTROL MAIN NOMSG
ISREDIT MACRO
ISREDIT LINE_GET 1 LINE
IF &LASTCC <> 0 THEN DO
  WRITE Error: Could not get line 1
  EXIT CODE(8)
END
/* Process LINE */
END

Looping Through Lines

Looping through lines is common in macros.

REXX Loop Example

Loop through all lines in REXX:

1
2
3
4
5
6
7
8
9
/* REXX: Loop through lines */
Address ISREDIT
"MACRO"
Do i = 1 to 10000
  rc = LINE_GET(i, 'LINE')
  If rc <> 0 Then Leave
  /* Process LINE here */
End
Exit

Using PROCESS RANGE

Process all lines with PROCESS RANGE:

1
2
3
4
5
6
7
8
9
10
/* REXX: Process all lines */
Address ISREDIT
"MACRO"
"PROCESS RANGE ALL"
Do i = 1 to 10000
  rc = LINE_GET(i, 'LINE')
  If rc <> 0 Then Leave
  /* Process LINE here */
End
Exit

Best Practices for Writing Macros

Follow these best practices when writing macros:

• Test on Sample Files: Always test macros on sample files first
• Handle Errors: Include error checking and meaningful error messages
• Validate Parameters: Check that parameters are provided and valid
• Use Meaningful Names: Choose clear variable and macro names
• Comment Your Code: Add comments explaining what the macro does
• Limit Line Ranges: Use reasonable limits when looping (e.g., 10000 instead of infinite)
• Check Return Codes: Always check return codes from ISREDIT commands
• Make Macros Reusable: Design macros to work with different files

Creating and Storing Macros

Steps to create and store your macros.

Step 1: Allocate Macro Library

If you don't have a macro library:

• Allocate a PDS or PDSE for your macros
• Ensure it's in your SYSPROC or SYSEXEC allocation
• Set appropriate attributes (RECFM=FB, LRECL=80, etc.)

Step 2: Create Macro Member

To create a macro:

• Open your macro library in ISPF editor
• Create a new member with the macro name
• Write your REXX or CLIST code
• Save the member

Step 3: Test the Macro

To test your macro:

• Open a test file in the editor
• Type the macro name on the command line
• Add parameters if needed
• Press Enter to execute
• Verify the results

Explain Like I'm 5: Writing Macros

Think of writing macros like teaching a robot helper how to do a task:

• Writing a Macro is like writing instructions for a robot. You tell the robot step-by-step what to do: "First, go to line 1. Then, add a comment. Then, save the file." It's like writing a recipe that the robot follows!
• REXX and CLIST are like different languages you can use to write the instructions. REXX is like a more detailed language, while CLIST is simpler. Both can tell the robot what to do!
• ISREDIT Commands are like special words the robot understands. When you say "LINE_AFTER", the robot knows to add a line after another line. It's like having a special vocabulary for talking to the robot!
• Parameters are like giving the robot extra information. You say "Add a comment that says 'Hello'", and the robot uses "Hello" as the comment. It's like telling the robot what specific things to use!

So writing macros is like teaching a robot helper how to do editing tasks by writing step-by-step instructions in a special language!

Practice Exercises

Complete these exercises to reinforce your understanding of writing macros:

Exercise 1: Simple REXX Macro

Create a simple REXX macro: write a macro that adds a single comment line at the top of a file, test it on a sample file, and verify it works. Learn the basic structure.

Exercise 2: REXX Macro with Parameters

Create a REXX macro with parameters: write a macro that accepts a parameter and uses it in the operation, test it with different parameters, and verify parameter handling works correctly.

Exercise 3: Simple CLIST Macro

Create a simple CLIST macro: write a CLIST macro that performs a simple operation, test it on a sample file, and verify it works. Learn the basic CLIST structure.

Exercise 4: Macro with Looping

Create a macro with looping: write a REXX macro that loops through lines and processes them, test it on a sample file, and verify the loop works correctly. Practice line iteration.

Exercise 5: Error Handling

Add error handling to a macro: take an existing macro and add error checking, test it with error conditions, and verify error messages are displayed. Practice robust macro writing.

Related Concepts