Adding and Changing Measurement Requests

To add a measurement request for a target program, specify an ADD command. Strobe, by default, continues sampling until the job completes. If a request is currently active for a job step, Strobe marks subsequent ADD commands directed to that job step as complete. See the section called Specifying Sampling Controls for more information about controlling how Strobe conducts a measurement session.

To change an existing request, specify a CHANGE command. If the measurement session is already active, you can specify only the GOMIN, SAMPLES, LIMIT, and RETAIN operands. Strobe applies the change to the next sample data set it creates. If the request is queued, you can change any of the operands.

Measuring an Active Job

To measure an active job, specify the job as “ADD *” so Strobe measures the job currently executing.

Specifying ADD and CHANGE Commands

To specify the default value for an operand on the ADD command, omit the operand. To specify the default value for an operand on the CHANGE command, code the keyword followed only by an equal sign (=).

The following is the complete Strobe command language syntax for the ADD and CHANGE commands. The only required operands are the statements identifying the target job and job step or program. The remaining operands are optional and are explained in subsequent sections.

Identifying the Target Job

The first operand that is specified for a command identifies the job that you want Strobe to target. You must specify this operand.

jobname|*|jobname*|rrrr  identifies the job in which the target job step or program will be executed.

• jobname  specifies the name of the job.
• *  (asterisk) specifies that the measurement request is for the currently executing job. The * keyword is valid only when Strobe is run as a step within the same job as the target program.
• jobname* (asterisk), for a queued request, specifies that Strobe should measure the next job that starts to execute and begins with the alphanumeric sequence preceding the * character. There is no limit on the number of sequences you can specify. For example, you can specify an ADD command of ADD(PR1*,PR2*). The statement will cause Strobe to measure the first two jobs that start to execute with names that begin with the characters PR1 and PR2. You cannot use the * character between two alphanumeric sequences, such as abc*job.
• rrrr  specifies the request number of an outstanding Strobe measurement request (valid in CHANGE commands only).

To add or change multiple requests, specify a comma-delimited, parenthesized list of request numbers or job names.

Identifying the Target Program

To identify the target program of a queued measurement request, specify one of the three operands that begins with the keyword PGM, STEP, or NUMBER. If you specify more than one operand, make sure the target job step satisfies all conditions.

If a specified step or program appears more than once in a job, Strobe measures only the first occurrence of the step or program. To measure a subsequent step or program, use the NUMBER operand.

PROGRAM | PGM

PROGRAM|PGM=programid(s)  specifies the name of any target program, as given in the PGM= operand of an EXEC statement. AutoStrobe users can measure multiple programs with one request, for example:

or

STEP

STEP={stepname(s)[.procstepname],...|*|*ALL} specifies the name of the target job step.

• stepname(s)  specifies the stepname that invokes the target program or procedure. You can also specify multiple stepnames to be measured.
• procstepname specifies the stepname within the procedure that executes the target program.
• * (asterisk) specifies that the measurement request is for the step currently executing. Specifying an asterisk will cause Strobe to create an Add Active measurement request. Specifying stepname, procstepname, or *ALL will cause Strobe to create an Add Queued measurement request.

• (Auto

  Strobe

   only) *ALL specifies that all steps of the job should be measured for a queued request (nested procedure steps will not be measured if they have previously executed).

The following example shows the job control statements for a job (MYJOB) that contains three procedures. The third procedure (PROC3) contains two executions of PROC2, with stepnames NEST1 and NEST2.

To measure a step that is not part of a procedure, specify only the stepname. Code:

To measure a step that is part of a procedure, specify both stepname and procstepname, separating the names by a period (.), as in  stepname.procstepname. Strobe will measure the first executable step identified by the procedure step name. To measure step P1 in the first procedure in the example above (PROC1), code:

To measure a step that is part of a nested procedure, specify the stepname of the procedure containing the nested procedure and procstepname  of the nested procedure, separating the names by a period (.), as in  stepname . procstepname. If the procedure containing the nested procedure executes an identically named stepname before the nested procedure executes, Strobe measures only the first step. In order to measure identically named steps, specify the NUMBER operand.

To measure the first execution of the second step of the nested procedure, PROC2, in the example, code:

To measure the second execution of the second step of the nested procedure, PROC2, in the example, code:

To measure a step that is currently executing, specify  STEP=* without the PROGRAM or NUMBER operands.

To measure all steps in a job, code:

To measure job steps that are distributed across multiple systems in the sysplex (for example, in an IBM SmartBatch environment), ensure that you enter “*ALL” for the SYSTEM parameter.

NUMBER

NUMBER=stepnumber(s) specifies the number of the step within the target job. You specify the number of the job step within the target job you want to measure. AutoStrobe users can specify one step number, multiple step numbers, or a range of step numbers that you want to measure.

To measure a specific step number, code:

AutoStrobe only: To measure multiple step numbers, code:

ADDRESS SPACE ID | ASID

ASID=nn specifies the address space ID of a job. When multiple jobs have the same job name, use ASID to specify which instance to measure.

For example:

Identifying the Target System

If you are using Strobe in a multisystem environment, identify the system, or systems, you want to be potential targets for the measurement request by specifying the SYSTEM or the EXCLUDE parameter.

SYSTEM

SYSTEM=systemname specifies the system, or systems, you wish to be potential targets for the measurement request. When the target job becomes active on one of the systems that you specified, Strobe initiates a measurement session on that system.

For example:

EXCLUDE

EXCLUDE=systemname specifies the system, or systems, on which you do not want to target the measurement request. In the following example, Strobe targets all of the systems in the sysplex, except SYSTEMD, as potential targets for the measurement request:

Specifying Sampling Controls

The following operands allow you to control the duration of the measurement session.

GOMIN

GOMIN=gggg (default 1) specifies the estimated minimum measurement time in minutes. Specify a value between 1 and 1440 minutes. For batch programs, GOMIN should represent the estimated run time (clock time, not CPU time) of the program. For online systems, GOMIN should represent your estimate of the duration of the measurement session. Supply this operand to prevent Strobe from taking an unnecessarily high number of samples. If the job runs longer than the GOMIN value estimate, Strobe will decrease the sampling rate.

The GOMIN operand is used to determine the initial sampling rate Strobe uses. It controls the time interval between each instance of Strobe taking a sample of the program activity. Strobe will sample the job it is measuring until it completes, unless you specify the LIMIT operand.

SAMPLES

SAMPLES=ssssss (default 10,000) specifies the target number of samples to be taken during the measurement session. Specify a value between 1,000 and 150,000. The default value of 10,000 samples provides a 0.98% margin of error at a confidence level of 0.95.

LIMIT | NOLIMIT

LIMIT={({nn,}{QUIT|STOP})}|NOLIMIT (default NOLIMIT, except for CICS) controls the automatic suspension of sampling when the target number of samples is reached. To specify the number of sample data sets to create, supply the nn value (default 1). To control the measurement session when the final data set has been completed, specify QUIT or STOP. Each sample data set will contain the number of samples specified in the SAMPLES operand. If you specify LIMIT without a value, Strobe uses (1,QUIT).

NOLIMIT specifies that sampling is to continue until the target program completes execution. If you specify this keyword, Strobe creates only one sample data set.

When measuring batch job steps, you generally should not specify LIMIT because sampling should continue until the step completes, producing a complete picture of all phases of the program’s execution. LIMIT is useful when you are measuring online subsystems that run continuously because it provides a convenient way to control sampling and it allows you to produce Strobe Performance Profiles from the closed sample data sets while continuing to measure the job step.

For example:

NOSTART

NOSTART delays the beginning of the measurement session.

A measurement will initialize and begin sampling by default. To initialize the measurement session but defer sampling, use the NOSTART operand. Strobe sets the request’s status to suspended and does not allocate a sample data set. To begin sampling, issue a SEND START command. For more information, see Specifying Operands for the SEND Command .

Specify NOSTART to coordinate sampling between requests. To ensure that several jobs are measured at the same time, you can first issue the ADD command with the NOSTART operand, and begin sampling later with a series of SEND commands.

BASELINE

BASELINE=nn (default 2) specifies the percentage of all execution samples that must occur within modules loaded, linked, or attached by the target program in order for Strobe to obtain control section mapping data for those modules. Specify a value between 0 and 100. To map all load modules in which Strobe detects execution, specify 0.

MAPPROGRAM

MAPPROGRAM={(loadmod|(loadmod,...)} specifies modules that are loaded, linked, or attached by the target program and for which control section mapping data is to be obtained regardless of the value assigned to BASELINE.

For example:

SVCS

SVCS={svcno|(svcno , svcno|svcno - svcno,...)} specifies SVC numbers, or ranges of SVC numbers, for which you want to see more detailed reporting. Strobe normally reports all execution of an SVC as occurring within an SVC pseudo-section named “SVC nnn”. When you use the SVCS operand, Strobe shows execution within the modules called by the invocation of the SVC, provided the modules are loaded by MVS contents management. You can supply this parameter if you have written your own SVC and want to examine it for performance improvement opportunities.

STRBLIB

STRBLIB={dsname|(dsname,dsname,...)} specifies the names of additional load libraries for Strobe to search to find module mapping data. Strobe searches the libraries you specify before it searches other libraries.

For a list of these libraries, see LIBRARIES TO SEARCH.

STRBDD

If you often specify the same list of additional load libraries using STRBLIB, STRBDD=ddname provides a convenient shortcut. Use STRBDD to specify a ddname that includes a concatenated list of the additional load libraries you want Strobe to search.

OPTIONS

OPTIONS=options allows you to send additional parameters to Strobe. Normally, the Strobe system programmer uses this operand under the direction of a BMC systems engineer to enter parameters for Strobe problem determination.

Specifying Routing Information

NOTIFY

NOTIFY

NOTIFY specifies a user ID to receive the Strobe message that the measurement session has completed.

NOTIFY | NONOTIFY

NOTIFY=tsoid|NONOTIFY determines whether, when a measurement session completes, Strobe issues a TSO NOTIFY message to a user ID on the system where the measurement request originated. If you submit the job through TSO, the Strobe default is to issue a NOTIFY message. If you submit the request through a batch job or started task, the default is for Strobe not to issue a NOTIFY message.

To receive a NOTIFY message when you submit a request through a batch job or started task, specify NOTIFY=tsoid. To suppress the NOTIFY message, specify NONOTIFY.

APPNAME (AutoStrobe only)

APPNAME= iStrobename is used in conjunction with iStrobe.

Specifying Sample Data set Characteristics

The sample data set contains the data collected during the measurement session. You can provide the data set name prefix, unit, volume, and disposition information as described below. For more information on the format of the data set name, see LIBRARIES TO SEARCH.

DSNAME | SAMDSN

{DSNAME|SAMDSN}=dsname specifies all high-level qualifiers of the sample data set name. If you do not specify a prefix, Strobe uses the default qualifiers specified during system installation. The prefix and suffix combined cannot exceed 26 characters. The character limit does not include quotation marks or parentheses.

Strobe appends to the prefix the job name of the target job step or program and an eight-character session/data set number identifier. The length of the data set name must not exceed the MVS operating system maximum of 44 characters.

The sample data set is allocated in the address space of the target program. Therefore, you should choose a prefix that conforms to the security requirements for your installation.

UNIT

UNIT=unitname specifies the name of the unit on which sample data sets are to be allocated. Your system programmer may have specified a default value during system installation. If you do not specify a unit, the operating system determines it. If the data set already exists, Strobe ignores the UNIT specification.

VOLUME

VOLUME=volser specifies the serial number of the volume on which sample data sets are to be allocated. Your system programmer may have specified a default value during system installation. If you do not specify a volume, the operating system determines it. If the data set already exists, Strobe ignores the VOLUME specification.

DISPOSITION

DISPOSITION=CATLG|KEEP specifies the disposition of the sample data sets. If you omit this parameter, Strobe uses the system default, specified by your system programmer during Strobe installation.

STORCLAS

STORCLAS=sms storage class specifies the storage class of the sample data set, for installations with System Managed Storage (SMS).

MGMTCLAS

MGMTCLAS=sms management class specifies the management class of the sample data set, for installations with SMS.

DATACLAS

DATACLAS=sms data class specifies the data class of the sample data set for installations with SMS.

Specifying Request Retention Options

RETAIN=(QUEUED=nnn, COMPLETE=nnn) (default 7) specifies how long Strobe keeps a submitted request on the system.

• The QUEUED subparameter specifies how many days from today to retain a measurement request for a job that has not executed. If Strobe has not measured the requested job step after the specified number of days, Strobe deletes the request at the end of the final day. Specify a value between 0 and 999. Specifying QUEUED=999 causes the request to remain queued until Strobe measures the requested job step. QUEUED is not valid for active and completed requests.
• The COMPLETE subparameter specifies how long to retain a request after measurement completes. After the specified number of days elapses, Strobe deletes a request at the end of the final day. Specify a value between 0 and 999. Specifying COMPLETE=999 causes the request to remain on the system indefinitely. If you change a completed request, the COMPLETE subparameter specifies the number of days from the current day to retain the request.

If you specify 0, Strobe will delete the request at midnight of the day on which you make the specification.

Specifying Data Collector Options

You rarely need to use the following command operands. Under normal circumstances, Strobe invokes Strobe options in a configuration appropriate for the environment.

You must specify a data collector option if your installation uses a nonstandard name for any of the subsystems that Strobe supports, unless your Strobe system programmer has provided an alias for the Strobe data collector during system installation.

Strobe loads a data collector whenever it finds a module with the name (or alias) STRBnnnn, where nnnn is the unique four-character prefix of the name of the module that begins execution in the target subsystem. For example, if the load module that initializes a CICS job step begins with the IBM standard prefix “DFHSIP,” Strobe loads the CICS data collector STRBDFHS whenever it encounters a measurement request for a CICS address space.

To force the loading of a data collector when Strobe would not normally load it, specify the keyword.To override the loading of a data collector, prefix the keyword that loads the data collector with “NO“. For example, “NOCICS”.

CICS

CICS|NOCICS is the keyword for Strobe for CICS. These keyword subparameters can follow it:

• CPS|NOCPS determines whether Strobe collects information for the CICS Performance Supplement.
• TERM|NOTERM controls whether Strobe produces the Terminal Statistics report in the CICS Performance Supplement.
• ATTR|NOATTR controls whether Strobe collects CICS attribution data.

• TRAN= {tran (tran,tran,...)} enables you to specify up to five transactions for which Strobe collects detailed performance information. Enter any valid CICS transaction name.

  Important

  The names of CICS system transactions are not valid in this field.

  To target sets of transactions, enter a wildcard (*) as the last character. When you specify this parameter, Strobe uses the following defaults: RLI ,  NOCPS ,  NOTERM. You cannot specify this parameter with CPS, TERM, or NOATTR.

• RLI|NORLI determines whether Strobe collects region-level information. The defaults that Strobe uses depend upon other values specified:

  If you specify	Default is
  RLI	NOCPS and NOTERM
  TRAN=	RLI
  CPS or TERM	NORLI

  You cannot specify RLI with CPS or TERM.

• DSSIZE = nn (default 2048K) enables you to specify the size of the dataspace, in kilobytes, for Strobe for CICS. The minimum value is 100K, and the maximum value is 3072K. You cannot specify this parameter with CPS or TERM.
• CAPTBUFF=nn (default 34K) enables you to determine the size, in kilobytes, of the service time capture buffer that Strobe for CICS uses. The minimum value is 34K, and the maximum value is 1000K. You cannot specify this parameter with CPS or TERM.

To suppress the terminal statistics reports from the CICS Performance Supplement, code:

For more information on these options, refer to the the CICS section of the Using-Strobe-options.

IMS

IMS|NOIMS is the keyword for Strobe for IMS. You may follow it with these keyword subparameters:

• ATTR|NOATTR controls whether Strobe collects IMS attribution data.
• CAPTURE|NOCAPTURE controls whether Strobe collects IMS transaction counts and service time data.

For information on these options, see the IMS section of the Using-Strobe-options.

Db2

DB2|NODB2 is the keyword for Strobe for Db2. You may follow it with these keyword subparameters:

• CAPTURE|NOCAPTURE controls whether Strobe collects Db2 SQL CPU usage.
• DB2CLIST=('filterIDvalue'|'filterIDvalue,'filterIDvalue',...) limits the amount of trace information collected using the IBM Db2 instrumentation facility interface (IFI). You should be familiar with IFI and its command requirements before using this feature. You must surround values containing lowercase characters with two pairs of single quotes in order to retain the lowercase. For example, entering ''DB2-value'' will retain the lowercase of “value”.The filterID portion of 'filterIDvalue' is a prefix ID where:
  • P = Plan
  • A = AuthIDs
  • C = CorrIDs
  • L = Locations
  • U = Enduser IDs
  • T = Enduser Transactions
  • W = Enduser Workstations
  • * = Freeform text string.

For information on these options, see the Db2 section of the Using-Strobe-options.

To suppress the collection of Db2 data while measuring within a Db2 region, enter the following:

DDFRQSTR

DDFRQSTR is the keyword that determines how SQL data is collected for the DDF SQL Statement by DBRM by Requester report. The requester is the source of the SQL that is executing in the DDF address space. You can assign either one or two of the following values:

• REQLOC—Produces the DDF SQL Statement by DBRM by Requester report by location, which is either the IP address or LU name of the requester.
• CORRID—Produces the DDF SQL Statement by DBRM by Requester report by correlation ID.
• AUTHID—Produces the DDF SQL Statement by DBRM by Requester report by authorization ID.
• EUUSER—Produces the DDF SQL Statement by DBRM by End User USERID report.
• EUWORK—Produces the DDF SQL Statement by DBRM by End User Workstation report.
• EUTRAN—Produces the DDF SQL Statement by DBRM by End User Transaction report.

Examples:

Use this syntax to assign one value:

Use this syntax to assign two values, where value 1 and value 2 each represent one of the values specified in the previous syntax. Notice that value 1 and value 2 are separated by a comma and are enclosed by a single quote.

For more information about this parameter, refer to the Db2 section of the Using-Strobe-options.

IEF

IEF|NOIEF is the keyword subparameter for Strobe for CA Gen.

NATURAL

NATURAL|NONATURAL is the keyword subparameter for the NATURAL language attributor. NATURAL is required for batch programs that invoke NATURAL.

ADABAS

ADABAS|NOADABAS is the keyword subparameter for the ADABAS data collector.

ADA3GL

ADA3GL|NOADA3GL is the keyword subparameter for attributing wait time caused by a 3GL program written in COBOL, FORTRAN, Assembler, or PL/I, in an ADABAS/NATURAL environment.

IDMS

IDMS|NOIDMS is the keyword for Strobe for Advantage CA-IDMS. You may follow it with this keyword subparameter:

ADSO|NOADSO controls whether Strobe collects ADS/O attribution data.

DML

DML|NODML determines whether Strobe collects CA-IDMS attribution data for DML wait time. DML is required for batch DML wait attribution. Do not specify IDMS if you specify DML. The IDMS data collector is automatically invoked if you specify DML.

DCC

DCC={program|(program,program,...)} allows you to specify your own user-written data collectors. When you specify more than one data collector program, Strobe invokes the programs in the order you specify. For instructions on writing a data collector program, see the Interface section of the Using-Strobe-options.

You can also include the name of Strobe options in the list if you want to have them execute after your data collector.

For example:

MQSERIES

MQSERIES|NOMQSERIES is the keyword for Strobe for WebSphere MQ. It determines whether Strobe gathers WebSphere MQ-related data collector and attribution data. You may follow it with these keyword subparameters:

• MQROUTINE=modulename enables you to specify the name of an MQSeries user module so that Strobe will attempt to identify its caller.
• CAPTURE|NOCAPTURE controls whether Strobe collects counts for the following MQI functions: MQOPEN, MQCLOSE, MQPUT, MQPUT1, MQGET, MQINQ, MQSET. The default is NOCAPTURE; if you omit this parameter, Strobe uses the default.

Additional Attribution Options

Use the following operands to determine whether Strobe collects attribution data.

ATTRSVC | NOATTRSVC

ATTRSVC|NOATTRSVC collects data that shows sites of SVC invocation. Strobe collects the data to produce the SVC Attribution reports in the Performance Profile.

PLI | NOPLI

PLI|NOPLI determines whether Strobe collects PL/I attribution data. This data is used to produce the PL/I Attribution reports in the Performance Profile.

C | NOC

C|NOC controls whether Strobe collects C attribution data. This information is used to produce the C Attribution reports in the Performance Profile.

COBOL | NOCOBOL

COBOL|NOCOBOL controls whether Strobe collects COBOL attribution data. This information is used to produce the COBOL Attribution reports in the Performance Profile.

ATTRLNK | NOATTRLNK

ATTRLNK | NOATTRLNK determines whether Strobe collects attribution data for applications that use z/OS UNIX System Services, WebSphere MQ OS/390 middleware product, or MVS Coupling Facilities. Specifying NOATTRLNK severely restricts Strobe ability to collect attribution data for UNIX System Services, WebSphere MQ, and MVS Coupling Facilities activity.

VSAM | NOVSAM

VSAM | NOVSAM determines whether Strobe collects VSAM attribution data.