CHANGE—Change a Search String

The CHANGE macro command changes one search string into another.

Syntax


Macro command syntax

                                      .-.ZFIRST--.ZLAST-.   
>>-ISREDIT--CHANGE--string1--string2--+-----------------+------->
                                      '-labela--labelb--'   

   .-NEXT--.  .-CHARS--.                                    
>--+-------+--+--------+--+----+--+---------------------+------><
   +-ALL---+  +-PREFIX-+  +-X--+  +-start_col-----------+   
   +-FIRST-+  +-SUFFIX-+  '-NX-'  '-left_col--right_col-'   
   +-LAST--+  '-WORD---'                                    
   '-PREV--'

string1

The search string you want to change. See Finding, seeking, changing, and excluding data.

Note: For edit macros written in CLIST, strings that contain an open comment delimiter (/*) must be placed within quotes within the &STR() such as &STR('/*XXX'). The maximum allowable length of the string is 256 bytes. If you are specifying a hex string, the maximum is 128 hexadecimal characters.

string2

The string you want to replace string1. The maximum allowable length of the string is 256 bytes. If you are specifying a hex string, the maximum is 128 hexadecimal characters. See Finding, seeking, changing, and excluding data.

labela, labelb

Labels identifying the start and end of the group of lines CHANGE searches.

If the cursor is currently placed above the start label and the PREV occurrence of a string is requested, or the cursor is currently placed below the end label and the NEXT occurrence of a string is requested, the process returns a return code of 4 and the string is not found, even if it exists within the label range.

For more information about using labels to identify a group of lines, see Labels and line ranges.

NEXT

Starts at the first position after the current cursor location and searches ahead to find the next occurrence of string1.

ALL

Starts at the top of the data and searches ahead to find all occurrences of string1.

FIRST

Starts at the top of the data and searches ahead to find the first occurrence of string1.

LAST

Starts at the bottom of the data and searches backward to find the last occurrence of string1.

PREV

Starts at the current cursor location and searches backward to find the previous occurrence of string1.

CHARS

Locates string1 anywhere the characters match.

PREFIX

Locates string1 at the beginning of a word.

SUFFIX

Locates string1 at the end of a word.

WORD

Locates string1 when it is delimited on both sides by blanks or other non-alphanumeric characters.

X

Scans only lines that are excluded from the display.

NX

Scans only lines that are not excluded from the display.

start_col

The first column to be included in the range of columns to be searched. When you specify only one column, the editor finds the string only if the string starts in the specified column.

left_col

The first column to be included in the range of columns CHANGE is to search.

right_col

The last column to be included in the range of columns CHANGE is to search.

Note: For more information about restricting the search to only a portion of each line, see Limiting the search to specified columns.

Description

CHANGE is often used with FIND, EXCLUDE, and SEEK, and the CHANGE_COUNTS assignment statement.

To change the next occurrence of "ME" to "YOU" without specifying any other qualifications, include this command in an edit macro:

ISREDIT CHANGE ME YOU

This command changes only the next occurrence of the letters "ME" to "YOU". Since no other qualifications were specified, the letters "ME" can be:

Uppercase or a mixture of uppercase and lowercase
At the beginning of a word (prefix), the end of a word (suffix), or the entire word (word)
In an excluded line or a non-excluded line
Anywhere within the current boundaries

To change the next occurrence of "ME" to "YOU", but only if the letters are uppercase, include this command in an edit macro:

ISREDIT CHANGE C'ME' YOU

This type of change is called a character string change (note the C that precedes the search string) because it changes the next occurrence of the letters "ME" to "YOU" only if the letters are found in uppercase. However, since no other qualifications were specified, the change occurs no matter where the letters are found, as outlined in the preceding list.

When you would like to issue CHANGE, but you are unsure of the exclude status of a line, you can use the XSTATUS assignment statement with SEEK. First, find the particular line with SEEK. Then, determine the exclude status with the XSTATUS assignment statement. Use CHANGE to change the string; and finally, reset the exclude status with another XSTATUS assignment statement. For example:

ISREDIT SEEK ABC
DO WHILE &LASTCC=0
  ISREDIT (X) = XSTATUS .ZCSR
  ISREDIT CHANGE ABC DEF .ZCSR .ZCSR
  ISREDIT XSTATUS .ZCSR = &X
  ISREDIT SEEK ABC
END

For more information, including other types of search strings, see Finding, seeking, changing, and excluding data.

Return codes

0: Normal completion
4: String not found
8: Change error. string2 is longer than string1 and substitution was not performed on at least one change.
12: Inconsistent parameters. The string to be found does not fit between the specified columns.
20: Severe error

Examples

Before changing the current member name, put it into a variable name such as MEMNAME. To add an identifier to that name, if it is in columns 1 to 10 and lies within the first line and the line labeled .XLAB:

ISREDIT (MEMNAME) = MEMBER
ISREDIT CHANGE WORD &MEMNAME "MEMBER:&MEMNAME" 1 10 .ZFIRST .XLAB