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. When using this compiler option, a user
field with the size of a pointer is reserved on the stack. This user
field can be utilized by your prolog or epilog code. 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.