ALTER (Macro)

Notes:

¹ You can only specify G, if you specified target as a number.

Purpose

Use the ALTER macro to change a single character to another character, one that may not be available on your terminal keyboard. The ALTER macro allows you to reference characters by their hexadecimal values.

Operands

char1: is the character to be altered. It may be specified either as a single character or in hexadecimal notation (00 through FF).
char2: specifies the character to which char1 is to be altered. It may be specified either as a single character or in hexadecimal notation.
target: defines the number of lines to be searched for char1. The search for char1 starts with the current line and continues to, but does not include, the target line. If you specify an asterisk (*), the search continues to the end of the file (or the end of the range — see SET RANGE.) If target is not specified, only the current line is altered.
You can specify a target as an absolute line number, a relative displacement from the current line, a line name, or a string expression. For more information on targets, see LOCATE and z/VM: XEDIT User's Guide.
n: is the number of occurrences of char1 to be altered in each line examined. If you specify an asterisk (*), all occurrences of char1 are altered. If n is not specified, only one occurrence of char1 in each line is altered. For compatibility with the CMS editor (EDIT), you can specify the G (Global) operand, but only when you specify target as a number.
p: specifies the relative number of the first occurrence of char1 to be altered in each line examined. If p is not specified, the alteration starts with the first occurrence of char1 in a line.

Examples

This section shows an example of the ALTER macro. For more information, see z/VM: XEDIT User's Guide.

To produce compound characters on printed output, you can use ALTER to change a special character to a backspace character.

Current Line:

===== Please underline T$_H$_I$_S$_

alter  $  16  1  *

(alter $ to X'16' each time it appears in current line)

===== Please underline T _H _I _S _

When printed, the line looks like this:

Please underline THIS

Responses

The column pointer remains unchanged.

If SET STAY OFF is in effect (the default), the last line examined becomes the new current line.

If SET STAY ON is in effect, the line pointer remains unchanged.

When verification is on, every line that is changed is displayed.

On a display terminal, when verification is off and a change has been made, the following message is displayed:

517I  nn occurrence(s) changed on nn line(s)

Messages and Return Codes

520E: Invalid operand: operand [RC=5]
543E: Invalid number: number [RC=5]
545E: Missing operand(s) [RC=5]
546E: Target not found [RC=2]
585E: No line(s) changed [RC=4]

where return codes are:

0: Normal
1: TOF or EOF reached
2: Target line not found
4: No change occurred
5: Invalid or missing operand(s) or invalid number
6: Subcommand rejected in the profile due to LOAD error, or QUIT subcommand has been issued in a macro called from the last file in the ring