CHANGE and RCHANGE

The CHANGE command is used to find and change one or more occurrences of string-1 to string-2. You can enter the operands in any sequence, except string-2 must follow string-1, col-2 must follow col-1, and the DATA-NAME or CURSOR (CUR, C) operand must be last.

PL/I

You cannot use the CHANGE command to change individual bit patterns within a BIT data item. For example, if a field is declared as BIT(8) and contains 11000101, a CHANGE ’101’ ’001’ command does not find the 101 in bits five through seven of the field. However, because 11000101 is the bit pattern for the character E, a CHANGE E F or CHANGE X’C5’ X’C6’ command successfully changes E to F in the Bit field¹.

See to here for information on how the CHANGE command is affected by non-keyed and nonunique segments.

You can specify string-1 and string-2 in any of the following formats:

• A simple string: Any series of characters that does not start or end with an apostrophe (’) or quotation mark (") and does not contain any blanks.
• A delimited string: Any string that starts and ends with an apostrophe, but does not contain imbedded apostrophes. Or, any string that starts and ends with a quotation mark but does not contain imbedded quotation marks.
• A hexadecimal string: Any delimited string of hexadecimal characters preceded by the letter X (for example, X’C1F0’).
• A Unicode string: Any delimited string of Unicode characters preceded by the letter U (for example, U’ABC’) will find the hexadecimal string X'004100420043'.
• A single asterisk: This format causes the string, but not the optional operands except for a data-name field boundary, used in the previous CHANGE command to be used again.

Adjusting Length of Strings

 File-AID for IMSreplaces string-1 with string-2 only when they are the same length. When appropriate, the strings are forced to be the same length. For example, in the command CHANGE SUSAN SUE, string-1 (SUSAN) is five bytes in length, and string-2 (SUE) is three bytes. File-AID for IMS replaces the next occurrence of SUSAN with SUE…

String-2 is forced to five bytes long with blank padding to the right (positions four and five). This is done so that any numeric data to the right of string-2 is not shifted to the left.

File-AID for IMS does not adjust the length of a delimited string. For example, in the command CHANGE ’SUE’ SUSAN, File-AID for IMS assumes that you want to search for the specific value SUE and not for the value SUEªª. In this situation the change is not made, and the error message INVALID CHANGE TO TEXT is displayed.

Asterisk (*) Operand

The asterisk operand can represent the string-1 or string-2 value used in the previous CHANGE command. You can use two asterisks to represent both string-1 and string-2. For example, the command CHANGE SMITH JONES can be repeated as follows:

• CHANGE * JONES
• CHANGE SMITH *
• CHANGE * *

The data-name boundary is the only optional Change command operand that File-AID for IMS retains for the Change * * command. For example, the command CHANGE SMITH JONES NAME changes the characters SMITH to JONES in the field NAME. If you subsequently enter the command CHANGE * * FIRST, File-AID for IMS changes the first occurrence of the characters SMITH to JONES in the field NAME.

INVALID Operand

A data-name or CURSOR operand is required with the INVALID operand to limit database searches.

When used with the data-name or CURSOR operand in the Edit Formatted sub-option, the INVALID operand causes field values that do not conform to the appropriate COBOL PICTURE clause or PL/I data type to be found. For numeric fields, any value that does not conform to the field’s data type is invalid. For alphanumeric fields, any value that contains non-displayable data is invalid.

ANY Operand

The ANY operand for string-1 can be used to change any value in a range of columns by specifying col-1 and, optionally, col-2. It can also be used to change any value in a field by specifying a data-name boundary. If you specify col-1 without col-2, any value starting in col-1 is changed to string-2, based on the length of string-2. For example, the command CHANGE ANY ABC 10 changes any value that starts in column 10 and ending in column 12 to ABC. If you specify both col-1 and col-2, the entire value contained within and including col-1 and col-2 is changed to string-2, with blank padding to the right if necessary. For example, the command CHANGE ANY ABC 10 20, changes any value that starts in column 10 and ending in column 20 to ABC......... If you use the data-name or CURSOR option, the entire existing value in the appropriate field is changed to string-2.

SEGMENT Operand

Use the SEGMENT operand to limit the search to the specified segment type. If you do not use the SEGMENT operand, all segment types are searched unless you specify a data-name boundary. In this case, only the segment type that you are currently positioned on is searched.

Controlling Starting Point and Extent of Change

You can control the starting point and extent of the change by using one of the following operands:

NEXT

Starts the scan at the current cursor location and proceeds forward to find the next occurrence of the string. This is the default operand.

ALL

Starts the scan at the top of the search range and proceeds forward to find all occurrences of the string.

FIRST

Starts the scan at the top of the search range and proceeds forward to find the first occurrence of the string.

You can further control the extent of the change by using the following operand:

GET(n)

Limits the number of segments that are processed, where n is the number of segments to be searched. 0 is the default value. If you specify 0 or omit this operand, there is no limit placed on the extent of the search. In this case, all database segments can potentially be searched. When the number of segments processed reaches n, the FIND/CHANGE Message screen shown on here is displayed.

FIND/CHANGE Message Screen

The FIND/CHANGE Message screen shown in the following figure, is displayed when the number of segments processed reaches the limit imposed by the GET(n) operand, installation parms, or a security exit.

If you are using a security exit, File-AID for IMS enforces the limit set by either the security exit or the value specified for n, whichever is lower.

If you are not using a security exit, File-AID for IMS enforces the limit set by either the installation parms or the value specified for n, whichever is lower.

FIND/CHANGE Message Screen

The FIND/CHANGE Message screen displays information about what kind of limit was reached (get next calls, installation parms, or security exit). The upper-right corner displays information about the results of the search. In FIND/CHANGE Message Screen, the limit reached was imposed by the CHANGE command and the message indicates that the search was stopped because n segments were retrieved.

When this screen is displayed, you can press Enter to continue the search or END to terminate the search.

Controlling the Range of Change

You can control the range of change by using one of the following operands:

NORCD

Searches the entire database. This is the default operand.

RCD

Searches only the current database record.

CHILD

Searches only the children of the current segment.

Limiting the Search

You can limit the search to a portion of each segment rather than the entire segment by specifying column boundaries (col-1 and col-2 operands) or a data-name boundary (data-name or CURSOR operand).

Column Boundaries

When using column boundaries, col-1 indicates the starting position and col-2 indicates the ending position for the search. If you specify col-1 without col-2, the string must start in col-1 to be found. If you specify col-1 and col-2, the string does not need to start in col-1, but it must be completely contained within the boundaries to be found.

Data-Name Boundary

You can specify a data-name boundary only in the Formatted mode. Data-name indicates the portion of the segment that corresponds to the field to be changed. You can abbreviate the data-name if the abbreviation results in a unique data-name.

If you specify a data-name, it must exist in the current segment’s COBOL or PL/I layout. By specifying a data-name, the search is limited to the current segment type.

For example, assume that you are editing segment ORDR020 using a segment layout that contains a 30-byte alphanumeric field [PIC X(30) in COBOL; CHAR(30) in PL/I] called DESCRIPTION that starts in column 20 of the segment. To change the next occurrence of the characters MODEM to COAX within that field, you can enter the command CHANGE MODEM COAX DESCRIPTION. Only columns 20 through 49 of each ORDR020 segment are searched.

Another way to confine the search to a specific field within each segment is to use the CURSOR operand. To do this, enter the word CURSOR, CUR or C in place of a specific data-name and position your cursor on the data-name line to which you want to limit the search and press Enter.

When you specify an alphanumeric field, the string does not need to start in position 1 of the Data-Name field, but it must be completely contained within the field to be found. When you specify a numeric field, the string is converted to the appropriate numeric data type before the search begins.

For example, again assume that you are editing segment ORDR020 using a segment layout that contains a three-byte, signed, packed field [PIC S9(5) COMP-3 in COBOL; FIXED DEC(5) in PL/I] called QTY-ORDERED. If you enter the command CHANGE ’200’ ’250’ QTY-ORDERED, the value 200 is first converted to the internal, signed, packed representation, and the appropriate portion of each ORDR020 segment is scanned for that value.

COBOL

If the data-name boundary you specify is for a POINTER or INDEX data item, you must enter the string-1 and string-2 operands as hexadecimal strings.

PL/I

If the data-name boundary you specify is for a BINARY FLOATING POINT or POINTER data item, you must enter the string-1 and string-2 operands as hexadecimal strings.

A data-name boundary cannot be specified for a BIT data item.

When you want to limit the search to a numeric field, enter string-1 and string-2 so that they cannot be misinterpreted as column boundaries. For example, the command CHANGE 200 300 QUANTITY searches for the characters QUANTITY starting in column 200 and ending in column 300 rather than changing the value 200 to 300 in the Quantity field. Do the following to distinguish string-1 and string-2 values from column boundaries:

• Enclose the value in apostrophes or quotes.
• Precede the value with a positive (+) or minus (-) sign if the COBOL picture or PL/I attribute allows a sign.
• Specify a decimal point.

For example, each of the following commands changes the value 200 to 300 in the Quantity field:

• CHANGE "200" "300" QUANTITY
• CHANGE +200 +300 QUANTITY
• CHANGE 200. 300. QUANTITY

The search proceeds until one or all occurrences of string-1 are found or until the end of the range is encountered. If string-1 is not found, one of the following messages is displayed.

When BOTTOM OF DATA REACHED is displayed, you can enter the RCHANGE command to continue searching by wrapping to the top of the data. If an occurrence is not found anywhere in the data, a NO CHARS string FOUND message is displayed.

When string-1 is found in fields that have been excluded from display, the fields are displayed again. Also, if the segment layout is shorter than the segment it defines and string-1 is found in a part of the segment beyond the reach of the segment layout, the message TEXT FOUND - NON DISPLAY is displayed.

Repeat Change (RCHANGE)

The RCHANGE command finds and changes the next occurrence of the designated string. The other optional parameters remain in effect, as specified in the last CHANGE command.

CHANGE Command Screen

If you enter CHANGE or C in the Command field with no operands while in Edit mode, the CHANGE Command screen is displayed. This screen enables you to find and change one or more occurrences of a string². 

CHANGE Command Screen

From String

Enter the string that you want changed. For more information on string syntax, see .

To String

Enter the string that is to replace the From String. The To String can be specified by using the same syntax as the From String, except that the INVALID and ANY operands cannot be used.

Segment Name

Enter the name of the segment type to be searched. If you do not specify a segment type, all segment types are searched unless you specify a data-name boundary. If you specify a data-name boundary, only the segment type that you are currently positioned on is searched.

Modifier

Enables you to control the starting point and extent of the search. The following operands are valid:

Search Range

Enables you to control the range of the search. The following operands are valid:

Maximum Calls

Enter the maximum number of segments to be searched. 0 is the default value. If you leave this field blank or specify 0, there is no limit placed on the extent of the search. In this case, all database segments are potentially searched.

When the number of segments processed reaches the number specified in the Maximum Calls field, the FIND/CHANGE Message screen is displayed. See here for an illustration and description of this screen.

You can limit the search to a portion of each segment rather than the entire segment by specifying a data-name or column boundaries.

Data-Name

If you are in Formatted mode, you can specify a data-name that indicates the portion of the segment that corresponds to the field to be searched.

If you specify a data-name, it must exist in the current segment’s COBOL or PL/I layout. By specifying a data-name, the search is limited to the current segment type.

You can also use the CURSOR operand in place of a data-name. To do this, position the cursor on the data-name to which you want to limit the search while in Formatted mode before you invoke the CHANGE command. When the CHANGE Command screen is displayed, enter CURSOR, CUR or C in the Data-Name field.

Start Column

Enter the starting position for the search.

End Column

Enter the ending position for the search. If you specify a Start column without an END column, the string must begin in the Start column to be found. If you specify both Start and End columns, the string does not need to begin in the Start column, but it must be completely contained within the boundaries to be found.