Re-entrant assembler macros in z/OS

In a C program on z/OS you can code assembler macros. See Putting assembler code inside a C program

I wanted to use a WTO/WTOR macro to put a message onto the operator console. This took a few hours to get working, firstly I needed to understand using Re-entrant macros, and secondly see Using Re-entrant assembler macros in C ASM().

Background to using re-entrant macros in assembler

Programming in assembler

You can write a macro like

   WTO  'Colins message'

This generates code

         WTO   'Colin'               
             
         BRAS  1,LABEL1    Set register 1 to the following DC and jump to the label         
LENDATA  DC    AL2(9)                
         DC    B'0000000000000000'   
         DC    C'Colin'              
LABEL1   DS    0H
         SVC   35                     

This works.

I can pass a string to the macro – a half word length followed by the data – like LENDATA above. This makes the WTO macro more complex.

You can pass a variable content message to WTO. The code following

• creates data in the correct format (length followed by the data).
• The WTO creates the data structure
• The WTO updates the data structure from the data passed to the macro

* define the variable data, and point register 2 to it
          BRAS  2,OVERTEXT                                       
DATA      DC    AL2(5)                 Length of string                               
          DC    C'Colin'               the data to display                         
 
* invoke WTO. (2) says the address of the data is in register 2
OVERTEXT DS    0H                                              
          WTO   TEXT=(2) 

* This generates...                                       
          CNOP  0,4                                             
          BRAS  1,TWOLABA              branch around definition
* The WTO data structure
          DC    AL2(8)                   TEXT LENGTH           
          DC    B'0000000000010000'      MCSFLAGS              
TEXTADDR  DC    AL4(0)                   MESSAGE TEXT ADDRESS  
          .. 
* The instructions to update the data structure from the passed data
WTOLABA   DS    0H                                                 
          LR    14,1                     FIRST BYTE OF PARM LIST   
          SR    15,15                    CLEAR REGISTER 15         
          AH    15,0(1,0)                ADD LENGTH OF TEXT + 4    
          AR    14,15                    FIRST BYTE AFTER TEXT     
          ST    2,4(0,1)                 STORE TEXT ADDR INTO PLIST
          SVC   35                       ISSUE SVC 35              

Where

• BRAS 2,OVERTEXT saves in register 2 the address of data, then branches to the label OVERTEXT
• BRAS 1,WTOLABA saves in register 1 the address of the structure following the instruction, then branches to label WTOLABA
• ST 2,4(0,1) this saves what register 2 points to – my data; and stores it at the front of the control block data in field TEXTADDR

This fails to execute because the whole program is Re-entrant (RENT) and so the whole program is read only. The program is trying to store register 2 into read only storage.

Solving the RENT problem.

The problem of trying to write into read only storage is solved splitting the above code into two parts and using thread read write storage.

• define the structure for the constants in read only storage
• copy the read only structure to thread read write storage
• use the thread read write storage for the request.

Define the structure for the constants in read only storage

You use an extra parameter on the macro call

WTOS      WTO TEXT=(),MF=L  
ETWOS     DS   0H 

This generates code

WTOS     WTO   TEXT=(),MF=L                                       
WTOS     DS    0F                                                  
         DC    AL2(8)                   TEXT LENGTH           
         DC    B'0000000000010000'      MCSFLAGS                   
         DC    AL4(0)                   MESSAGE TEXT ADDRESS       
         ...          
         DC    AL4(0)                   WSPARM ADDRESS             
ETWOS    DS    0H                                                  

This has created the data structure. The data is of length EWTOS-WTOS

Copy the read only structure to thread read write storage

In assembler you can use MVC or MVCL to copy from the read only data to thread read/write storage.

Use the thread read write storage for the request.

If the static part of the structure was copied to the block of storage userdata, the code below will issue the WTO request

WTOL   WTO TEXT=((2)),MF=(E,userdata)

This generates the code to update the structure in read only storage

         WTOR  TEXT=((2)),MF=(E,userdata)                                
         LA    1,userdata               LOAD PARAMETER REG   
         LR    14,1                     FIRST BYTE OF PARM LIST     
         SR    15,15                    CLEAR REG 15               
         AH    15,0(1,0)                ADD LENGTH OF TEXT + 4     
         AR    14,15                    ADDR OF BYTE AFTER TEXT   
         ST    2,4(1,0)                 MOVE TEXT INTO PARM LIST    
         OI    4(14),B'00000000'        SET EXTENDED MCS FLAGS      
         OI    5(14),B'10000000'        SET EXTENDED MCS FLAGS2     
         SVC   35                       ISSUE SVC 35                

Note:

Some z/OS components use MF=(S,name) to generate the Static structure with the specified name, others use MF=(L).

They all use MF=(E,name).