On Tue, 30 May 2017 08:39:25 -0500, John McKown wrote: >As best as I can tell, there are 5 different Save Area formats. There is >the historic 72 byte format. This saves bits 32..63 of GPR 14-12. There is >an F4SA which is 144 bytes and contains bits 0..63 of GPRs 14-12. There is >a F5SA which holds bits 0..63 of the GPRs 14-12 and bits 0..31 of GPRs >0-15. There is F7SA which holds bits 0..63 of GPRs 14-12 and ARs 14-12 plus >"alet of previous save area" (isn't this just AR13 at entry?). And finally, >there is F8SA which is bits 0..63 of GPRs 14-12, ARs 14-12, "alet of >previous savearea", bits 32..63 of GPRs 0-15. > >ref: >https://www.ibm.com/support/knowledgecenter/SSLTBW_2.2.0/com.ibm.zos.v2r2.iead200/iead200571.htm > >First question: Why save the "high word" of regs 0-15 in addition to the >entire double word of regs 14-12 (all but GPR15)?
You don't. Your question applies to F5SA and F8SA. Those formats are used when you need to save and restore the 64-bit registers and you are not able to require a 144-byte save area be provided by your callers. In that case, you save the low halves of your caller's registers in the caller-provided 72-byte save area and allocate either a 216-byte save area or a 288-byte save area for programs that you call. At the end of your save area is space for you to save the high halves of your caller's registers. You mark your save area at offset 4 with "F5SA" (or "F8SA"). The difference between the F5SA and the F8SA format is the size of the save area that is allocated and the offset of the high halves of your caller's registers. When you allocate a 216-byte save area and mark it with "F5SA", there are 144 bytes available for programs that you call. Those programs can then use F4SA format or standard 72-byte format to save your registers. When you allocate a 288-byte save area and mark it with "F8SA", there are 216 bytes available for your callers, which can then use F7SA, F4SA or standard 72-byte format. The programs that you call can also use F5SA or F8SA format to save your registers. In that case, they would store the low halves in your save area, just as you did. This wouldn't be something that you planned, but would be as a result of you calling a program that, like your program, was not able to control its callers and could not assume that more than a 72-byte save area was available. When you use F5SA or F8SA format to save your caller's registers, the forward pointer to your save area is at offset 8 of your caller's save area. >Second question: Why say "alet of previous savearea" rather than AR13? Is >there a case where this is _not_ in AR13 at entry? If so, how would I know? Yes, it is the same thing. >Philosophy question: If I am writing a non-LE enabled HLASM subroutine, >should I check the "save area type" to ensure that my routine is properly >callable from any non-XPLINK routine? You cannot use the contents of offset 4 of the save area in R13 at the time you are called to determine the available size of the save area provided. That value does not, in general, say anything about the save area in which it is contained. Rather, it documents the way that the program that allocated the save area saved its caller's registers in the save area that was passed to it by the caller. F5SA and F8SA are different in that the program that allocates the save area also stored the high halves of its caller's registers in its own save area. >I know that the standard says that it >is the _caller's_ responsibility to do this. But I'm paranoid. And I don't >way to ASSuME that the caller is paying attention and by so doing possibly >introduce a memory overlay in the caller. If you are not able to specify that your program requires (for example) a 144-byte save area so that you can store your caller's registers in F4SA format, then you can use F5SA or F8SA. You would use F8SA if you were going to call AR-mode programs that need to save the access registers as well as the 64-bit registers in F7SA format. Otherwise, you would use F5SA and the programs that you call could use F4SA to save your registers. >Also, if I get a "bad" type of >savearea, should I "do something", such as using the linkage stack, or >should I abend or maybe return a "failed" return code? No, you shouldn't do that. Every program has specifications that must be met by the calling program. We don't usually give much thought to the normal requirement that R13 contain the address of a 72-byte save area, but it is still a requirement and if it is not met, bad things can happen. And as an aside, the requirements for the save area that a calling program provides are the minimum requirements. There is no harm done by providing a larger save area. If your program calls a program that uses the Access Registers, you will want to provide a 216-byte save area for it. That program will save the 64-bit registers and the access registers in the save area that you provide. It will allocate a save area for any programs that it calls and mark that save area with F7SA. A program does not touch the word at offset 4 of the save area that was passed to it. This is completely in keeping with the way a standard 72-byte save area is used. In that case, offset 4 is the address of the previous save area and it is required when the owner of the save area (the program that allocated it) returns to its caller. If, upon return from the AR-mode program, your program calls another program that is a 31-bit program that only knows about 72-byte save areas, that program will simply use the first 72 bytes of your save area. Offset 8 of your save area will contain the address of the save area that the called program allocates. Offset 4 of the save area allocated by the called program contains the address of your save area. This address is used when the called program returns to you. Likewise, your program can call a program that requires a 144-byte save area that will be used in F4SA format. By the way, when the system passes control to your program, such as by ATTACH, register 13 points to a 144-byte save area. I am indebted to Peter Relson for this information. He and I had an email exchange a few years ago that led to him rewriting Chapter 2 of the Assembler Services guide for the Release 12 edition of the manual. I have an interest in people understanding how to use these save area types properly because, as an Abend-AID developer, I need to be able to follow save areas in order to be able to determine the calling sequence. -- Tom Marchant Abend-AID development Compuware Corporation
