Tom Marchant wrote:
On Tue, 3 Aug 2010 12:02:29 -0600, Steve Comstock wrote:
Peter Relson wrote:
As to your point
about
allocating using space based on a format shown in a book, that is not
using best programming practices when a symbol is provided in a macro.
I disagree. I use the docs as reference, trusting they reflect
the macros (which can be difficult to read in some cases, eh?)
But the example in the book shows:
GETMAIN RU,LV=SAVF5SA_LEN Get my reentrant savearea
That will allocate a 216 byte save area.
Umm, how can I tell from the example that this will be
a 216-byte save area? There are no comments in the code
nor discussion around the example to inform the reader
of the generated size; my essential point is the whole
section is not clear enough for the reader to properly
code save area linkages.
I will be re-writing the section in my course on save
area linkages so students who subsequently visit the
doc can relate to what's there. Right now, it just
doesn't tell the story clearly, in my opinion.
On pages 21, 23, and 241 you refer to a F6SA; but you never define
that; how is it different from a F4SA?
It has no similarity at all. The string F6SA (as with any of the FxSA
strings)
identifies how the caller's registers were saved. As shown, both F1SA and
F6SA indicate that registers were saved on the linkage stack.
How is that? I mean, where in the doc is that connection made? Oh,
I see, on p. 21:
A primary mode program that uses the linkage stack must:
o Issue a BAKR instruction which will save the caller's ARs and
64-bit GPRs on the linkage stack.
...
"Set the second word of the save area to the character string
'F1SA' if obtaining a 72-byte save area or 'F6SA' if obtaining
a 144-byte or larger save area"
The fact
that
you have allocated 144 bytes of save area in addition to saving registers
on the linkage stack does not state how a callee may use those 144 bytes.
The publication is correct.
Well, perhaps, but unclear. For example, on page 8:
"In the case where the program saves its registers in a 72-byte
save area (mapped by the SAVER DSECT in macro IHASAVER), the
second word contains the address of the previous save area.
Because that previous save area was on a word or doubleword
boundary, bit 31 of the address (and thus bit 31 of the
second word) will be 0. In the case where another save area
format was used, bit 31 of the second word will contain 1
due to the 4-character string that is to be placed there."
So, if I'm parsing this correctly, you're saying if the second
word of a save area ends in b'0', the save area is 72 bytes in
length, and in all other cases the second word of any save area
will be b'1'.
Not exactly. If the second word ends in b'0', the program that
created that save area saved its caller's registers in 72-byte
"standard" format. However, it might call other programs that
require a 144-byte save area, in which case the save area
must be 144 bytes to accommodate the requirements of the
programs that it calls.
This is presumably because you are expecting strings like F4SA,
F5SA, and so on, which end in c'A' -> b'1100 0001' in the second
word. Is that correct?
But what about the quote above from page 21:
"Set the second word of the save area to the character string
'F1SA' if obtaining a 72-byte save area or 'F6SA' if obtaining
a 144-byte or larger save area"
Isn't this a contradiction? A 72 byte save area with bit 31
of the second word being b'1'?
No. Read it again. Here is an important part, from the beginning of the
same paragraph you quoted from page 8:
<quote>
In all save areas, the second word (the word at offset 4)
of each save area provides an indication of how the
program that created the save area saved the caller's
registers. It does not describe the contents of this save
area.
</quote>
"The second word of the save area ... does not describe the
contents of this save area"
I'm afraid this section is full of carelessness like that. Most
uncharacteristic of Peter.
Please be specific. The section you show was not careless in any way.
It was fully intentional. The fact that F6SA says that the area is 144
bytes
(or larger) does not characterize its format.
So the second word tells me the size of the save area provided
by the caller?
No. It tells how the called program used the save area provided
by the caller. You can not deduce anything about the size of
the caller's save area from that. What you can do is to determine
where to find the address of the previous save area and find the
caller's registers in that save area.
Well I don't think _that's_ communicated in the doc at all.
Let's see ...
From the doc you quote:
"The second word of the save area ... does not describe the
contents of this save area"
Then you write:
"It tells how the called program used the save area provided
by the caller."
... so it _does_ imply _something_ about the contents.
Then ...
"What you can do is to determine where to find the address of
the previous save area and find the caller's registers in
that save area."
So there must be some kind of mapping that tells me this,
some logic I can incorporate in my program, right?
So, revising my earlier table, let's see ...
Content of 2nd word means address of previous save area is at
ends in b'0' savearea+4
'F1SA' savearea+4 (?); no, that can't be right!
since this has 'F1SA'
'F2SA' .. not documented ..
'F3SA' .. not documented ..
'F4SA' savearea+128
'F5SA' savearea+128
'F6SA' ?
'F7SA' savearea+128
'F8SA' savearea+128
I'm not saying the doc is wrong, I'm saying I can't understand
what it's trying to convey. I can't use it to consistently
explain the rationale behind the various save area formats.
It's probably just my feeble brain, but I need things spelled
out more simply still. Sorry.
--
Kind regards,
-Steve Comstock
The Trainer's Friend, Inc.
303-393-8716
http://www.trainersfriend.com
* To get a good Return on your Investment, first make an investment!
+ Training your people is an excellent investment
----------------------------------------------------------------------
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to [email protected] with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html
