CHANGE/CX primary command

The CHANGE command finds and replaces occurrences of a string or value. It can be entered in an Edit session or when using the Find/Change Utility, by using any abbreviation of the command (for example, C, CH, CHG).

For date and time fields that are displayed using the output format defined in the template, Z Data Tools searches the displayed values for string1 and if found replaces string1 with string2 in the displayed value.

The CX command displays an Extended Command Entry panel, in which you can enter long arguments that may not otherwise fit within the Command line (see Handling long strings in CHANGE).

Note:
  1. When you enter the CHANGE primary command in the Editor without specifying any parameters, Z Data Tools displays the Extended Command Entry pop-up panel to allow you to enter arguments.
  2. If you use the CNot version of the command, then a string is matched if it does not match according to the matching criteria described in this section.

Syntax

CHANGE primary command in the Editor

In an Edit session, the CHANGE primary command finds and replaces one or more occurrences of a character string within the currently displayed data set or data set member. In SNGL or TABL display format, you can also use the CHANGE command to find and replace a numeric value in numeric fields.
Note: When you enter the CHANGE primary command in the Editor without specifying any parameters, Z Data Tools displays the Extended Command Entry pop-up panel to allow you to enter arguments.
Read syntax diagramSkip visual syntax diagram
Syntax in the Editor

              (1)   
>>-+-Change-+--------------------------------------------------->
   +-CX-----+       
   +-CHG----+       
   +-CNot---+       
   '-CNX----'       

>--+---------------------------------------------------------+-->
   |                           .-NEXT--.  .-CHARs--.         |   
   '-+-*-------+--+-*-------+--+-------+--+--------+--+----+-'   
     '-string1-'  '-string2-'  +-ALL---+  +-PREfix-+  +-X--+     
                               +-PREV--+  +-SUFfix-+  +-EX-+     
                               +-LAST--+  '-WORD---'  '-NX-'     
                               '-FIRST-'                         

                                .-.ZFIRST--.ZLAST-.   
>--+-------------------------+--+-----------------+------------->
   +-| column range |--------+  '-label1--label2--'   
   '-| field list or range |-'                        

          (2)   
>--+----+------------------------------------------------------><
   +-X--+       
   +-EX-+       
   '-NX-'       

column range (all display formats)

|--col1--+------+-----------------------------------------------|
         '-col2-'   

field list or range (SNGL or TABL display format)

     .-#ALL-.                     
|--+-+------+-----------------+---------------------------------|
   |     .-+---+-.            |   
   |     | '-,-' |            |   
   |     V       |            |   
   +---(---ref---+-)----------+   
   |   .-+---+------------.   |   
   |   | '-,-'            |   |   
   |   V                  |   |   
   '-(---ref_1-- ---ref_2-+-)-'   

Notes:
  1. You can specify parameters in any order.
  2. If none of these parameters (X, EX or NX) is specified, then both excluded and not-excluded records are searched.

CHANGE primary command in the Find/Change Utility

In the FCH utility, the CHANGE primary command finds and replaces all occurrences of the specified string in the selected members or data set.

Read syntax diagramSkip visual syntax diagram
Syntax in the Find/Change Utility

                                 .-CHARs--.   
>>-+-Change-+--string1--string2--+--------+--------------------->
   +-CX-----+                    +-PREfix-+   
   '-CHG----'                    +-SUFfix-+   
                                 '-WORD---'   

>--+---------------+--MAXINREC(n)--MAXRECS(n)--FIRST(n)--------><
   '-col1-+------+-'                                      
          '-col2-'                                        

Change, CX
The CHANGE command or any of its abbreviations is entered on the Command line, together with the desired parameters. To find and replace long strings that do not fit on the Command line, enter the CHANGE primary command (or one of its abbreviations, such as C) with no parameters, or enter the CX command on the Command line with no parameters. This displays the Extended Command Entry panel, in which you can enter long strings and the CHANGE command parameters.
* (asterisk)
When used in place of the search string, uses the search string specified on the previous CHANGE command as the search string.

When used in place of the replacement string, uses the replacement string specified on the previous CHANGE command as the replacement string.

The position of the * is important for CHANGE. If it is positioned before a string, it indicates the previous search argument; that is, it is treated as the first string. If a string is found prior to the *, then it is treated as the second string (the change argument), taking the change argument from the previous CHANGE command. To use both the previous search string and the previous change string, specify CHANGE * *.

string1
The string you want to search for, which must be no more than 100 characters long. The string can be:
  • A character string not starting or ending with a quotation mark and not containing any embedded blanks or commas. The case of the string is ignored. Uppercase and lowercase representations of the same character match. For example, the following command changes the strings black, Black, and BLACK:
    CHANGE black white
  • A character string enclosed in quotation marks. The string can contain blanks and commas. The case of the string is ignored. For example, 'Exact string' matches 'exact string'. The string can be a null string (''). If string1 is a null string, then string2 is inserted at the current column position.
  • C followed by a character string enclosed in quotation marks (C'Frog'), or a character string enclosed in quotation marks followed by C ('Frog'C). The string can contain blanks and commas. The string must match exactly (including case). For example, C'Exact string' does not match C'exact string'. The string can be a null string (C''). If string1 is a null string, then string2 is inserted at the current column position.
  • A DBCS string or a mixed DBCS and non-DBCS string. A shift-out (X'OE') as the first character, or a shift-in (X'OF') as the last character, are discarded as part of the search string.
  • P preceded or followed by a picture string enclosed in single or double quotation marks to describe a type of string to be found rather than the exact characters. It can contain blanks, alphabetic and numeric characters which represent themselves, or any of the special characters listed here, each of which represents a class of characters:
    =
    Any character.
    @
    Alphabetic characters.
    #
    Numeric characters.
    $
    Special characters.
    & notsym;
    Non-blank characters.
    .
    Invalid characters.
    -
    Non-numeric characters.
    <
    Lowercase alphabetics.
    >
    Uppercase alphabetics.

    When this notation is used, numeric, bit and Unicode fields (for SNGL and TABL display formats) are excluded from the search process.

  • X followed by a hexadecimal string enclosed in quotation marks (X'C1C2'), or a hexadecimal string enclosed in quotation marks followed by X ('C1C2'X).
  • A numeric value (only when, in SNGL or TABL display format, you limit the search by specifying field references, and only when the field being searched is a numeric field). For details, see Searching numeric fields.
string2
The string that you want to use to replace string1, which must be no more than 100 characters long. The string can be:
  • A character string not starting or ending with a quotation mark and not containing any embedded blanks or commas. If CAPS ON or CASE UPPER is in effect, then string2 is translated to uppercase.
  • A character string enclosed in quotation marks. The string can contain blanks and commas. If CAPS ON or CASE UPPER is in effect, then string2 is translated to uppercase. The string can be a null string ('').
  • C followed by a character string enclosed in quotation marks (C'Frog'), or a character string enclosed in quotation marks followed by C ('Frog'C). The string can contain blanks and commas. Case is respected and retained. The string can be a null string (C'').
  • A DBCS or a mixed DBCS and non-DBCS string. The shift-out (X'0E') and shift-in (X'0F') at the start and end of the string are adjusted in such a way that the integrity of the DBCS data is not compromised.
  • P preceded or followed by a picture string enclosed in single or double quotation marks to describe the change to be made. You can change characters from uppercase to lowercase or from lowercase to uppercase, or leave the field the same using these string special characters.
    =
    Any character.
    <
    Lowercase alphabetics.
    >
    Uppercase alphabetics.

    Examples of picture strings used with the CHANGE command:

    c p'.' x'00'
    Change next invalid character to hex x'00'.
    c p'###' 100
    Change next 3-digit number to 100.
    c all 73 80 p'=' " "
    Put blanks in columns 73 to 80.
    c all p'-' 1 10 "0"
    Change all non-numeric characters in columns 1 to 10 into the char "0".
    c p'<' p'>'
    Change any lowercase to uppercase.
    c p'a>' p'=<'
    Change char a, any uppercase to char a, lowercase.
    c p'>' '¬'
    Change any uppercase to "not sign" (note: "not sign" has no special meaning in a "to" string).
    c p'<#' p'>='
    Change any lowercase, any number to uppercase, the number found.

    When this notation is used, numeric, bit and Unicode fields (for SNGL and TABL display formats) are excluded from the search process.

    .
  • X followed by a hexadecimal string enclosed in quotation marks (X'C1C2'), or a hexadecimal string enclosed in quotation marks followed by X ('C1C2'X). Case is respected and retained (the hexadecimal values are used exactly as specified).
  • A numeric value (SNGL and TABL display formats only).
col1
The first column to be included in the range of columns to be searched. Must be greater than or equal to 1, and less than or equal to the maximum record length. When column ranges are specified and the data is displayed in SNGL or TABL formats, the search is performed in the order that the data occurs, which may not be the order in which the fields are displayed.

When column ranges are specified in SNGL or TABL display format, then a string comparison is performed, even for numeric fields.

Note: When you use the CHANGE primary command in the Find/Change Utility, if the JCL Source format option is selected, the columns searched are set to 3 through 71, unless the statement is not a JCL statement. A statement is considered to be a JCL statement if it begins with the strings "/*" or "//". If the statement does not begin with either of these strings, it is not considered to be a JCL statement in which case any column range specified on the FIND (or CHANGE, respectively) command or preset using the BOUNDS command is honored. If no column range has been specified, the full record is searched.
ALL
(Applies in the Editor only.) Causes the search to begin at the top of the data and find and replace all occurrences of the string.
Note:
  1. Suppressed or not-selected records that are hidden from display or represented by shadow lines are not processed by the CHANGE command, even when the ALL parameter is specified.
  2. The ALL parameter is not recursive when used with the CHANGE command. That is, applying the command CHANGE ALL 'SS' 'RS' to the string 'SSS' results in 'RSS', not in 'RRS'.
FIRST
(Applies in the Editor only.) Searches from the top of data for the first occurrence of string.
LAST
(Applies in the Editor only.) Searches backwards from the bottom of data for the last occurrence of string.
NEXT
(Applies in the Editor only.) Causes the search to begin at the cursor location (if the cursor is within the data portion of the screen) or the beginning of the first record displayed, and searches ahead to find the next occurrence of the string. If the next occurrence of the string is in an excluded record and you do not limit the search to not-excluded records, only the first excluded record containing the string is shown.
PREV
(Applies in the Editor only.) Searches backwards from the cursor position (if the cursor is within the data portion of the screen), or from the beginning of the topmost record displayed on the screen, for the next occurrence of string.
CHARS
Matches the search string anywhere in the data.
PREFIX
Matches the search string wherever it appears as a prefix in the data. To be a prefix, the matched text must be preceded by a non-alphanumeric character or be the start of a line or field, and must be followed by an alphanumeric character.
SUFFIX
Matches the search string wherever it appears as a suffix in the data. To be a suffix, the matched text must be preceded by an alphanumeric character, and must be followed by a non-alphanumeric character or be the end of a line or field.
WORD
Matches the search string wherever it appears as a word in the data. To be a word, the matched text must be preceded by a non-alphanumeric character or be the start of a line or field, and must be followed by a non-alphanumeric character or be the end of a line or field.
col2
The last column to be included in the range of columns to be searched. Must be greater than or equal to col1 and less than or equal to the maximum record length. If not specified, the string is matched with data starting in the col1 location for the length of the string.
#ALL
Each field is searched according to its template attributes.
ref
(Applies in the Editor only.) A field reference, specifying the field to be included in the search, for example: #3. When the field is an item in an array, you must specify a subscript in parentheses to identify the occurrence that you want to change, for example: #5(3). If your field is part of a multi-dimensional array, you must specify a subscript for each dimension in the array, for example: #7(2,3).

Multiple field references must either be enclosed in parentheses, or separated with commas but without any intervening spaces. For details, see Limiting the search to specified fields.

In SNGL or TABL display format, if you specify field references or do not specify a field reference or column range, when searching a numeric field, the search string is interpreted as a numeric value, and a numeric comparison is performed. When searching a character field, a string comparison is performed. That is, the search is performed based on the Z Data Tools template attributes. For details, see Searching numeric fields.

ref_1
The first field reference of a range of fields. It cannot be subscripted. If the ref_1 field reference value is less than the lowest displayed field reference value, the lowest displayed field reference value is used.
ref_2
The last field reference of a range of fields. It cannot be subscripted. If the ref_2 field reference value is greater than the highest displayed field reference value, the highest displayed field reference value is used.

The ref_1 and ref_2 field reference values must be separated by a hyphen (-). Spaces are permitted between the hyphen and the field reference values.

If ref_1 is a higher value than ref_2, the search process reverses the operands.

EX
(Applies in the Editor only.) Excluded records only.
label1
(Applies in the Editor only.) Label identifying the start of a range of records. The label must start with a period (.) followed by one to four alphabetic characters (no numeric or special characters). Labels starting with the letter “Z” indicate an editor-assigned label.
label2
(Applies in the Editor only.) Label identifying the end of a range of records. The label must start with a period (.) followed by one to four alphabetic characters (no numeric or special characters). Labels starting with the letter “Z” indicate an editor-assigned label.
NX
(Applies in the Editor only.) not-excluded records only.
X
(Applies in the Editor only.) Same as EX.
MAXINREC(n)
(Applies in the FCH Utility only.) The MAXINREC parameter allows you to specify the maximum number of changes that can be made within a single record.
MAXRECS(n)
(Applies in the FCH Utility only.) The MAXRECS parameter allows you to specify the maximum number of records that can be changed within a single data set or PDS member.
FIRST(n)
(Applies in the FCH Utility only.) The FIRST parameter allows you to specify the maximum number of total changes that can be performed within a single data set or PDS member.