Supplying your own prolog and epilog code

If you need the prolog and epilog code to provide additional functionality, you can use #pragma directives to instruct the compiler to use your own HLASM prolog and epilog code. Figure 1 provides an example.

Figure 1. Specification of your own prolog and epilog code for a function

   #pragma prolog(foo,"MYPROLOG")
   #pragma epilog(foo,"MYEPILOG")
   int foo() {
     return 0;
   }

To apply the same prolog and epilog code to all your functions in the C source file, use the PROLOG and EPILOG compiler options. When you use the PROLOG and EPILOG compiler options, by default, your prolog and epilog code is applied only to the functions that have external linkage. To apply your prolog and epilog code to all functions defined in the compilation unit, use the new "all" suboption provided by z/OS® V1R11 XL C compiler. For detailed information, see PROLOG and EPILOG options in z/OS XL C/C++ User's Guide.

The string you supplied to the PROLOG/EPILOG options or the #pragma directives must contain valid HLASM statements. The compiler does not validate the content of the string but it does take care of some formatting for you:

If your string contains only a macro name, as shown in Figure 1, you do not need to supply leading blanks.
If the length of your HLASM statement exceeds 71 characters, you do not need to break it into multiple lines. The compiler will handle that for you.

Your prolog code needs to ensure that:

The primary functions of the prolog code have been performed.
Extra DSA space is acquired, in the event that the NAB is needed for the referenced functions.
Upon exit of your prolog code:
- GPR 13 points at the DSA for this function.
- GPR 1 points at the parameter list supplied by the calling function.

Your epilog code needs to ensure that:

The primary functions of the epilog code have been performed.
The content of GPR 15, on entry to your epilog code, is preserved.
If a 64-bit integer value is returned from an AMODE 31 program, the low half of the return value contained in GPR 0 is preserved.

Your prolog and epilog code does not need to perform the following functions:

Preserve the calling function’s floating-point registers.
Preserve the calling function's vector registers.
Preserve the high-halves of 64-bit general purpose registers in AMODE 31 functions.
Preserve the registers used by the compiler generated code.
Set up the NAB for the called functions.

User reserved DSA space

User reserved DSA space can be enabled by using the compiler option DSAUSER(value). If DSAUSER is specified without suboption, a user field with the size of a pointer is reserved on the stack. The user field is a 4-byte field for AMODE 31 and an 8-byte field for AMODE 64. This user field can be utilized by your prolog or epilog code.

If a value suboption is specified with DSAUSER, a user field with the size of value 32-bit words is allocated. Specifying DSAUSER with a suboption requires ARCH(6). The value must be an integer in the range of 0 to 50.

The user field can be located by the HLASM global set symbol &CCN_DSAUSER, which provides the offset to the user field. The compiler allocates the field on the stack only, without initializing it.

The following example shows how &CCN_DSAUSER is set by the compiler:

&CCN_DSAUSER SETC '#USER_2-@@AUTO@2'

The following example shows how &CCN_DSAUSER can be used in your prolog code:

STG 0,&CCN_DSAUSER.(,13)

For detailed information about the DSAUSER compiler option, see the topic about DSAUSER and NODSAUSER in z/OS XL C/C++ User's Guide.