The following describes information that a programmer needs to
know for developing the Data Extractor Module Resolution.
- The exit is called once to initialize itself at the start of the
sample session and once again at the end of sampling to perform cleanup
and termination.
- For each sampling interval during the sample session, the Application Performance Analyzer Sampling
Engine analyzes the Job Step TCB and all subtasks. Part of this analysis
involves resolving the PSW addresses. Therefore, the Data Extractor
Module Resolution should expect to be called one or more times per
sample interval and once for each unresolved address.
- The Application Performance Analyzer Sampling Engine executes as an SRB. Since the
Data Extractor Module Resolution is called by the Sampling Engine,
it must also comply with all the rules of an SRB as described in z/OS MVS Programming: Authorized Assembler Services
Guide; Chapter: Implications of Running in SRB Mode.
- It must not establish an FRR. Recovery is provided by the Sampling
Engine.
- A user can request that a Job Step be sampled from start of step
to end of step. Therefore, it is very likely that the exit is called
early in the Job Step’s creation. Under this condition the sampled
application does not have sufficient time to initialize itself. Therefore,
the exit might not find the environment that it expects. This is especially
true during the Initialization (First) function call to the exit.
If the exit determines that the sampled application is not ready,
the exit should remember this fact and not attempt to initialize itself
at this time. Instead, it should reattempt initialization during Module
Resolution function calls.
The exit can also be called late in
the Job Step termination and find that the sampled application already
terminated. In this case, the exit might find it impossible to resolve
an address or even perform its termination function.
For both
early and late calls, the exit can expect segment- or page-translation
exceptions if it attempts to reference memory that has not been obtained
yet. The exit should validate such addresses by checking for zeros
and using the TPROT instruction to verify the address.
- The exit must be reentrant and able to handle concurrent calls.
It is very possible for the exit to be called by the Sampling Engine
SRB, the DB2 intercept and the IMS intercept all at the same time.
- If the exit requires its own memory, it should allocate this memory
from subpool 235. Storage in this subpool is owned by the address
space and is not freed at end of step. The exit can therefore be guaranteed
that the memory persists until its Termination (Last) function call.
The exit must free this memory to prevent memory leaks.
- Economize on path length. The exit could be called multiple times
per second and a long path length could adversely affect the overall
performance of the Sampling Engine. Avoid calling MVS system services.
Try to restrict these calls to Initialization or Termination functions
as they are only called once per sample session.
- Data Extractor Module Resolution is
not activated by default. It must be activated by specifying DEXMR=YES
in the CONFIG SAMPLE section of the configuration file found in the
member CAZCNFG0 in hlq.SCAZSAMP.
- Data Extractor Module Resolution is a global exit. When it is
properly activated, it is called during all sampling sessions. If
this is undesirable, the programmer can add code to the Initialization
function call to deactivate itself for the remainder of the sample
session. This must be done on a sample session by sample session basis.
- The exit is passed a pointer to a 4096-byte context area. This
area is for the exclusive use of the exit. The Sampling Engine initializes
this area to nulls once, prior to the First call to the exit. This
exit can use this area for any purpose, which can include:
- A portion for the exit’s dynamic storage area.
- A portion as a context area to keep information it might need
across function calls.
- A portion can optionally be used to communicate information back
to the Sampling Engine e.g. USS pathname data.