Data Collector Programs

This section describes how data collector programs work and explains what information is required in a data collector program. A data collector works very closely with Strobe. Each time it samples the target job step, Strobe attempts to identify the name, load address, and size of the module in which execution or wait is occurring. Strobe then passes control to the appropriate data collector programs. If more than one task is executing in a given sample, Strobe gives control to a data collector for each active task.

Functions of Data Collector Programs

You can use data collector programs to augment the data provided in the Strobe Performance Profile. This section lists some of those uses.

Identifying Transactions

In transaction-driven subsystems, a data collector program can identify the transaction in control. The data collector program supplies transaction names to Strobe, which uses them to produce the Transaction Usage Summary and Transaction Usage by Control Section reports of the Performance Profile.

When Strobe cannot assign activity to a single transaction, a data collector program can generate one or more pseudo-transaction names. Pseudo-transaction names can, for example, denote specific overhead functions.

Identifying Active Load Modules

As Strobe samples, it attempts to identify the module that is currently executing or waiting. That module may be the one in which program execution began; it may be an operating system support module (such as an SVC module or an I/O module); or it may be a module that has been dynamically loaded during program execution.

If your application program has not loaded modules with the system contents management facilities employed by the link, load, attach, or xctl macro instructions, then Strobe cannot identify the module in which activity takes place. You can supply a data collector program to report on modules that Strobe cannot identify so the Performance Profile provides more complete information about the application.

Supplementing Strobe Options

You can write data collector programs to supplement information gathered by Strobe options. Strobe calls your data collector program after it calls any options.

For example, Strobe identifies a transaction, which it may label as a true user transaction or as system overhead. A beginning period (.) identifies the name of an overhead transaction. Your data collector program can change the pointer to the transaction name to identify a subtransaction or to define overhead functions further.

When Strobe cannot identity the module in which execution or wait is occurring, your data collector program may be able to do so.

For each transaction name, Strobe produces a detail line in the Transaction Usage Summary and a report subsection in the Transaction Usage by Control Section report of the Performance Profile.

Other Data Collector Functions

For subsystems that are not transaction-driven, you can write a data collector program that groups functionally related activities under a name that you specify. The data collector program supplies this name to Strobe. Strobe reports activity associated with this name in pseudo-control sections. The name appears in a detail line in the Program Section Usage Summary report and as a header of a subreport in the Program Usage by Procedure report.

The Structure of Data Collector Programs

Important

The structure of user-written data collectors has changed in  21.01 to support measuring 64-bit programs. User-written data collectors will need to be recompiled to be used with  21.01. Further coding changes may be required to exploit 64-bit measurement.

To write a data collector that Strobe can use requires you to follow certain conventions. A data collector program must begin with the following structure:

STRBxxxx    CSECT
            USING    *,15
BASE        B        BEGINCollector identifier (REQUIRED)
            DC       AL1(FILL-*-1)          Length of identifier
            DC       CL17'STROBE COLLECTOR' Eyecatcher
            DC       CL1' '
            DC       CL8'STRBxxxx'Program name
DC     CL1' '
GENID    DC       CL4'V-00'              Version (V-00 for 21.01+)
IDSIZE      EQU      *-BASE
FILL        DC       XL(64-IDSIZE)'00'
ADDRLIST    DS       0F
            DC       A(0)                     Reserved
            DC       A(0)                     Reserved
DCCSCPA     DC       A(0)                     Reserved
DCCPCST     DC       A(0)                     Pseudo-csect table
DCCSW       DC       AL1(0)                   Reserved
DCCLIST     DC       AL3(PROGRAMS)            List of programs supported
BEGIN       DS       0H

Parameter List

You need to supply Strobe with some information so it can combine what your data collector provides with the rest of the measurement data in the Performance Profile. The parameter list contains the following fields:

DCCPCST

DCCPCST can contain the address of a table supplying the pseudo-control section names that Strobe uses to condense its reports. Strobe reports activity in functionally related system control program modules (whose names share a common three-character prefix) as occurring in a single pseudo-control section. The name of the control section begins with “.” and suggests its function. For example, activity reported in the pseudo-control section .COBLIB comprises activity measured in modules whose names share the common prefix ILB, which identifies some COBOL library modules.

To condense the reports for your modules, create a table that holds the definitions for the pseudo-control sections and give the address of the table in the DCCPCST parameter of the data collector program. Code each entry in the table by specifying a pseudo-control section name and its identifying real module prefix.

DC CL7'AAAAAAA'
DC CL3'ABC'

This code will cause Strobe to report in the Program Section Usage Summary report and the Program Usage by Procedure report the processing of all modules beginning with the characters ABC under the module .SYSTEM and the section .AAAAAAA.

You can specify more than one prefix for a pseudo-control section. For example, you can also specify:

DC CL7'AAAAAAA'
DC CL3'DEF'

You can supply as many as 25 pseudo-control section entries. Terminate the list with X'FF'.

DCCLIST

DCCLIST contains the address of a list specifying the names of programs supported by the data collector. This list ensures that a data collector program is invoked only for the application program or online subsystem for which it is written. Strobe scans the list, matching each entry against the name of the subject program and the names contained in the MAPPROGRAM parameter list supplied by the user when the user submits a measurement request. (Refer to the Using-Strobe-to-measure-online-applications-and-batch-programs.) Strobe calls the data collector only when it finds a match. If you explicitly name your data collector program when you submit a measurement request, Strobe does not refer to this list. (See Invoking a Data Collector.)

You can supply any number of programs. Terminate the list with X'80'. To allow Strobe to call your data collector program each time it measures, code a field of asterisks (CL8'********') in the list.

Register Usage

A data collector program uses the standard IBM linkage conventions. When Strobe calls the data collector, the following registers are set:

R1

address of the data collector communications area (described below)

R13

address of a save area provided by Strobe

R14

return address of Strobe

R15

base address for the data collector program.

The data collector returns control to Strobe through register 14. All registers must be saved and restored.

Data Collector Communications Area

The data collector communications area provides for communication between Strobe and the data collector program. The format is as follows:

DCILCOMM  DSECT        data collector communications area
DCILCPSG  DS     0AD   current user task PSW instruction address
          DS     A     | HI half of DCILCPSG
DCILCPSW  DS     A     | LO half of DCILCPSG
DCILCTCB  DS     F     address of the current user TCB
DCILCBAG  DS     0AD   load address of the module in control
          DS     A     | HI half of DCILCBAG
DCILCBAS  DS     A     | LO half of DCILCBAG
DCILCSIG  DS     0FD   size of the module in control
          DS     F     | HI half of DCILCSIG
DCILCSIZ  DS     F     | LO half of DCILCSIG
DCILCNMA  DS     F     address of the name of module in control
DCILCTRA  DS     F     address of the name of transaction in control
DCILCOLA  DS     F     data collector work address
DCILCIDA  DS     F     address of the data collector ID field
DCILCFLG  DS     F     X CALL FLAG
DCILCIDNT EQU    x’40’ called at CPU identify time
DCILCICST EQU    x’80’ called at CPU sample time

When Strobe calls a data collector, Strobe provides the following information in the data collector communications area.

DCILCPSG/DCILCPSW

DCILCPSG contains the 64-bit instruction address from the program status word (PSW) for the task that is active at the time Strobe takes the sample. DCILCPSW contains the 32-bit half of the instruction address. This field is provided for information only. Strobe does not act on modifications to it.

DCILCTCB

DCILCTCB contains the address of the task control block (TCB) of the user task in control at the time the sample is taken. This field is provided for information only. Strobe does not act on modifications to it.

DCILCBAG/DCILCBAS

When Strobe has identified the module that is executing or waiting, DCILCBAG contains the 64-bit load address of the module. DCILCBAS contains the 32-bit half of the load address.

DCILCSIG/DCILCSIZ

When Strobe has identified the module that is executing or waiting, DCILCSIG contains the 64-bit size of the module in bytes. DCILCSIZ contains the 32-bit half of the size.

DCILCNMA

When Strobe has identified the module that is executing or waiting, DCILCNMA provides the address of an eight-byte field containing the name of the module in control. The field must be left-justified and padded with blanks. Strobe sets DCILCNMA to null (binary zero) if neither Strobe nor any other data collectors have identified the module in control.

DCILCTRA

When a data collector has identified a transaction, DCILCTRA provides the address of an eight-byte field containing the name of the transaction. The field must be left-justified and padded with blanks.

DCILCOLA

DCILCOLA is a four-byte field that is available to your data collector program for any purpose you choose. For example, you can use it to anchor storage acquired via GETMAIN.

DCILCIDA

DCILCIDA contains the address of an eight-byte field supplying information about measured programs or subsystems that is printed in the Measurement Parameters column under the field labeled SUBSYSTEM in the Measurement Session Data report. Strobe initializes this field to null (binary zero) on each invocation of the data collector.

DCILCFLG

DCILCFLG contains a one-byte flag field that Strobe sets to either x'40' or x'80' depending on the time of the call. DCILCFLG will always be x'40', identify time call, if the parmlib parameter UDCCDSS is left at its default value of UDCCDSS=NO. This will allow legacy user data collectors to run with no modifications. If the PARMLIB parameter UDCCDSS=YES is specified, you must check the value of DCILCFLG to determine the time of the call.

Important

When a user data collector is called during sample time x'80' the entire address space has been stopped. Any attempt to use resources that require locks or enqueues may cause a deadly embrace to occur and the address space can hang. We strongly recommend that you leave UDCCDSS at its default value of NO.

In addition, running a user data collector sample time may have unintended consequences on other functions provided by , so exercise caution when updating the name of the module or transaction in control:

  • ’s attribution processing may be adversely affected if a user data collector renames a system module already identified by ’s own data collectors. For example, if a user changes the name of the CICS module, DFHSIP, CICS attribution cannot proceed. We recommend that user data collectors do not rename system or subsystem (for example, Db2 or CICS) modules already identified by . User data collectors should identify only those modules that  cannot identify.
  • The CICS Transaction Profile reports may be affected. CICS TXP has never recognized transaction names supplied in a user data collector. However, a user data collector run at sample time could skew the TXP reports if the user attempts to profile either the original CICS-supplied transaction name or the user-supplied name. The CICS Transaction Profile reports for the transaction will be incomplete.

Supplementing Measurement Data

Your data collector program can supplement data that Strobe collects. All changes caused by the data collector must be indicated in the data collector communications area. Your data collector should not change the PSW instruction address or the TCB address. The data collector program can change the following:

  • Address of the name of a transaction in control at the time of the sample
  • Address of the name of a module waiting or executing
  • Load address of the module
  • Reported size of the module
  • Address in the information field.

Identifying Active Load Modules

A data collector can examine the DCILCNMA field to determine if Strobe has identified the module that is executing or waiting. (The DCILCBAS and DCILCSIZ fields are not reliable indicators; they may contain zeros when Strobe identifies activity in an SVC module.) When a data collector program identifies the module, it places the address of the module name in DCILCNMA. The data collector also places the module base in DCILCBAS, and the module size in DCILCSIZ.

Strobe verifies that the PSW instruction address supplied in the data collector communications area fits within the size and base supplied by the data collector program. If the address does not fit, Strobe does not record the module data that the data collector supplies.

If the identified module is also one defined as a pseudo-control section (see DCCPCST), a data collector can force Strobe to accept the module by:

  • Setting the value of DCILCBAS to zero
  • Setting the size value to X'7FFFFFFF'.

If neither Strobe nor any of the active data collector programs can identify the active load module, Strobe attributes execution or wait to a pseudo-control section corresponding to the location of the current PSW (for example, to .PRIVATE if the PSW is within the private area of the address space).

Identifying Transactions

In transaction-driven subsystems, Strobe may not be able to identify the transaction in control. If a data collector program can identify the transaction, it places the address of the name of the transaction in the DCILCTRA field. The name must be in an eight-byte field, left-justified and padded with blanks.

Your data collector program can also attribute activity to pseudo-transactions that may identify overhead functions. If a data collector program cannot otherwise identify a transaction, it should supply a pseudo-transaction name so that Strobe can account for all activity in the transaction reports.

When a data collector program identifies a transaction, Strobe attributes subsequent CPU time to the transaction until the data collector either identifies another transaction or supplies a null transaction identifier (binary zeros) in the field addressed by DCILCTRA.

Operational Considerations

Besides the program structure and reporting requirements you must meet for a data collector, several operation factors should be taken into account and are described in this section.

Strobe a data collector program whenever it finds within an authorized linklist library a program with the name STRBxxxx, where xxxx is the unique four-character prefix of the name of the target program. To allow Strobe to automatically load your data collector program for the appropriate programs, link-edit your data collector with the associated name. If the data collector supports more than one program, supply a STRBxxxx alias for each program whose name begins with a unique four-character prefix. For example:

  • To link-edit a data collector that Strobe automatically invokes whenever it measures programs MYPROG, MYPROG1, and MYPR1234, code the NAME statement for the link-editor input:
    NAME STRBMYPR

  • To link-edit a data collector that Strobe automatically invokes whenever it measures programs MYPROG, OURPROG, and YOURPROG, code:

    ALIAS STRBOURP
    ALIAS STRBYOUR
    NAME STRBMYPR

To make your data collector program available to any job step that you want to measure, link-edit your data collector program into an authorized linklist library. 

Invoking a Data Collector

If you have used the naming conventions described above, Strobe automatically invokes your data collector when it encounters a program with the appropriate four-character prefix, provided that it meets the verification requirements described for the DCCLIST parameter.

Alternatively, if you use the Strobe command language to submit your measurement request, you can specify the name of your data collector with the DCC operand with the ADD or CHANGE commands. If you use Strobe/ISPF to submit the measurement request, you can specify the name of your data collector on the Strobe - Data Collectors panel.

When you explicitly specify a data collector name, Strobe loads and calls the data collector program, checking only for the data collector’s identifying constant STROBE COLLECTOR and version. (See The Structure of Data Collector Programs.) When you specify more than one data collector, Strobe executes them in the order you have specified.

AMODE/RMODE Considerations

When Strobe measures programs, it executes and calls a data collector program in 31-bit addressing mode (AMODE 31), supervisor state, and in the protect key of the target program. If your data collector cannot operate in AMODE 31, you can change it to operate in 24-bit mode (AMODE 24). The program must, however, return control to Strobe in 31-bit mode.

The following code is suggested to change from 31-bit mode to 24-bit mode:

L    R1,16              load CVT address
TM   116(R1),X'80'      is this XA
BZ   *+10               no
LA   R1,*+6             get next instruction address
BSM  0,R1               go to 24-bit mode
This code is suggested to change from 24-bit mode to 31-bit mode:
L    R1,16 load CVT address
TM   116(R1),X'80'      is this XA
BZ   *+14               no
LA   R1,*+10            get next instruction address
O    R1,=XL4'80000000'  set bit for 31-bit mode
BSM  0,R1               go to 31-bit mode

Link-edit your data collector in RMODE 24.

Programming Considerations

Because Strobe calls the data collector each time it takes a measurement sample, code it to perform efficiently.

Your data collector program must be re-entrant.

Your data collector program must determine if the target program is one that it can measure. If not, it must return control immediately to Strobe.

Strobe calls user-written data collectors in user key supervisor state, which is the key of the measured address space.

To obtain storage, specify the storage protection key on the GETMAIN or STORAGE OBTAIN macro. For example:

IPK     R2               determine our key
LA      R2,STORAGE_SIZE  indicate storage size
STORAGE OBTAIN,ADDR=(8),SIZE=(0),KEY=(2),LOC=(ANY,ANY),COND=YES
LTR     R15,R15          work ok?
BNZ     ERROR            bif no

Because the Supervisor State allows privileged instructions and authorized services to be issued from the user-written data collector, review all customer-written data collectors to ensure that there are no integrity exposures.

To facilitate the process, we have provided a 256-byte work area. When Strobe calls the user-written program, Register 13 points to a 144-byte save area. Following the save area, there is a 256-byte work area in the correct key. The work area is not persistent; its contents will not be preserved across calls to the data collector. 


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*