Purpose, Argument, Streams, Usage, Examples, Related

                                    ┌─STRing─┐
>>──CHANGE──┬─────────┬──┤ Range ├──┼────────┼──fromstring──tostring──┬───────────┬──>< 
            └─ANYCase─┘             └─REGexp─┘                        └─maxchange─┘

Range:

   ┌─1-*─────────────────┐
├──┼─────────────────────┼────────────────────────────────────────────────────────────┤ 
   ├──columnrange────────┤ 
   │   ┌─<───────────┐   │
   └─(─┴─columnrange─┴─)─┘

Notes:
(1) columnrange is unsigned.

Use the CHANGE stage to replace a character or string of characters with another character or string of characters of the same or different length. CHANGE reads records from its primary input stream, replacing any occurrences of fromstring that are found within the specified columnrange with tostring, and writes the records to its primary output stream. If fromstring does not appear in an input record, CHANGE writes the record unchanged to its secondary output stream, if it is connected, otherwise it writes the unchanged record to its primary output stream.

• ANYCase
  when specified in conjunction with the STRING keyword; the case of letters are preserved in the following manner:
  
  The text specified in fromstring and in the input record are compared in uppercase. If fromstring is found and contains one or more uppercase characters or contains no letters; then tostring replaces the given text in the output record without change of case. Otherwise, an attempt is made to preserve the case of the text being replaced. When the text contains no uppercase letters and starts with one or more lowercase letters, the following rules determine the case of the replacement text in tostring.
  
  
  • When the first two characters of the text in the input record are both lowercase, tostring is used without change.
  • When the first two characters of the text in the input record are uppercase, the whole of tostring is translated to uppercase.
  • When the first character of the text in the input record is uppercase and the second one is lowercase (or not a letter, or the string is only one character in length), the first letter of tostring is translated to uppercase.
    
    
  When specified in conjunction with the REGEXP keyword; the regular expression fromstring is compared with the contents of an input record without regard to case.
  
  
• columnrange
  is an unsigned integer column range in which to search for fromstring. If you do not specify columnrange, CHANGE searches the entire record for occurrences of fromstring. You can specify any number of columnrange operands. If you specify more than one, you must place at least one space between each columnrange and you must enclose the set of columnrange operands within parentheses. If you specify more than one columnrange operand, the range of columns must not overlap.
  
  
• STRing
  specifies that the fromstring and tostring operands are literal strings.
  
  
• REGexp
  specifies that the fromstring operand is a regular expression of characters to locate and the tostring operand is an expression format string.
  
  
• fromstring
  in conjunction with the STRING keyword; fromstring defines a string that is to be replaced by tostring. If you specify a null string for fromstring, CHANGE inserts tostring immediately before the first column of the columnrange which defines the leftmost column of the record. When used in conjunction with the REGEXP keyword; fromstring is a regular expression of characters to locate.
  
  If columnrange is not specified and if both fromstring and tostring consist only of decimal numbers (0-9), you cannot specify a left parenthesis or a number as the delimiting character.
  
  
• tostring
  in conjunction with the STRING keyword; tostring defines a string that is to replace fromstring. If you specify a null string for tostring, CHANGE deletes occurrences of fromstring within the range or ranges you specify for columnrange. When used in conjunction with the REGexp keyword; tostring defines a format string which specifies the way in which the occurrences of the expression fromstring are to be changed/formatted.
  
  
  • maxchange
    is an unsigned integer which defines the maximum number of occurrences of fromstring to be changed in each input record. If you do not specify maxchange, all occurrences of fromstring within the range or ranges you specify for columnrange are changed. If you specify a null string for fromstring, 1 is the default value for maxchange and 1 is the only value allowed for maxchange.

1. CHANGE does not delay the records.
   
   
2. If the CHANGE stage discovers that all of its output streams are not connected, the CHANGE stage ends.
   
   
3. If columnrange is not specified and if both fromstring and tostring consist of only decimal numbers (0-9), you cannot specify a left parenthesis or a number as the delimiting character. For example:
   
   

   change /8//9/
   

   
   is not equivalent to:
   
   

   change 383393
   

   
   The first CHANGE stage changes the string 8 to 9. The second stage results in an error message because 383393 is processed as a columnrange operand rather than a delimited string. The error message is issued because fromstring and tostring are missing and they are required operands.
   
   
4. CHANGE can also be used to delete words. By specifying a NULL tostring; for instance '//', CHANGE will effectively delete the word specified by fromstring. See the following example:
   
   Deleting words
   
   
5. CHANGE verifies that its secondary input stream is not connected and then begins execution.

The following examples of the CHANGE stage command use the ANYCASE keyword and the rules that apply for preserving the case of letters.

1. 'pipe literal /Mick/ | change anycase /mick/ /mack/ | console'
   
   output:
   
   Mack
   

   
   

2. 'pipe literal /Mack MacNeill/ | change anycase /mac/ /mc/ | console' 
   
   output:
   
   Mck McNeill
   

   
   

3. 'pipe literal /Mack MacNeill/ | change anycase /macn/ /mcn/ | console' 
   
   output:
   
   Mack Mcneill
   

   
   

4. 'pipe literal /Mack MacNeill/ | change anycase /macn/ /mcN/ | console' 
   
   output:
   
   Mack McNeill
   

   
   

5. 'pipe literal /Mack MacNeill/ | change anycase /Macn/ /mcn/ | console' 
   
   output:
   
   Mack mcneill
   

   
   

6. 'pipe literal /Mack MacNeill/ | change anycase /MacN/ /McN/ | console' 
   
   output:
   
   Mack McNeill
   

   
   
7. If we revisit our example above; we will also notice that a regular expression is used to select both upppercase and lowercase combinations of the word 'the' with the ANYCASE keyword.
   
   Deleting words

SPECS, TRANSLATE