change Command

Substitutes one string for another.

Scope: File

Syntax

Parameters

visible 
Changes are restricted to visible lines.
any
Find String regardless of case.
asis
Find String exactly as typed.
Delimiter 
Strings are separated by any single non-blank character not used elsewhere in the parameter string. For example, change "String1"String2 uses double quotes as a delimiter. Because z is not part of the string to be changed, you could also have specified the command with change zString1 zString2. Spaces placed between the delimiter and string are considered part of the string.
String1/String2 
String1 is the string to be searched for and String2 is the string which replaces String1. A change is made only when an exact match is found, including alphabetic case and spaces. If no other parameters are used, only the current line or marked block is searched.

If String1 is null, String2 is inserted at the beginning of each line. If String2 is null, each occurrence of String1 is deleted. To indicate null, use the delimiter followed by the next delimiter (for example, "").

Command 
An Editor command, including multiple commands. This is used to define the range of lines over which any changes are to be applied. The range extends from the current position to the line that becomes the current line when the command is executed. This parameter can also be a positive integer that gives the number of lines over which the changes can be made.
Count 
The maximum number of changes allowed in any line. If omitted, the default is any number of changes; but if String1 is null, then the default becomes one. If the Command parameter is omitted, you need to ensure that there are two delimiters before the Count.
? 
The Editor prompts for each change to be confirmed.

Description

The change command searches for String1 and, if found, replaces it with String2. This command searches forward only.

By default, the change command is applied only to the current line or, if a block is marked, then only to the marked block. If the Command or Count parameters are used, the change command continues to make changes beyond the current line or marked block if required by these parameters.

Examples

  1. To replace every occurrence of the 6-character string colour with the 5-character string color in the current line or marked block, type:
    change "colour"color

    In this example, " is the delimiter.

  2. To replace every occurrence of the 6-character string colour with the 5-character string color, from the current position to the end of the file, type:
    change "colour"color"bottom
  3. To replace every occurrence of the 6-character string colour with the 5-character string color, until the Editor finds the word finish, type:
    change "colour"color"find asis finish"?

    The Editor searches for the word colour and changes it to color until it finds the word finish. Because of the ?, the Program Editor asks for each change to be confirmed.

  4. To replace every occurrence of the 6-character string colour with the 5-character string color, in the next five lines, type:
    change "colour"color"5

    The integer 5 in the Command position gives the number of lines over which the changes can be made.

  5. To replace up to five occurrences of the 6-character string colour with the 5-character string color, in the current line, type:
    change "colour"color""5

    The integer 5 in the Count position gives the maximum number of changes allowed in the current line. The two quotation marks in the Command parameter position are required to place the integer in the Count position.

API Return Codes

-1 
The marked block in which you want to search is not in the current file. Click on the file containing the block to make it current and then retry the command.
-2 
The file contains no lines; no operations can be performed.
-3 
The change command received a negative return code from the command specified by the Command parameter.
-4 
The Count parameter was not a valid positive integer. Correct the Count and issue the command again.
-5 
You cannot make changes to the file because the readonly parameter is set to on.
-7 
The change command required at least two parameters and you have specified only one. Check to see that a null string is preceded by a delimiter.