Compiler

Linkage. Calling a Metal C Program

Calling a Metal C program from an assembler program depends on the amode of the called Metal C program. For more details about linkage conventions consult: z/OS Metal C Programming Guide and Reference^©, Chapter 1. About IBM z/OS Metal C.

For AMODE 31

The pointer to the parameter list is in GPR 1.
GPR 13 contains the pointer to the dynamic storage area (DSA).
The parameter list consists of a list of addresses, each address corresponding to a parameter, each address is a full word 4 bytes) in length.
72-byte save area with the standard 18-word format.

For AMODE 64

The pointer to the parameter list is in GPR 1.
GPR 13 contains the pointer to the dynamic storage area (DSA).
The parameter list consists of a list of addresses, each address corresponding to a parameter, each address is a double word 8 bytes) in length.
Save area is 36-word F4SA format; compiler generates code to set up the F4SA signature in the second word of the save area.

To pass a parameter by reference, specify a pointer of the type to be passed in the function prototype. For any addressing mode, integer type values are returned in GPR 15. For AMODE 31 a 64-bit integer value is returned in GPR 15 + GPR 0.

NAB linkage extension

Metal C code uses the dynamic storage area (DSA) as stack space. Each time a function is called, its prolog code acquires this space and upon return releases it. To avoid excessive overhead from acquisition and release operations, Metal C uses an upward growing stack or next available byte (NAB) for the DSA. All Metal C runtime library functions expect the NAB address to be set by the calling function.

If a routine is a main routine, then the prolog code for the routine will perform a STORAGE OBTAIN for its DSA, and a STORAGE RELEASE upon termination.

Example of NAB

Below is an example of the usage of the NAB. Before calling the Metal C routine, in this case getDate, the calling program needs to calculate the NAB. This program uses the first byte after its own DSA, whose size is overallocated at 65K. The calling program stores the NAB at offset 8 in its own save area.

 
 1 TESTEXM2 CSECT                  
 2 TESTEXM2 AMODE 31               
 3 TESTEXM2 RMODE ANY              
 4 GETDATE  ALIAS C'getDate'       
 5          Print NoGen            
 6          J     @OFFSET          
 7          DC    HL2'08'          
 8          DC    CL8'TESTEXM2'    
 
12 @OFFSET  DS    0H                                                     
13          STM   R14,R12,12(R13)    Save Registers                      
14          LR    R12,R15                                                
15          Using TESTEXM2,R12                                           
17          LGFI  R3,DSALen          Length of program's DSA             
18          AFI   R3,65536           Storage for Metal C Routines        
19          STORAGE OBTAIN,LENGTH=(R3),LOC=31                            
34          St    R0,0(,R1)          Save DSA Length                     
35          AHI   R1,4                                                   
36          St    R13,4(,R1)         Store Previous DSA Address   
        
37          LR    R13,R1             Point to our DSA                    
38          Using DSA,R13            Establish Addressability            
39          LR    R2,R13             Calculate NAB                       
40          AFI   R2,DSALen          Move past end of this program's DSA 
41          ST    R2,SavNext         Addr of Next Available Byte (NAB)

In the prolog code for the called route, getDate, the Metal C code loads the NAB from offset 8 from R13, the caller's DSA. The caller's DSA (R13) is saved at offset 4 in the called routine's DSA, and restored upon return from the routine. If a called routine, in turn, calls another Metal C routine, then the same convention of NAB calculation and retrieval is performed by the calling and called routine.

 
 * int getDate(struct dateTime *_dateTime)                        
         ENTRY @@CCN@172                                         
@@CCN@172 AMODE 31                                               
         DC    XL8'00C300C300D50100'   Function Entry Point Marke
         DC    A(@@FPB@2-*+8)          Signed offset to FPB      
         DC    XL4'00000000'           Reserved                  
@@CCN@172 DS   0F                                                
         STM   14,11,12(13)                                      
         LR    11,0 
                                                          
         LR    15,13                                             
         L     13,8(,13)                                         
         ST    15,4(,13)                                         
@@BGN@2  DS    0H                                                
         LA    10,176                                            
         ALR   10,13                                             
         ST    10,#NAB_2-@@AUTO@2(,13)                           
         LR    0,11                                              
         USING @@AUTO@2,13

References

z/OS Metal C Programming Guide and Reference
z/OS XL C/C++ Language Reference