CHG_VAR

Figure 1. Syntax

1  CHG_VAR ( name ,
1  old ,? new
1  , new
2  ,
1! 1
1 count
3  ,
1! 1
1 start
4  ,
1! 0
1 length
5  ,
1! ''
1 text_char
6  )

(Can be used in FASTREXX procedures.)

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

Changes one or more occurrences of an old string in the variable 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 variable.

Returns
A single blank.
name
1–256 character variable identifier. Variable name matching is not case sensitive. If the name is not found, a severe error occurs and the procedure is terminated. Cannot be a system character variable or a system numeric variable. See Using FASTREXX variables.
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 a 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 a 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.
start
Position, in bytes, in the variable 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 variable, the function has no effect.
Relative to current variable position
Can be specified as OPx or ONx, or as Px or Nx, or 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 variable, the function has no effect.
length
Amount, in bytes, of the variable 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_VAR 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_VAR behaves in this way:

  • If the new and old strings are the same length, CHG_VAR 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_VAR 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 File Manager 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_VAR 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 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 variable contains 'abcabcabcabcabcabcabc', then:

CHG_VAR(MYVAR,'abc','DeF',0)
/*  All occurrences of old within the             */
/*  variable are changed                          */

The variable becomes 'DeFDeFDeFDeFDeFDeFDeF'.

Example 2

Assuming that the current variable contains 'abcabcabcabcabcabcabc', then:

CHG_VAR(MYVAR,'abc','DeF',,4)
/*  1 (default) occurrences of old changed,       */
/*  starting at position 4 within the variable    */

The variable becomes 'abcDeFabcabcabcabcabc'.

Example 3

Assuming that the current variable contains 'aaaaaaaaaa', then:

CHG_VAR(MYVAR,'a','A',0,3,2)
/*  all occurrences of old changed, starting at   */
/*  position 3 in the variable, for a length of 2 */

The variable becomes 'aaAAaaaaaa'.

Example 4

Assuming that the current variable contains 'abcabcabcabcabcabcabc', and that current variable position is 4, then:

CHG_VAR(MYVAR,'abc','DeF',1,P3)
/*  1 occurrence of old changed,                  */
/*  uses current position as the default target, therefore  */
/*  starts at position 7 within the variable      */

The variable becomes 'abcabcDeFabcabcabcabc' and the variable position is set to 10.

Example 4

Assuming that the current variable contains 'abcabcabcabcabcabcabc', and that current variable position is currently set to 13, then:

CHG_VAR(MYVAR,'abc','DeF',1,IN3)
/*  1 occurrence of old changed,                  */
/*  forces start to use current position value, therefore   */
/*  starts at position 10 within the variable     */

The variable becomes 'abcabcabcDeFabcabcabc' and the variable position is set to 13.