CHANGE - Change a Data String

Syntax


CHANGE

from-string   to-string

[ start-column [ end-column ] ]

[ FIRST | LAST | NEXT | PREV | ALL ]

[ PREFIX | SUFFIX | WORD | CHAR ]

[ LEFT | RIGHT ]

[ TRUNC ]

[ line-control-range ]

[ color-selection-criteria]

[ color-change-request]

[ DS | CS ]

[ X | NX ]

[ U | NU ]

[ MX | DX ]

[ TOP ]


Operands


from-string

The search string you want to change


to-string

The string you want to replace from-string


start-column

Left column of a range (with end-column) within which the from-string value must be found. If no end-column operand, then the from-string operand must be found starting in start-column.


end-column

Right column of a range (with start-column) within which the from-string value must be found.


FIRST

Starts at the top of the data and searches ahead to find the first occurrence of from-string.


LAST

Starts at the bottom of the data and searches backward to find the last occurrence of from-string.


NEXT

Starts at the first position after the current cursor location and searches ahead to find the next occurrence of from-string.  NEXT is the default.


PREV

Starts at the current cursor location and searches backward to find the previous occurrence of from-string.


ALL

Starts at the top of the data and searches ahead to find all occurrences of from-string.


LEFT

LEFT causes the search-string to be found at most once in any given line.  Where the search-string occurs more than once in the same line, only the left-most occurrence of search-string is changed, and any other instances on that same line are unchanged.


RIGHT

RIGHT causes the search-string to be found at most once in any given line.  Where the search-string occurs more than once in the same line, only the right-most occurrence of search-string is changed, and any other instances on that same line are unchanged.


TRUNC

TRUNC will cause the remainder of the line, following the replacement CHANGE string, to be deleted (truncated).


PREFIX

Locates from-string at the beginning of a word.


WORD

Locates from-string when it is delimited on both sides by blanks or other non-Word characters.


CHAR

Locates from-string regardless of what precedes or follows it.


SUFFIX

Locates from-string at the end of a word.


line-control-range

The range of lines which are to be processed by the command.  Line control ranges provide a powerful tool to customize the range of lines to be processed.   The full syntax and allowable operands which make up a line control range are discussed in "Line Control Range Specification".  Refer to that section of the documentation for details.


color-selection-criteria

A request for selection based on the highlight color of the from-string. Color requests provide another powerful tool to control search selection.   The full syntax and allowable operands which make up a color-selection-criteria  are discussed in "Color Selection Criteria Specification".   Refer to that section of the documentation for details.


color-change-request

A request can also be made to highlight the string following completion of the command.  The full syntax and allowable operands which make up a color-change-request  are discussed in "Color Change Request Specification".   Refer to that section of the documentation for details.


X | NX

Specifies a subset of the line range to be processed.   X requests only excluded lines are to be examined, NX requests only non-excluded lines are to be examined.   If neither X or NX are specified, all lines in the range will be examined.


U | NU

Specifies a subset of the line range to be processed.   U requests only User lines are to be processed, NU requests only non-User lines are to be processed.   If neither U or NU are specified, all lines in the range will be processed.


CS | DS

Specifies the Column Shift / Data Shift mode for this particular CHANGE command.   See Effect of CHANGE Command on Column-Dependent Data for the significance of this operand.   If not specified, the default CS/DS value for this file's Profile will be used.


If a CS or DS is the only operand of the CHANGE command, the specified value will be set as the default for the file's Profile.


MX

MX requests that all lines which DO contain from-string be excluded from the display following command processing.  MX = Make Excluded.


DX

DX requests that lines which DO contain from-string, which, if excluded, would normally be made visible, be left in their excluded status.  DX = Don't change Excluded status


TOP

Normally, at the completion of the command, the first, or only, line processed is highlighted (if it is on the current screen) or the screen is scrolled to the second screen line (as ISPF does) if the line is not on the current screen.  If TOP is coded, then the line is always repositioned as the top line of the screen, regardless of its current location.


Abbreviations and Aliases


CHANGE can also be spelled as C, CHG or CHA

PREFIX can also be spelled as PRE or PFX

SUFFIX can also be spelled as SUF or SFX

WORDS can also be spelled as WORD

CHARS can also be spelled as CHAR

Description


You can use the CHANGE command to change one string to another either singly, or for all occurrences. As well optional operands allow you to restrict the column boundaries within which it operates, along with other characteristics of the string searched for.


To change the next occurrence of ME to YOU without specifying any other qualifications:


On the command line type:


CHANGE ME YOU


Press Enter. This command changes only the next occurrence of the letters ME to YOU.


Since no other qualifications were specified, the letters ME can be:



To change the next occurrence of ME to YOU, but only if the letters are uppercase:



On the command line type:


CHANGE C'ME' YOU


Press Enter. This type of change is called a case sensitive 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.


For more information, including other types of search strings, see Finding and Changing Data and Specifying a Picture or Format String.


The following example changes the first plus in the file to a minus. However, the plus must be the first character of a word:

  CHANGE '+' '-' FIRST PREFIX


The following example changes the last plus in the file to a minus. However, the plus must be the last character of a word; and it must be found on an excluded line:  


  CHANGE '+' '-' LAST SUFFIX X


The following example changes the first plus that precedes the cursor position to a minus. However, the character must be a stand alone character (not part of any other word); it must be on a nonexcluded line; and it must exist within columns 1 and 5:  


     CHANGE '+' '-' PREV WORD NX 1 5


The following example changes all words ABC to DEF from the line at label .A to the line at label .B.  If the word ABC appears more than once in any given line, only the left-most one is changed, and any additional occurrences of ABC on the same line are ignored:


  CHANGE LEFT ABC DEF .A .B ALL


The following example changes all strings "XYZ" which are highlighted in BLUE to "PQR".  The resulting string will remain colored BLUE.


  CHANGE ALL "XYZ" BLUE "PQR"



The TRUNC keyword will cause the CHANGE command to truncate the line after point where the change-string replaces the find-string.  The following example changes the characters "END)" to "END." and deletes all remaining characters on the line.


   CHANGE  "END)"  "END."  TRUNC


which will alter the line


COMING TO AN END) BUT NOT BEFORE  


into


COMING TO AN END.


When using TRUNC, the change string can be a zero-length string, which results in truncating the find-string and everything that follows it.  The following example deletes the character ")" and all remaining characters on the line.


   CHANGE  ")"  ""  TRUNC


which will alter the line


COMING TO AN END) BUT NOT BEFORE  


into


COMING TO AN END


Note:  When the CHANGE search operand is a Regular Expression (a string with an R type code) and reverse-order searching is done with PREV or LAST, only the left-most occurrence on any given line is changed.  That is, the command


       CHANGE R'ABC' 'XYZ' PREV


is treated as if it were specified as


       CHANGE LEFT R'ABC' 'XYZ' PREV


and


       CHANGE R'ABC' 'XYZ' LAST


is treated as if it were specified as


       CHANGE LEFT R'ABC' 'XYZ' LAST


This limitation stems from the regular-expression engine used by SPFLite.




Created with the Personal Edition of HelpNDoc: Free Kindle producer