┌◄────── , ──────┐
── REPLACE ─┴─<target specs>─┴─────────────────────────────────────────►
►─┬─────────────────────────────────────────────────────────┬──────────┤
│ ┌◄────────────────────────────────────────────────────┐ │
└─┴─┬─/1\─<sequence range list>───────────────────────┬─┴─┘
├─/1\─ @ ──<start column>─┬───────────────────────┤
│ └─ - ──<end column>─────┤
├─/1\─ SQUEEZE ───────────────────────────────────┤
├─/1\─ TRUNCATE ──────────────────────────────────┤
└─/1\─ : ─┬─ FILE ──<file name>─┬─────────────────┤
│ └─ , ── NOCRUNCH ─┤
├─ SEQUENCE ────────────────────────────┤
└─ TEXT ─┬──────────────────────────────┤
│ ┌◄─────────────────────────┐ │
└─┴─ , ─┬─/1\─ PAGEFORMAT ─┬─┴─┘
├─/1\─ SQUASHED ───┤
└─/1\─ TRUNCATED ──┘<target specs>
──┬───────────────────────┬────────────────────────────────────────────►
│ ┌◄──────────────────┐ │
└─┴─┬─/1\─ LITERAL ─┬─┴─┘
├─/1\─<count>───┤
├─/1\─ FIRST ───┤
├─/1\─ CASED ───┤
└─/1\─ UNCASED ─┘
►─┬─<dlm>──<target text>──<dlm>──────────────────┬─────────────────────►
└─ COLUMN ──<start column>─┬───────────────────┤
└─ ─ ──<end column>─┘
►─┬─<dlm>──<new text>──<dlm>─────────────────────┬─────────────────────┤
└─ COLUMN ──<start column>─┬───────────────────┤
└─ ─ ──<end column>─┘Explanation
The REPLACE command searches all, or part, of the work file for occurrences of specific target text and replaces the target text with new text. The system responds with a number sign (#) to signify completion.
The UPDATE command is implicitly invoked after the REPLACE command has been executed.
The REPLACE command is different from the FIX command. Refer to the FIX command for more information.
Target Specifications
The <target specs> construct defines the location or occurrence of target text that is to be replaced with new text. Target specifications include the following options and required target text and replacement text:
-
LITERAL
-
<count>
-
FIRST
-
CASED
-
UNCASED
-
<dlm> <target text> <dlm>
-
<dlm> <new text> <dlm>
-
COLUMN <start column> - <end column>
LITERAL
The LITERAL option specifies that the search mode for the target text is to be the literal mode. The default search mode is token mode. Refer to the FIND command for more information about the literal and token search modes.
<count>
The count option, if specified, must be an integer. The value of count limits the maximum number of replacements to be performed to the number specified. Any appearances of the target text after the number of occurrences specified by count are ignored.
FIRST
If the FIRST option is specified, each line is searched only for the first occurrence of the target text. Any occurrences later in the line are ignored.
The CASED option enables you to search for the target text with the specified casing. That is, the search for target text is case sensitive. CASED is a command-level option and as such, overrides the CANDE session setting of the text search mode. CASED is the default search mode.
Refer to the SO command in this section for information about setting the text search mode for the CANDE session level.
The UNCASED option enables you to search for the target text without regard to the casing of the text. The search for target text is case insensitive. UNCASED is a command-level option and as such, overrides the CANDE session setting of the text search mode.
Refer to the SO command in this section for information about setting text search mode for the CANDE session level.
<dlm> <target text> <dlm>
The <dlm> <target text> <dlm> form of the target specification explicitly defines the target text, which must be bounded by two matching delimiters. The delimiter (<dlm>) can be any special character except the comma (,), colon (:), or at sign (@).
The target text is the text for which the file is to be searched; the target text is replaced with the specified new text.
The target text can contain hexadecimal values delimited by the defined hexadecimal escape character if the hexadecimal escape character is set through the CANDE command ESCAPE. However, the target delimiter (<dlm>) cannot be the same as the hexadecimal escape character. For more information about the hexadecimal escape character, refer to the ESCAPE command described earlier in this section.
<dlm> <new text> <dlm>
The <dlm> <new text> <dlm> form specifies the replacement text for the target text. The new text must be bounded by two matching delimiters. The delimiter (<dlm>) can be any special character except the comma (,), colon (:), or at sign (@).
COLUMN <start column> – <end column>
COLUMN <start column>
The COLUMN <start column> – <end column> form of the target specification can be used to define the column range for the target text, the replacement text, or both.
When identifying the target text, you can use the following COLUMN option constructs:
-
The COLUMN <start column> – <end column> form defines the target text to be all text on each line between the character positions specified by the start column and end column values, inclusive. This is the range of text that is to be replaced with new text.
-
The COLUMN <start column> form specifies the start-column character position from which to begin text replacement. The new text is inserted from the start-column character position of each line and the remainder of each line is shifted right to accommodate the new text.
When identifying the replacement text, you can use the following COLUMN option constructs:
-
The COLUMN <start column> – <end column> form defines the range of new text to be text between the character positions specified by the start column and end column values, inclusive.
-
The COLUMN <start column> form specifies the column in which the single character for the replacement text is to be retrieved.
Adjustment for different lengths of target text and new text is made by shifting the right side of the line (or column range specified by @<start column> – <end column>) to the left or right, deleting or adding trailing blanks as required. A line overflow error is detected whenever the adjustment would shift nonblank characters off the end of the line (or the (@) column range). By default, the replacement is not performed if an overflow occurs, and a “#<sequence number>–SKIPPED.” message is displayed.
The actions taken depending on the length of the target text and replacement text are described in the following:
|
Target and Replacement Text Specification |
Description |
|---|---|
|
Replacement text is the same length as the target text. |
The new text replaces the target text. There is no text shift because of the one-for-one character replacement. |
|
Replacement text is longer than the target text. |
The new text replaces the target text and the text to the right of the target text range is shifted to the right to allow room for the new text. Text is shifted to the right only when the shift does not cause a loss of text; otherwise, the replacement does not take place and a warning message is displayed. If only a single column is specified as the target text, then replacement text is inserted beginning at the specified target column and existing text is shifted to the right of the replacement text. If you do not want to shift text to the right to make up for the difference in the longer replacement text length, then use the @ <start column> – <end column> option to indicate the column range within which the replacement and shifting of text is limited. |
|
Replacement text is shorter than the target text |
The new text replaces the target text and the text to the right of the target text is shifted to the left to take up columns that would otherwise have been left vacant by the shorter length of replacement text. If you do not want to shift text to make up for the difference in replacement text length, use the @ <start column> – <end column> option to indicate the column range within which the replacement of text is to take place without disturbing non-affected text. See the examples later in the description of this command for the use of the @ <start column>-<end column> option. |
<sequence range list>
The sequence range list limits the REPLACE operation to one or more sequence ranges in the work file.
@ <start column> @ <start column>–<end column>
When the @ <start column> form is specified, the REPLACE operation can take place only at the start column position.
When the @ <start column>–<end column> form is specified, the REPLACE operation is limited to the specified column range. The entire column range is included in any left or right justification that might be necessary to adjust for different lengths of target and new text. All text outside this column or column range is not affected in any way by the replacement or any text justification that might occur.
The following examples illustrate this feature:
GET SPORTS #WORKFILE SPORT: SEQ, 1 RECORD, SAVED PAGE NEXT+ ....*....1....*....2....*....3.... 00002000WINDSURFER****SKIS #DISPLAY COMPLETE REPLACE /WINDSURFER/ /SAIL/ @1-10 #WORKFILE SPORT #UPDATING # PAGE NEXT+ ....*....1....*....2....*....3.... 00002000SAIL ****SKIS #DISPLAY COMPLETE
If a different column range is specified for the same work file as before, the results are as indicated in the following example:
REPLACE /WINDSURFER/ /SAIL/ @1-15 #WORKFILE SPORT #UPDATING # PAGE NEXT+ ....*....1....*....2....*....3.... 00002000SAIL****S KIS #DISPLAY COMPLETE
The characters ****s are part of the specified column range, so it is included in the left justification.
SQUEEZE
The SQUEEZE option causes strings of multiple blanks to be shortened (if possible) to make room for the substitution. If sufficient squeezing is impossible, the line is left unsqueezed, the substitution is skipped, and a “#<sequence number>–SKIPPED.” message is displayed.
TRUNCATE
The TRUNCATE option causes the characters shifted off the right side of a line overflow to be lost.
FILE <file name>
The FILE <file name> option causes each line modified by the REPLACE command to be written to a file in the user's library. The file name specifies the title of that file. If the specified file name already exists in the user's library, an error message to that effect is displayed and the text is not replaced.
Files created by the REPLACE command are crunched by default. If an uncrunched file is desired, the output option NOCRUNCH can be specified.
SEQUENCE
The SEQUENCE option causes the sequence number of each line modified by the REPLACE command to be displayed at the terminal. Asterisks (*) in this output flag lines that had more than one replacement.
TEXT
The TEXT option causes each line modified by the REPLACE command to be displayed at the terminal in the modified form. When the TEXT option is used and the PAGEFORMAT option is not specified, all lines that have been marked with a current MARKID will have an asterisk (*) between the sequence number and the rest of the line, unless the REPLACE command has replaced the record ID of the marked lines. For more information about MARKID, refer to the GET, MAKE, and MARKID commands.
The PAGEFORMAT, SQUASHED, and TRUNCATED options apply to the terminal output only and do not affect the line images in the work file.
PAGEFORMAT
When the PAGEFORMAT option is specified, the output appears in a format similar to the page mode output. That is, the full length of the sequence number field is displayed, immediately followed by the contents of the text field (the blank or asterisk flag character is omitted).
SQUASHED
The SQUASHED option causes a sequence of blanks to be printed as a single blank.
TRUNCATED
The TRUNCATED option causes the output line to be truncated to the character width of the terminal, if necessary. By default, lines that exceed terminal width are split across two or more lines.
Examples
The following example shows the REPLACE command with the SEQUENCE and FILE options.
G FRUIT #WORKFILE FRUIT: SEQ, 5 RECORDS, SAVED LIST 100 APPLE ORANGE PEAR 200 GRAPE PLUM APPLE 300 CHERRY APPLE LEMON 400 LIME PEAR BANANA 500 APPLE ORANGE APPLE # REPLACE /APPLE/ /LEMON/ :S #WORKFILE FRUIT #UPDATING 100, 200, 300,*500 # LIST 100 LEMON ORANGE PEAR 200 GRAPE PLUM LEMON 300 CHERRY LEMON LEMON 400 LIME PEAR BANANA 500 LEMON ORANGE LEMON # REPLACE .PEAR..PEACH.:FILE PEACHBOWL #WORKFILE FRUIT #UPDATING # LIST 100 LEMON ORANGE PEAR 200 GRAPE PLUM LEMON 300 CHERRY LEMON LEMON 400 LIME PEAR BANANA 500 LEMON ORANGE LEMON # LIST PEACHBOWL 100 LEMON ORANGE PEACH 400 LIME PEACH BANANA
The following example shows the REPLACE command used with the TEXT option when a current MARKID has been placed in lines 200 and 500.
REPLACE .L..l.:TEXT #WORKFILE FRUIT #UPDATING 100 lEMON ORANGE PEACH 200*GRAPE PLUM lEMON 300 CHERRY lEMON lEMON 400 lIME PEACH BANANA 500*lEMON ORANGE lEMON #
The following examples show the REPLACE command used with the COLUMN option for target text and replacement text manipulation. The following example replaces a column range with another column range of equal length.
PAGE NEXT+ ....*....1....*....2....*....3.... 00002000abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ #DISPLAY COMPLETE REPLACE COL 10-15 COL 25-30 PAGE NEXT+ ....*....1....*....2....*....3.... 00002000abcdefghiyzABCDpqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ #DISPLAY COMPLETE
The following example shows the replacement of text beginning at the specified target column with text from another column range. The existing text to the right of the target column is shifted to the right to accommodate the insertion of the replacement text.
The CANDE PAGE mode is used to show the text replacement.
PAGE NEXT+ ....*....1....*....2....*....3.... 00002000abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ #DISPLAY COMPLETE REPLACE COL 10 COL 25-30 PAGE NEXT+ ....*....1....*....2....*....3.... 00002000abcdefghiyzABCDjklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ #DISPLAY COMPLETE
The following example replaces text within a column range with text from a single column. The replacement text is inserted at the specified target column. Because the replacement text does not entirely occupy the region of the target column range, the existing text not affected by the replacement text is shifted to the left to occupy the unused space.
PAGE NEXT+ ....*....1....*....2....*....3.... 00002000abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ #DISPLAY COMPLETE REPLACE COL 10-15 COL 20 PAGE NEXT+ ....*....1....*....2....*....3.... 00002000abcdefghitpqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ #DISPLAY COMPLETE
The following example replaces text in a column range with text from a single column; however, the column range where the replacement is to take place is specified with the @ <start column>-<end column> option. The replacement text is inserted beginning at the specified target column.
Because the replacement text does not fully occupy the target-column range and a column range is specified with the @ option, the part of the column range not affected by text replacement is filled with blanks.
PAGE NEXT+ ....*....1....*....2....*....3.... 00002000abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ #DISPLAY COMPLETE REPLACE COL 10-15 COL 20 @ 10-15 PAGE NEXT+ ....*....1....*....2....*....3.... 00002000abcdefghit pqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ #DISPLAY COMPLETE
