Primary Commands Reference

Primary commands are file-wide operations entered on the command line in the ISPF editor. Unlike line commands that operate on specific lines, primary commands perform global operations like searching, replacing, saving, and configuring editor settings. This comprehensive reference covers all major primary commands with detailed explanations and examples.

Understanding primary commands is essential for efficient editing in ISPF. They provide powerful capabilities for text manipulation, file management, and editor configuration. Primary commands are entered on the command line (typically labeled "Command ==>") and affect the entire file or perform operations across multiple lines.

Understanding Primary Commands

Primary commands are entered on the command line at the top of the editor screen.

Command Line Location

The command line is:

• Located at the top of the editor screen
• Labeled "Command ==>" or similar
• Where you type primary commands
• Separate from the data area and line number area

How Primary Commands Work

To use a primary command:

• Type the command on the command line
• Add any required parameters or options
• Press Enter to execute the command
• The command performs its operation on the file

Command Syntax

Primary commands typically follow this syntax:

1
COMMAND parameter1 parameter2 option1 option2

Commands are case-insensitive, and many accept various options and parameters.

FIND Command

The FIND command searches for text in the file and positions your cursor at the match.

Basic FIND

To find text:

• Type "FIND" followed by the text to search for
• Press Enter to execute the search
• The cursor moves to the first occurrence of the text
• You can continue searching for the next occurrence

FIND Examples

Basic find:

1
Command ===> FIND PROCEDURE

This searches for the word "PROCEDURE" and positions the cursor at the first match.

FIND Options

FIND supports various options:

• FIND text PREV: Searches backwards from the current position
• FIND text FIRST: Finds the first occurrence in the file
• FIND text LAST: Finds the last occurrence in the file
• FIND text ALL: Highlights all occurrences (in some ISPF versions)
• FIND text NEXT: Finds the next occurrence (default behavior)

FIND with Options Examples

Finding the previous occurrence:

1
Command ===> FIND PROCEDURE PREV

Finding the first occurrence:

1
Command ===> FIND PROCEDURE FIRST

FIND Behavior

When FIND locates text:

• The cursor moves to the line containing the match
• The matching text is highlighted or positioned
• You can continue editing or perform other operations
• If no match is found, a message is displayed

CHANGE Command

The CHANGE command searches for text and replaces it with new text.

Basic CHANGE

To change text:

• Type "CHANGE" followed by the old text and new text
• Separate old and new text with a space or delimiter
• Press Enter to execute the change
• The first occurrence is replaced

CHANGE Examples

Basic change:

1
Command ===> CHANGE OLD NEW

This finds the first occurrence of "OLD" and replaces it with "NEW".

CHANGE with Delimiters

For text containing spaces, use delimiters:

1
Command ===> CHANGE /old text/new text/

Or with different delimiters:

1
Command ===> CHANGE 'old text' 'new text'

CHANGE Options

CHANGE supports various options:

• CHANGE old new ALL: Replaces all occurrences in the file
• CHANGE old new PREV: Replaces the previous occurrence
• CHANGE old new FIRST: Replaces the first occurrence
• CHANGE old new LAST: Replaces the last occurrence
• CHANGE old new NEXT: Replaces the next occurrence (default)
• CHANGE old new NX: Replaces the next occurrence (abbreviated)

CHANGE ALL Example

Replacing all occurrences:

1
Command ===> CHANGE OLD NEW ALL

This replaces every occurrence of "OLD" with "NEW" throughout the entire file.

CHANGE Behavior

When CHANGE executes:

• The matching text is located
• The old text is replaced with the new text
• The cursor moves to the changed line
• A message confirms the change (or number of changes for ALL)
• If no match is found, a message is displayed

COPY Command

The COPY command copies lines or blocks of lines within the file or to another location.

Basic COPY

COPY can be used in different ways:

• As a primary command to copy lines
• With line commands (C with A or B)
• To copy entire files or sections

COPY with Line Numbers

To copy specific lines:

1
Command ===> COPY 10 20 50

This copies lines 10 through 20 and places them after line 50.

COPY Syntax

COPY syntax:

1
COPY startline endline targetline

Or to copy to another file:

1
COPY startline endline targetfile

COPY Examples

Copying lines 5-10 after line 20:

1
Command ===> COPY 5 10 20

This duplicates lines 5 through 10 and places the copies after line 20.

MOVE Command

The MOVE command relocates lines from one position to another within the file.

Basic MOVE

To move lines:

• Specify the range of lines to move
• Specify the target line where they should be placed
• Press Enter to execute the move
• The lines are removed from their original location and placed at the new location

MOVE Syntax

MOVE syntax:

1
MOVE startline endline targetline

MOVE Examples

Moving lines 5-10 to after line 20:

1
Command ===> MOVE 5 10 20

This moves lines 5 through 10 to after line 20, removing them from their original position.

MOVE vs COPY

The key difference:

• MOVE: Relocates lines, removing them from the original location
• COPY: Duplicates lines, keeping originals in place
• Use MOVE when you want to reorganize content
• Use COPY when you want to duplicate content

SAVE Command

The SAVE command saves all modifications to the file.

Basic SAVE

To save your changes:

• Type "SAVE" on the command line
• Press Enter to execute the save
• All modifications are written to the dataset
• The file is updated with your changes

SAVE Examples

Basic save:

1
Command ===> SAVE

This saves all changes made during the current editing session.

SAVE Options

SAVE supports various options:

• SAVE: Saves to the current file
• SAVE NEWNAME: Saves with a different name or to a different location
• SAVE BACKUP: Creates a backup before saving (in some ISPF versions)
• SAVE REPLACE: Replaces existing file without prompting

SAVE Behavior

When SAVE executes:

• All modifications are written to the dataset
• The file is updated on disk
• A confirmation message is displayed
• Unsaved changes are now saved
• You can continue editing or exit

When to SAVE

Save your work:

• After making significant changes
• Before performing risky operations
• Before exiting the editor
• Periodically during long editing sessions
• After completing a task or section

CANCEL Command

The CANCEL command discards all unsaved changes and exits the editor without saving.

Basic CANCEL

To cancel your changes:

• Type "CANCEL" on the command line
• Press Enter to execute
• All unsaved modifications are discarded
• The file returns to its last saved state
• You exit the editor

CANCEL Examples

Basic cancel:

1
Command ===> CANCEL

This discards all changes and exits without saving.

CANCEL Behavior

When CANCEL executes:

• All unsaved changes are lost
• The file remains in its last saved state
• You exit the editor
• A confirmation may be required (depending on ISPF version)
• You return to the previous panel or menu

When to Use CANCEL

Use CANCEL when:

• You've made mistakes and want to start over
• You want to abandon all changes
• You opened the wrong file
• You want to exit without saving
• You're experimenting and don't want to keep changes

CANCEL vs SAVE

Understanding the difference:

• SAVE: Keeps your changes and writes them to the file
• CANCEL: Discards your changes and exits without saving
• Use SAVE when you want to keep your work
• Use CANCEL when you want to abandon your changes

BOUNDS Command

The BOUNDS command sets the left and right column boundaries for editing.

Basic BOUNDS

To set column boundaries:

• Type "BOUNDS" followed by the left and right column numbers
• Press Enter to apply the boundaries
• The editor restricts editing to the specified column range
• This is useful for fixed-format languages like COBOL

BOUNDS Examples

Setting boundaries for COBOL (columns 1-72):

1
Command ===> BOUNDS 1 72

This sets the left boundary at column 1 and the right boundary at column 72.

BOUNDS for COBOL Areas

Setting boundaries for Area B (columns 12-72):

1
Command ===> BOUNDS 12 72

This restricts editing to Area B, which is where COBOL procedure statements go.

BOUNDS Syntax

BOUNDS syntax:

1
BOUNDS leftcolumn rightcolumn

Both column numbers are required.

BOUNDS Behavior

When BOUNDS is set:

• Editing is restricted to the specified column range
• You cannot type outside the boundaries
• The boundaries are displayed or enforced visually
• This helps maintain proper formatting for fixed-format languages
• Boundaries persist until changed or the editor is closed

When to Use BOUNDS

Use BOUNDS when:

• Editing fixed-format languages like COBOL
• You need to stay within specific column ranges
• You want to prevent typing outside allowed areas
• You're working with structured data formats
• You need to maintain column alignment

Other Primary Commands

ISPF supports many other primary commands for various operations.

Additional Commands

Other useful primary commands include:

• RESET: Resets the editor state or clears modifications
• UP: Scrolls up in the file
• DOWN: Scrolls down in the file
• TOP: Moves to the top of the file
• BOTTOM: Moves to the bottom of the file
• LOCATE: Similar to FIND, locates text
• EXCLUDE: Hides lines matching criteria
• RECOVERY: Recovers from errors or restores state

Command Abbreviations

Many primary commands can be abbreviated for faster entry.

Common Abbreviations

Command abbreviations:

• F for FIND
• C for CHANGE (when unambiguous)
• S for SAVE
• CAN for CANCEL
• B for BOUNDS (when unambiguous)

Using Abbreviations

Abbreviations make commands faster to type:

1
2
3
Command ===> F PROCEDURE
Command ===> S
Command ===> CAN

These are equivalent to FIND, SAVE, and CANCEL respectively.

Best Practices for Primary Commands

Following best practices helps you use primary commands effectively:

• Save Frequently: Use SAVE regularly to avoid losing work
• Verify Before Change ALL: Be careful with CHANGE ALL—verify the replacements are correct
• Use FIND Before CHANGE: Use FIND to locate text before using CHANGE to ensure you're changing the right thing
• Set BOUNDS for Fixed-Format: Use BOUNDS when editing fixed-format languages to stay within column limits
• Learn Abbreviations: Master command abbreviations for faster editing
• Understand Command Effects: Know what each command does before using it
• Use CANCEL Wisely: Only use CANCEL when you're sure you want to discard changes
• Combine with Line Commands: Use primary commands together with line commands for powerful editing

Command Line Tips

Here are some tips for using the command line effectively:

Command History

Some ISPF versions support command history:

• Use function keys or shortcuts to recall previous commands
• Modify previous commands instead of retyping
• This speeds up repetitive operations

Command Completion

Some ISPF versions support command completion:

• Type part of a command and use completion to finish it
• This reduces typing and prevents errors
• Helps discover available commands and options

Error Messages

When commands fail:

• Read error messages carefully
• They often indicate what went wrong
• Common issues: syntax errors, invalid parameters, file permissions
• Correct the command and try again

Explain Like I'm 5: Primary Commands

Think of primary commands like special buttons on a remote control for your file:

• FIND is like a "search" button. When you press FIND and type a word, it's like telling the editor "find this word for me!" The editor looks through the whole file and shows you where that word is, like using a search button to find your favorite TV show.
• CHANGE is like a "find and replace" button. You tell it "find this word and change it to this other word!" It's like having a magic button that finds all the old words and replaces them with new words automatically.
• SAVE is like a "save" button on a video game. When you press SAVE, all your work is saved so you don't lose it. It's like saving your progress in a game so you can come back to it later!
• CANCEL is like an "undo everything" button. When you press CANCEL, it's like saying "I don't want any of these changes!" All the work you did disappears, and the file goes back to how it was before, like resetting a game to the beginning.
• BOUNDS is like setting boundaries on a playground. You tell the editor "you can only play (edit) in this area!" It's like drawing lines on the ground and saying "stay inside these lines!" This helps keep everything in the right place.

So primary commands are like special buttons that do big jobs on your whole file at once—finding things, changing things, saving your work, or canceling everything!

Practice Exercises

Complete these exercises to reinforce your understanding of primary commands:

Exercise 1: FIND Operations

Practice using FIND: open a test file, use FIND to locate different words, try FIND with PREV and FIRST options, and practice navigating through search results. Build familiarity with search operations.

Exercise 2: CHANGE Operations

Practice using CHANGE: use CHANGE to replace single occurrences, try CHANGE with ALL to replace all occurrences, practice using delimiters for text with spaces, and verify your changes are correct.

Exercise 3: SAVE and CANCEL

Practice saving and canceling: make changes to a test file, use SAVE to save them, make more changes, use CANCEL to discard them, and verify that only the first set of changes were saved. Understand the difference between SAVE and CANCEL.

Exercise 4: BOUNDS Configuration

Practice using BOUNDS: set different boundary ranges, try editing within and outside the boundaries, set boundaries for COBOL editing (1-72 and 12-72), and observe how boundaries affect editing.

Exercise 5: COPY and MOVE

Practice using COPY and MOVE: use COPY to duplicate lines, use MOVE to relocate lines, compare the results, and practice with different line ranges. Understand when to use each command.

Related Concepts