Data Extractor Module Resolution Program Design Considerations

The following describes information that a programmer needs to know for developing the Data Extractor Module Resolution.
  1. 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.
  2. 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.
  3. 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.
  4. It must not establish an FRR. Recovery is provided by the Sampling Engine.
  5. 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.

  6. 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.
  7. 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.
  8. 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.
  9. 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.
  10. 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.
  11. 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.
Parent topic: Application Performance Analyzer Data Extractor Module Resolution User Exit