CHG_OUT

Read syntax diagramSkip visual syntax diagram
Syntax

                                       .-1-----.      
>>-CHG_OUT--(--+-old--,--+-----+-+--,--+-------+--,------------->
               |         '-new-' |     '-count-'      
               '-,--new----------'                    

   .-1-----.     .-0------.     .-''--------.      
>--+-------+--,--+--------+--,--+-----------+--)---------------><
   '-start-'     '-length-'     '-text_char-'      

Note: Commas following the last specified argument can be omitted.

Can be used in FASTREXX procedures.

Changes one or more occurrences of an old string in the output record to a new string. On successful execution, also updates the value of OUTPOS to one byte past the end of the last changed field in the output record.

Returns
A single blank.
old
Old string to change. If this argument is omitted, the new string is inserted at the start location.
You can substitute a character or numeric variable or tally literal by specifying an &varname where varname matches an existing variable name.
Note:
  1. Numeric values are converted to display form with leading zeros removed.
  2. If a variable name is not found, then the string is interpreted as literal.
new
New string. If this argument is omitted, then count occurrences of old are deleted.
You can substitute a character or numeric variable or tally literal by specifying an &varname where varname matches an existing variable name.
Note:
  1. Numeric values are converted to display form with leading zeros removed.
  2. If a variable name is not found, then the string is interpreted as literal.
count
Maximum number of occurrences of old to change. Must be a non-negative integer. Default value is 1. A value of 0 indicates that all occurrences should be changed, unless the old string field is omitted, in which case it is equivalent to a value of 1.
start
Position, in bytes, in the output record at which to start searching for occurrences of old. Can be specified as:
Absolute position
Must be a positive integer. Default value is 1. If start is greater than the current length of the output record, the function has no effect.
Relative to current INPOS
Must be specified as IPx or INx. If this resolves to a value of less than or equal to zero, the function results in an error. If this resolves to a value that is greater than the current length of the output record, the function has no effect.
Relative to current OUTPOS
Can be specified as OPx or ONx, or as Px or Nx.If this resolves to a value of less than or equal to zero, the function results in an error. If this resolves to a value that is greater than the current length of the output record, the function has no effect.
length
Amount, in bytes, of the output record to search for occurrences of old. Must be a non-negative integer. Default value is 0. A value of 0 indicates that the remainder of the output from start should be searched. If length is less than the length of old, the function has no effect.
text_char
Can be a null string or a single character.

Specifying a null string (the default), indicates CHG_OUT should behave without text sensitivity.

Specifying a single character defines the special text-sensitive character and indicates that text-sensitive change behaviour is required. When a character has been specified for text_char, CHG_OUT behaves as follows:
  • If the new and old strings are the same length, CHG_OUT behaves as if text-sensitive change behaviour had not been requested.
  • If the new string is shorter than the old string, then when a replacement is made, CHG_OUT searches for the first text_char character following the end of the replaced string. Note that the entire record is searched. If the text_char character is found, additional text_char characters are inserted at the point of this first subsequent character, to make up the difference in length between new and old. If the text_char character is not found in the remainder of the record, then no insertion takes place and the record is reduced in length. If the record is fixed-length and no subsequent action occurs to make up the shortfall, then the Z Data Tools record padding process fills out the record when it is written.

    The intended effect is that text on multiple lines, if aligned in columns separated by the text char character, continues to align in columns after replacement. This is useful for updating files with sequence numbers on the right, such as COBOL or JCL.

  • When the new string is longer than the old string., then when a replacement is made, CHG_OUT searches to the right of the replaced string for two consecutive text_char characters. Note that the entire record is searched. If two consecutive text_char characters are found, they are replaced with a single text_char character. This process is repeated, starting from the remaining single character (and including that character) until the length difference between old and new is accounted for. Using this algorithm, multiple text_char characters can be reduced to a single text_char character, but a single text_char char character between other characters is never eliminated.

    The intended effect is to try to use existing "blank" areas in the string, to leave text on the right unchanged as much as possible. There is no guarantee that there will be an adequate number of text_char characters to accomplish the goal. If there are not enough text_char characters, then the rest of the record is shifted right and possibly truncated when it is written, if fixed in length. This is useful for modifying files like COBOL or JCL source, where a sequence number may exist to the right.

  • If you have specified multiple string replacements (count is greater than 1), then the intent remains the same. The search proceeds from left to right, firstly checking for the search argument, and secondly text_char characters to expand or collapse. If the search argument is found, it is replaced and the search continues immediately following the replaced string.
  • Note that the string replacement may be limited to byte positions by the length argument. However, the search for text char characters to add or remove continues past that limit to the end of the record if required.

Example 1

Assuming that the current output record contains 'abcabcabcabcabcabcabc', then:

CHG_OUT('abc','DeF',0)
/*  All occurrences of old within the            */
/*  output record are changed                             */

The output record becomes 'DeFDeFDeFDeFDeFDeFDeF'.

Example 2

Assuming that the current output record contains 'abcabcabcabcabcabcabc', then:

CHG_OUT('abc','DeF',,4)
/*  1 (default) occurrences of old changed,      */
/*  starting at position 4 within the output record       */

The output record becomes 'abcDeFabcabcabcabcabc'.

Example 3

Assuming that the current output record contains 'aaaaaaaaaa', then:

CHG_OUT('a','A',0,3,2)
/*  all occurrences of old changed, starting at  */
/*  position 3 in the output record, for a length of 2    */

The output record becomes 'aaAAaaaaaa'.

Example 4

Assuming that the current output record contains 'abcabcabcabcabcabcabc', and that INPOS is currently set to 13 and OUTPOS is currently set to 4, then:

CHG_OUT('abc','DeF',1,P3)
/*  1 occurrence of old changed,                 */
/*  uses OUTPOS as the default target, therefore          */
/*  starts at position 7 within the output record         */

The output record becomes 'abcabcDeFabcabcabcabc' and OUTPOS is set to 10 (INPOS remains unchanged).

Example 5

Assuming that the current output record contains 'abcabcabcabcabcabcabc', and that INPOS is currently set to 13 and OUTPOS is currently set to 4, then:

CHG_OUT('abc','DeF',1,IN3)
/*  1 occurrence of old changed,                 */
/*  forces start to use INPOS value, therefore            */
/*  starts at position 10 within the output record        */

The output record becomes 'abcabcabcDeFabcabcabc' and OUTPOS is set to 13 (INPOS remains unchanged).