Writing IDF macros

Edit online

You can tailor IDF through the use of REXX programs (macros) that IDF invokes. These macros have a default ADDRESS of "ASM".

z/VM®

The default ADDRESS environment upon entry to an IDF macro is in the form of a PSW. This instructs REXX to use a LPSW to invoke IDF commands directly, whereas the "address IDF" environment requires a CMSCALL linkage to IDF commands.

The "ASM" subcommand environment is still provided to your macros, and it is still perfectly fine to explicitly direct most IDF commands through this named environment. However, the MRUN and MSTEP commands "behave better" if they are directed through the default "LPSW fastpath" interface.

See the usage notes under MRUN for MRUN considerations, and see REXX linkage considerations for details about the available methods for invoking IDF commands from REXX.

Most IDF commands can be issued within a macro. In particular, you can use the SET and EXTRACT commands to set or extract the settings of various parameters, and the target program's memory and registers.

IDF commands may be abbreviated as shown in Abbreviations. There are many potential uses for IDF macros. A few examples are:
  • Provide a "swap" PF key to swap to another set of PF key definitions
  • Set a number of predefined breakpoints for a program you are testing repeatedly
  • XEDIT the listing file for the program you are debugging
  • Redefine the ENTER key so that you can use your own syntax for expressions
An IDF macro:
  • On CMS, can have any file name that you like, but the file type must be ASM.
  • On z/OS®, it must be a member of the PDSs allocated to the ASM DD name, with any member name that you like.
  • On z/VSE®, it must be a member in a sublibrary in the active PROC chain.
  • Must be written in the REXX language. It may optionally be compiled by the REXX compiler, in which case the file type (DD name on z/OS) of the compiled EXEC must be ASM.
You can invoke a macro in several ways:
  • Assuming that your ENTER key retains the default assignment of COMMAND, you can enter MACRO, followed by the name of your macro and any arguments it requires, on the command line and press ENTER.
  • If you have specified the IMPMACRO option, you can type the macro's name on the command line (without prefixing it with MACRO), followed by any necessary arguments, and press ENTER.
  • You can set a PF key to MACRO myname args and press the PF key.
  • You can issue the macro from within your PROFILE macro.
Your macro can issue any IDF commands you like. These are treated as if they had been invoked by means of a PF key.
Here is an example of a special purpose macro that sets up some breakpoints, opens a Disassembly window, and runs the target program to the first breakpoint:
Figure 1. Example of a special purpose macro
/* ALLOPEN ASM */
'set break on loop'
'set break on exit'
'disasm'
'run'
exit 0

IDF propagates the return code from your macro to the caller if it is invoked by another IDF macro.

If the top level macro exits with a nonzero return code, IDF issues a message, so if you want to perform your own message handling you need to exit with a return code of zero.

There are times when one of several macros is setting an IDF option, and it is difficult to determine just where the option is being set. The MACROLOG option helps debug this sort of macro problem. Whenever this option is in effect, all IDF commands that are issued by either an IDF macro or a IDF exit routine are written to the macro log. See MACROLOG for the name of this log.

Warning: Be careful when executing CMS commands from within your macro. If you are debugging a user-area program, and your macro invokes another program that runs in the user area, it destroys your debugging environment. The same care should be taken with routines that run in the transient area.

Numbers in expressions can be specified in explicit (X'123', F'123') or implicit (123) notation. Numbers that do not explicitly specify the base are evaluated according to the current setting of the HEXINPUT option. When writing macros it is recommended that you use explicit base notation.