Considering that XPLINK is about creating trivial functions, it's funny you expect IBM to provide a non-trivial example. Here are some of my observations after a quick look at some (not all) of the documentation. Keep in mind, I haven't used XPLINK.
1. Limit your expectations. IBM limits the functionality to reduce overhead. 2. You keep referring to "return code" but this is a C where you could return a pointer. It's not obvious when it's treated at INT32 versus INT64. I expect this to be defined by C function prototype but maybe amode or EDCX versus CEQL changes how it's handled. 3. While you're not limited to 3 arguments, the first 3 are available in regs 1-3. This is IBM's way of encouraging you keep this trivial. I believe I saw somewhere that you can get to additional arguments. 4. You say FOO(17) will set R1 to 17 but you forget the function prototype determines whether you get the value or a pointer. 5. Preserved registers are guaranteed to be restored by IBM but I'm guessing is part of the DSA allocation. I'm guessing that IBM only preserves a few register to encourage you keep this trivial. You could look at the expansion of the prolog and epilog to see what IBM is doing in the macro's. Realize that in the XPLINK overview, it tells you that you are responsible for preserving registers but I'm guessing only non-preserved registers and R14 to R3 surely don't need to be saved but that's a guess. 6. The documentation tells you the DSA register. The doc should tell you registers upon exit which may also be in the EPLG macro. 7. You say "defining variables in DSA" which is confusing. In EPLG, you specify extra DSA to be available as working storage This should be well documented in the DSA doc and macro. If this is in reference to C variables, this doesn't make sense. 8. You ask where you save/restore regs. IBM expects you to use preserved registers because they want you to write trivial XPLINK programs. You can increase the DSA size in EPLG that includes a save area. If you need basic abend handling, then maybe BAKR/PR might be an option but remember set R3 prior to the BAKR. 9. You asked about arguments being passed in R1 to R3 which is under your control through the function prototype. I can't remember how C handles the last argument but I vaguely recall it doesn't use use the bit. I think it had a count of args passed but won't swear to it. 10. When you say automatic variables, it's not clear what variables you expect to access. I'm guessing that you are referring to variables created in the caller function that are limited to the caller. Much like your assembler workarea created by EPLG, only the caller will know variables and offsets. Or maybe you're talking about global variables? In any case, this seems to be extending past the scope of trivial. 11. You ask about R3 return code. It appears that it will be an INT32 or INT64 (possibly pointer) that is defined in your function call prototype. The pointer can point to a struct or something else as needed.
