MHELP sample macro trace and dump

The macro trace and dump (MHELP) facility is a useful means of debugging macro definitions. MHELP can be used anywhere in the source program or in macro definitions. MHELP is processed during macro generation. It is dynamic; you can branch around the MHELP statements by using AIF or AGO statements. Therefore, you can control its use by symbolic parameters and SET symbols. MHELP options remain in effect until superseded by another MHELP statement.

Figure 1 shows a sample program that uses five functions of MHELP. The macro dumps and traces in the listing are highlighted, for example  1A . Most dumps refer to statement numbers. When you call a library macro, the macro name is used instead of the statement number in the identification-sequence field. To get the statement numbers, use the LIBMAC assembler option or the COPY statement to copy the library definition into the source program before the macro call.

MHELP 1, Macro Call Trace
Item  1A  in Figure 1 shows an outer macro call,  1B  in Figure 1 an inner one. In each case, the amount of information given is short. This trace is given after successful entry into the macro; no dump is given if error conditions prevent an entry.
MHELP 2, Macro Branch Trace
This trace provides a one-line trace for each AGO and true AIF branch within a programmer macro. In any such branch, the branched from statement number, the branched to statement number, and the macro name are included, see example  2A  in Figure 1. The branch trace facility is suspended when library macros are expanded and MHELP 2 is in effect. To obtain a macro branch trace for such a macro, use the LIBMAC assembler option or insert a COPY macro-name statement in the source file at some point before the MHELP 2 statement of interest.
MHELP 4, Macro AIF Dump
Items  4A , 4B  ,  1A , 4D  , and 4E  in Figure 1 are examples of these dumps. Each dump includes a complete set of unsubscripted SET symbols with values. This list covers all unsubscripted variable symbols that appear in the same field of a SET statement in the macro definition. Values of elements of dimensioned SET symbols are not displayed.
MHELP 8, Macro Exit Dump
Items  8A  and  8B  in Figure 1 are examples of these dumps. This option provides a dump of the same group of SET symbols as are included in the macro AIF dump when an MEXIT or MEND is encountered.

Local and global variable symbols are not displayed at any point unless they appear in the current macro explicitly as SET symbols.

MHELP 16, Macro Entry Dump
This option provides a dump of the values of system variable symbols and symbolic parameters at the time the macro is called.

If there are k keyword parameters, they are listed as KPARM0001 through KPARM000k in order of appearance on the prototype statement.

If there are p positional parameters, they are listed as PPARM0001 through PPARM000p in order of appearance in the macro instruction.

Item  16A  in Figure 1 has one keyword parameter (&OFFSET) and one positional parameter. In both the prototype (statement 4) and the macro instruction (statement 55), the positional parameter appears in the first operand field, the keyword in the second. A length appears between the NAME and VALUE fields. A length of NUL indicates the corresponding item is empty.

Item  16B  in Figure 1 shows an inner call containing zero keywords and two positional parameters.

MHELP 64, Macro Hex Dump
This option, when used with the Macro AIF dump, the Macro Exit dump, or the Macro Entry dump, dumps the parameter and SETC symbol values in EBCDIC and hexadecimal formats.

The hexadecimal dump precedes the EBCDIC dump, and dumps the full value of the symbol. System parameters are not dumped in hexadecimal.

MHELP 128, MHELP Suppression
This option suppresses all the MHELP options that are active at the time.
MHELP Control on &SYSNDX
The maximum value of the &SYSNDX system variable can be controlled by the MHELP instruction. The limit is set by specifying a number in the operand of the MHELP instruction, that is not one of the MHELP codes defined above, and is in the following number ranges:
  • 256 to 65535
  • Most numbers in the range 65792 to 9999999. Details for this number range are described in the HLASM Language Reference.

When the &SYSNDX limit is reached, message ASMA013S ACTR counter exceeded is issued, and the assembler, in effect, ignores all further macro calls. Refer to the HLASM Language Reference for further information.

Figure 1. Sample program using MHELP (Part 1 of 6)
         Sample Program6 - HLASM                                                                               Page    3
  Active Usings: None
  Loc    Object Code      Addr1    Addr2    Stmt  Source Statement                          HLASM R6.0  2015/02/21 12.58
                                               2 ***********************************************************************
                                               3 *                                                                     *
                                               4 *  Licensed Materials - Property of IBM                               *
                                               5 *                                                                     *
                                               6 *  5696-234                                                           *
                                               7 *                                                                     *
                                               8 *  Copyright IBM Corporation 2008, 2015 All Rights Reserved.          *
                                               9 *                                                                     *
                                              10 *  US Government Users Restricted Rights - Use, duplication           *
                                              11 *  or disclosure restricted by GSA ADP Schedule Contract              *
                                              12 *  with IBM Corp.                                                     *
                                              13 *                                                                     *
                                              14 ***********************************************************************
00000000                00000000 00000034     15 Samp06  Csect
                                              16         ASMDREG        include standard registers
                                              17+         PUSH  PRINT                                                    01-ASMDREG
                                             117+         POP   PRINT                                                    01-ASMDREG
                                             118 * define inline macro inmac1
                                             119         macro
                                             120 &name   inmac1 &arg,&offset=stnumb-stchain
                                             121         lclc &label
                                             122 &label  setc 'A&sysndx'     Generate symbol
                                             123         aif (t'&name eq 'O').skip 
                                             124 &label  setc '&name'      If MACRO call has label, use it 
                                             125 .skip   anop              instead of generated symbol 
                                             126 &label  la 0,&offset      Load register R0 
                                             127         inmac2 &arg,0(R1) Search 
                                             128         bc R1,&label      If max reached, continue 
                                             129         mend 
                                             130 * define inline macro inmac2 
                                             131         macro 
                                             132 &nm     inmac2 &comp,&list 
                                             133         lcla &cnt 
                                             134         lclc &cmpadr 
                                             135 &cnt    seta 1
                                             136 &nm     stm  R1,R15,4(R13)
                                             137 .test   anop 
                                             138 &cmpadr setc '&cmpadr'.'&comp'(&cnt,1)
                                             139         aif ('&comp'(&cnt,1) eq '(').lpar 
                                             140 &cnt    seta &cnt+1 
                                             141         aif (&cnt lt k'&comp).test 
                                             142 .nolnth anop 
                                             143         la  R3,&comp         Comparand 
                                             144         ago .contin 
                                             145 .lpar   aif ('&comp'(&cnt+1,1) eq ',').finish
                                             146 &cnt    seta &cnt+1 
                                             147         aif (&cnt lt k'&comp).lpar 
                                             148         ago .nolnth 
                                             149 .finish anop 
                                             150 &cmpadr setc '&cmpadr'.'&comp'(&cnt+2,k'&comp-&cnt)
                                             151         la  R3,&cmpadr        Comparand minus length 
                                             152 .contin anop 
                                             153         la   R1,&list           Load the address 
                                             154         mvc  &comp,0(R0)        move 
                                             155         l    R15,=v(snow)       get address of module
Figure 2. Sample program using MHELP (Part 2 of 6)
Sample Program6 - HLASM                                                                               Page    4
  Active Usings: None
  Loc    Object Code      Addr1    Addr2    Stmt  Source Statement                          HLASM R6.0  2015/02/21 12.58
                                             156         balr R14,R15             and go execute it
                                             157         lm   R1,R15,4(R13)      restore regs
                                             158         mexit
                                             159         mend
                                             160 *
00000000 05C0                                161         balr R12,0             establish base
                    R:C 00000002             162         using *,R12             and use it
                                             163         mhelp b'11111'         switch macro help on
                                             164         inmac1  listline,offset=listline-listnext

                 1A               ++//MHELP CALL TO MACRO INMAC1      DEPTH=001   SYSNDX=0000002   STMT=00164


                 16B               //MHELP ENTRY TO  INMAC1   MODEL STMT=00000 DEPTH=001 SYSNDX=0000002 KWCNT=001
                                                 ////SYSTEM PARAMETERS:
                                                 //SYSVAR NAME    LNTH  VALUE (56 CHARS/LINE)
                                                 //SYSNDX          004  0002
                                                 //SYSECT          006  Samp06
                                                 //SYSLOC          006  Samp06
                                                 //SYSTIME         005  12.58
                                                 //SYSDATE         008  02/21/15
                                                 //SYSASM          020  HIGH LEVEL ASSEMBLER
                                                 //SYSVER          005  1.6.0
                                                 //SYSDATC         008  20150221
                                                 //SYSJOB          006  SAMP06
                                                 //SYSSTEP         001  C
                                                 //SYSSTYP         005  CSECT
                                                 //SYSSTMT         008  00000165
                                                 //SYSCLOCK        026  2015-02-21 12:58:32.749389
                                                 //SYSNEST         001  1
                                                 //SYSSEQF         008
                                                 //SYSOPT_DBCS     001  0
                                                 //SYSOPT_OPTABLE  003  UNI
                                                 //SYSOPT_RENT     001  0
                                                 //SYSOPT_XOBJECT  001  1
                                                 //SYSTEM_ID       013  z/OS 02.01.00
                                                 //SYSIN_DSN       022  SMORSA.BOOK.SAMPLE.ASM
                                                 //SYSIN_MEMBER    006  SAMP06
                                                 //SYSIN_VOLUME    006  37P003
                                                 //SYSLIB_DSN      022  SMORSA.BOOK.SAMPLE.ASM
                                                 //SYSLIB_MEMBER   006  INMAC1
                                                 //SYSLIB_VOLUME   006  37P003
                                                 //SYSPRINT_DSN    033  SMORSA.SAMP06.JOB47758.D0000102.?
                                                 //SYSPRINT_MEMBER NUL
                                                 //SYSPRINT_VOLUME NUL
                                                 //SYSTERM_DSN     NUL
                                                 //SYSTERM_MEMBER  NUL
                                                 //SYSTERM_VOLUME  NUL
                                                 //SYSPUNCH_DSN    NUL
                                                 //SYSPUNCH_MEMBER NUL
                                                 //SYSPUNCH_VOLUME NUL
                                                 //SYSLIN_DSN      NUL
                                                 //SYSLIN_MEMBER   NUL
                                                 //SYSLIN_VOLUME   NUL
                                                 //SYSADATA_DSN    NUL
Figure 3. Sample program using MHELP (Part 3 of 6)
Sample Program6 - HLASM                                                                               Page    5
  Active Usings: Samp06+X'2',R12
  Loc    Object Code      Addr1    Addr2    Stmt  Source Statement                          HLASM R6.0  2015/02/21 12.58
                                                 //SYSADATA_MEMBER NUL
                                                 //SYSADATA_VOLUME NUL
                                                 //SYSPARM         018  thisisatestsysparm
                                                 //SYSM_SEV        003  000
                                                 //SYSM_HSEV       003  000
                                                 ////NAME; KEYWORD PARAMETERS; POSITIONAL PARAMETERS:
                                                 //PARAMETER      LNTH  VALUE (54 CHARS/LINE)
                                                 //NAME            NUL
                                                 //KPARM0001       017  listline-listnext
                                                 //PPARM0001       008  listline


                 1A                //MHELP AIF IN    INMAC1   MODEL STMT=00123 DEPTH=001 SYSNDX=0000002 KWCNT=001
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLC       LABEL                                         LNTH= 005
                                                 //     VAL=A0002


                 2A               ++//MHELP  BRANCH FROM STMT 00123 TO STMT 00125 IN MACRO INMAC1

00000002 4100 0002               00000002    165+A0002   la 0,listline-listnext                                         X01-00000126
                                                +                          Load register R0

                 1B               ++//MHELP CALL TO MACRO INMAC2      DEPTH=002   SYSNDX=0000003   STMT=00127


                 16A               //MHELP ENTRY TO  INMAC2   MODEL STMT=00000 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SYSTEM PARAMETERS:
                                                 //SYSVAR NAME    LNTH  VALUE (56 CHARS/LINE)
                                                 //SYSNDX          004  0003
                                                 //SYSECT          006  Samp06
                                                 //SYSLOC          006  Samp06
                                                 //SYSTIME         005  12.58
                                                 //SYSDATE         008  02/21/15
                                                 //SYSASM          020  HIGH LEVEL ASSEMBLER
                                                 //SYSVER          005  1.6.0
                                                 //SYSDATC         008  20150221
                                                 //SYSJOB          006  SAMP06
                                                 //SYSSTEP         001  C
                                                 //SYSSTYP         005  CSECT
                                                 //SYSSTMT         008  00000167
                                                 //SYSCLOCK        026  2015-02-21 12:58:32.749431
                                                 //SYSNEST         001  2
                                                 //SYSSEQF         008
                                                 //SYSOPT_DBCS     001  0
                                                 //SYSOPT_OPTABLE  003  UNI
                                                 //SYSOPT_RENT     001  0
                                                 //SYSOPT_XOBJECT  001  1
                                                 //SYSTEM_ID       013  z/OS 02.01.00
                                                 //SYSIN_DSN       022  SMORSA.BOOK.SAMPLE.ASM
                                                 //SYSIN_MEMBER    006  SAMP06
                                                 //SYSIN_VOLUME    006  37P003
                                                 //SYSLIB_DSN      022  SMORSA.BOOK.SAMPLE.ASM
                                                 //SYSLIB_MEMBER   006  INMAC2
                                                 //SYSLIB_VOLUME   006  37P003
Figure 4. Sample program using MHELP (Part 4 of 6)
        Sample Program6 - HLASM                                                                               Page    6
  Active Usings: Samp06+X'2',R12
  Loc    Object Code      Addr1    Addr2    Stmt  Source Statement                          HLASM R6.0  2015/02/21 12.58
                                                 //SYSPRINT_DSN    033  SMORSA.SAMP06.JOB47758.D0000102.?
                                                 //SYSPRINT_MEMBER NUL
                                                 //SYSPRINT_VOLUME NUL
                                                 //SYSTERM_DSN     NUL
                                                 //SYSTERM_MEMBER  NUL
                                                 //SYSTERM_VOLUME  NUL
                                                 //SYSPUNCH_DSN    NUL
                                                 //SYSPUNCH_MEMBER NUL
                                                 //SYSPUNCH_VOLUME NUL
                                                 //SYSLIN_DSN      NUL
                                                 //SYSLIN_MEMBER   NUL
                                                 //SYSLIN_VOLUME   NUL
                                                 //SYSADATA_DSN    NUL
                                                 //SYSADATA_MEMBER NUL
                                                 //SYSADATA_VOLUME NUL
                                                 //SYSPARM         018  thisisatestsysparm
                                                 //SYSM_SEV        003  000
                                                 //SYSM_HSEV       003  000
                                                 ////NAME; KEYWORD PARAMETERS; POSITIONAL PARAMETERS:
                                                 //PARAMETER      LNTH  VALUE (54 CHARS/LINE)
                                                 //NAME            NUL
                                                 //PPARM0001       008  listline
                                                 //PPARM0002       005  0(R1)

00000006 901F D004               00000004    167+        stm  R1,R15,4(R13)                                              02-00000136

                                                 //MHELP AIF IN    INMAC2   MODEL STMT=00139 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000001
                                                 //0002 LCLC       CMPADR                                        LNTH= 001
                                                 //     VAL=l


                                                 //MHELP AIF IN    INMAC2   MODEL STMT=00141 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000002
                                                 //0002 LCLC       CMPADR                                        LNTH= 001
                                                 //     VAL=l


                 2A               ++//MHELP  BRANCH FROM STMT 00141 TO STMT 00137 IN MACRO INMAC2


                                                 //MHELP AIF IN    INMAC2   MODEL STMT=00139 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000002
                                                 //0002 LCLC       CMPADR                                        LNTH= 002
                                                 //     VAL=li


                                                 //MHELP AIF IN    INMAC2   MODEL STMT=00141 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000003
                                                 //0002 LCLC       CMPADR                                        LNTH= 002
                                                 //     VAL=li
Figure 5. Sample program using MHELP (Part 5 of 6)
Sample Program6 - HLASM                                                                               Page    7
  Active Usings: Samp06+X'2',R12
  Loc    Object Code      Addr1    Addr2    Stmt  Source Statement                          HLASM R6.0  2015/02/21 12.58


                 2A                ++//MHELP  BRANCH FROM STMT 00141 TO STMT 00137 IN MACRO INMAC2


                 4B                //MHELP AIF IN    INMAC2   MODEL STMT=00139 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000003
                                                 //0002 LCLC       CMPADR                                        LNTH= 003
                                                 //     VAL=lis


                 4C                //MHELP AIF IN    INMAC2   MODEL STMT=00141 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000004
                                                 //0002 LCLC       CMPADR                                        LNTH= 003
                                                 //     VAL=lis


                 2A               ++//MHELP  BRANCH FROM STMT 00141 TO STMT 00137 IN MACRO INMAC2


                 4D                //MHELP AIF IN    INMAC2   MODEL STMT=00139 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000004
                                                 //0002 LCLC       CMPADR                                        LNTH= 004
                                                 //     VAL=list


                 4E                //MHELP AIF IN    INMAC2   MODEL STMT=00141 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000005
                                                 //0002 LCLC       CMPADR                                        LNTH= 004
                                                 //     VAL=list


                 2A               ++//MHELP  BRANCH FROM STMT 00141 TO STMT 00137 IN MACRO INMAC2


                                                 //MHELP AIF IN    INMAC2   MODEL STMT=00139 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000005
                                                 //0002 LCLC       CMPADR                                        LNTH= 005
                                                 //     VAL=listl


                                                 //MHELP AIF IN    INMAC2   MODEL STMT=00141 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000006
                                                 //0002 LCLC       CMPADR                                        LNTH= 005
                                                 //     VAL=listl


                 2A                ++//MHELP  BRANCH FROM STMT 00141 TO STMT 00137 IN MACRO INMAC2
Figure 6. Sample program using MHELP (Part 6 of 6)
Sample Program6 - HLASM                                                                               Page    8
  Active Usings: Samp06+X'2',R12
  Loc    Object Code      Addr1    Addr2    Stmt  Source Statement                          HLASM R6.0  2015/02/21 12.58

                                                 //MHELP AIF IN    INMAC2   MODEL STMT=00139 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000006
                                                 //0002 LCLC       CMPADR                                        LNTH= 006
                                                 //     VAL=listli


                                                 //MHELP AIF IN    INMAC2   MODEL STMT=00141 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000007
                                                 //0002 LCLC       CMPADR                                        LNTH= 006
                                                 //     VAL=listli


                 2A               ++//MHELP  BRANCH FROM STMT 00141 TO STMT 00137 IN MACRO INMAC2


                                                 //MHELP AIF IN    INMAC2   MODEL STMT=00139 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000007
                                                 //0002 LCLC       CMPADR                                        LNTH= 007
                                                 //     VAL=listlin


                                                 //MHELP AIF IN    INMAC2   MODEL STMT=00141 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000008
                                                 //0002 LCLC       CMPADR                                        LNTH= 007
                                                 //     VAL=listlin

0000000A 4130 C026               00000028    168+        la  R3,listline      Comparand                                  02-00000143

                 2A                ++//MHELP  BRANCH FROM STMT 00144 TO STMT 00152 IN MACRO INMAC2

0000000E 4111 0000               00000000    169+        la   R1,0(R1)           Load the address                        02-00000153
00000012 D202 C026 0000 00000028 00000000    170+        mvc  listline,0(R0)     move                                    02-00000154
00000018 58F0 C02E               00000030    171+        l    R15,=v(snow)       get address of module                   02-00000155
0000001C 05EF                                172+        balr R14,R15             and go execute it                      02-00000156
0000001E 981F D004               00000004    173+        lm   R1,R15,4(R13)      restore regs                            02-00000157

                 8A                //MHELP EXIT FROM INMAC2   MODEL STMT=00158 DEPTH=002 SYSNDX=0000003 KWCNT=000
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLA       CNT                                           VAL=  0000000008
                                                 //0002 LCLC       CMPADR                                        LNTH= 007
                                                 //     VAL=listlin

00000022 4710 C000               00000002    174+        bc R1,A0002       If max reached, continue                      01-00000128

                 8B                //MHELP EXIT FROM INMAC1   MODEL STMT=00129 DEPTH=001 SYSNDX=0000002 KWCNT=001
                                                 ////SET SYMBOLS (SKIPPED NUMBERS MAY BE SEQUENCE SYMBOLS).//
                                                 //0001 LCLC       LABEL                                         LNTH= 005
                                                 //     VAL=A0002

00000026                                     175 listnext ds h'0'
         Sample Program6 - HLASM                                                                               Page    9
  Active Usings: Samp06+X'2',R12
  Loc    Object Code      Addr1    Addr2    Stmt  Source Statement                          HLASM R6.0  2015/02/21 12.58
00000028                                     176 listline ds fl3'0'
00000030                                     177          ltorg
00000030 00000000                            178                =v(snow)
00000000                                     179          end Samp06