There is always a tradeoff in documentation among conflicting goals.
Ease of maintenance. This requires putting technical details in a single
place.
Ease of use. This requires reducing the need to refer to other manuals for
technical details.
Accuracy. This is tied into ease of maintenance.
Legibility. It may be difficult to construct text that is both accurate and
readable.
Cost; a good SME or technical writer is expensive
Currency. Good documentation takes time, which may be contrained.
I believe that the move away from DCF-based tools has exacerbated the problem.
I vaguely recall a table showing storage attributes associated with various
types of fetch, including subpool, key, fetch protect and page protect.
--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3
________________________________________
From: IBM Mainframe Discussion List [[email protected]] on behalf of
Barry Lichtenstein [[email protected]]
Sent: Friday, August 27, 2021 1:11 PM
To: [email protected]
Subject: Re: RENT binder option
The binder and linkage editor manuals have attempted to describe the load-time
behaviors of modules according to the link-time parameters. (Similarly for the
binder FETCHOPT). This is somewhat unfortunate, as while it is reasonable to
expect some description of the options in those manuals, the behaviors are
going to depend on the system on which the module is being executed. The
binder really is just merely setting the bits in the directory.
That said the REUS options, along with AMODE and RMODE, are surprisingly
confusing, especially with their linkage editor history. The section of the
binder (Program Management: User's Guide and Reference), Appendix B ->
Migrating from the linkage editor to the binder -> Binder processing
differences from the linkage editor, does a pretty good job of explaining all
this:
https://www.ibm.com/docs/en/zos/2.4.0?topic=binder-processing-differences-from-linkage-editor
Lastly that's certainly a long-standing error in the publication! "The
refreshable attribute is negated if any input modules are not refreshable."
That's linkage editor behavior, and it is only true with the binder if
COMPAT(LKED) is specified.
In fact in the linkage editor that is the behavior of all the reusability
options (I'm looking at the MVS/ESA Linkage Editor and Loader's Guide Version 3
Release 1, SC26-4510-1, Second Edition June 1989): (** highlighting ** is mine)
In reference to the OP statement ("Someone else stated that by compiling with
the RENT compiler option, it will implicitly bind as RENT as well. My
observations tell me that this is not the case."), note that none of the
INCLUDEd modules attributes _set_ the reusability on, they only may turn it off.
Reusability Attributes
Either one of two attributes may be specified to denote the reusability of a
module. (Reusability means that the same copy of a load module can be used by
more than one task either concurrently or one at a time.) The reusability
attributes are reenterable and serially reusable; if neither is specified, the
module is not reusable and a fresh copy must be brought into virtual storage
before another task can use the module.
** The linkage editor only stores the attribute in the directory entry; it does
not check whether the module is really reenterable or serially reusable. **
A reenterable module is automatically assigned the reusable attribute. However,
a reusable module is not also defined as reenterable; it is reusable only.
Reenterable: A module with the reenterable attribute can be executed by more
than one task at a time; that is, a task may begin executing a reenterable
module before a previous task has finished executing it. This type of module
cannot be modified by itself or by any other module during execution. If a
module is to be reenterable, all the control sections within the module must be
reenterable.
**If the reenterable attribute is specified, and any load modules that are not
reenterable become a part of the input to the linkage editor, the attribute is
negated.**
Serially Reusable: A module with the serially reusable attribute can be
executed by only one task at a time; that is, a task may not begin executing a
serially reusable module before a previous task has finished executing it. This
type of module must initialize itself and/or restore any instructions or data
in the module altered during execution. If a module is to be serially reusable,
all its control sections must be either serially reusable or reenterable.
** If the serially reusable attribute is specified, and any load modules that
are neither serially reusable nor reenterable become a part of the input to the
linkage editor, the serially reusable attribute is negated. **
Refreshable Attribute:
A module with the refreshable attribute can be replaced by a new copy during
execution by a recovery management routine without changing either the sequence
or results of processing. This type of module cannot be modified by
itself or by any other module during execution. The linkage editor only stores
the attribute in the directory entry; it does not check whether the module is
refreshable. If a module is to be refreshable, all the control sections within
it must be refreshable.
** If the refreshable attribute is specified, and any load modules that are not
refreshable become a part of the input to the linkage editor, the attribute is
negated. **
Barry L
On Fri, 27 Aug 2021 11:38:05 +0000 Seymour J Metz <[email protected]> wrote:
> No, it is a text file containing one of IBM's old descriptions of the
> reusability option in *the binder* and in now way makes any claim about the
> linkage editor. Further, it is
incorrect: RENT by itself is not enough to protect a module from modification.
Contrast wit Module reusability at
<https://www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zOSV
2R4sa231393/$file/ieab100_v2r4.pdf#page=55> and REUS: Reusability options at
<https://www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zOSV2R4sa231393/$file/ieab100_v2r4.pdf#pa
ge=115> in z/OS Version 2 Release 4 MVS Program Management: User's Guide and
Reference, SA23-1393-40.
>
> There is still a minor error: "Therefore, refreshable modules must not modify
> themselves in any way" is a non sequitur.
>
>
> --
> Shmuel (Seymour J.) Metz
> http://mason.gmu.edu/~smetz3
----------------------------------------------------------------------
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to [email protected] with the message: INFO IBM-MAIN
----------------------------------------------------------------------
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to [email protected] with the message: INFO IBM-MAIN
