Start Performance Explorer (STRPEX)

The Start Performance Explorer (STRPEX) command starts a new Performance Explorer session or resumes a suspended Performance Explorer session.

Restrictions:

1. This command is shipped with public *EXCLUDE authority.
2. To use this command you must have *SERVICE special authority, or be authorized to the Service Trace function of the operating system. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_SERVICE_TRACE, can be used to change the list of users that are allowed to perform trace operations.
3. The following user profiles have private authorities to use the command:
   • QPGMR
   • QSRV
4. Two threads within the same job will not be allowed to run STRPEX at the same time. The thread that issued STRPEX first will run the command to completion while the second STRPEX waits.

Parameters

Session ID (SSNID)

Specifies an identifier for this Performance Explorer session. This name must be unique within the active sessions of the Performance Explorer tool.

This is a required parameter.

session-identifier

Specify the session identifier for a new or suspended Performance Explorer session.

Option (OPTION)

Specifies whether a new session should be started or a session which is currently suspended should be resumed.

This is a required parameter.

*NEW

A new session of the Performance Explorer tool is started. Performance data collection begins as soon as the session has been established.

*INZONLY

A new Performance Explorer session is started, but once the session is established, it is suspended. This option allows the user to perform the setup for a particular session before the scenario to be monitored is started. To begin data collection, the user must invoke this command again specifying the same session identifier and OPTION(*RESUME).

*RESUME

A suspended Performance Explorer session is resumed. The session was suspended either by specifying OPTION(*SUSPEND) on the ENDPEX command or by specifying OPTION(*INZONLY) on a previous STRPEX command.

Definition (DFN)

Specifies the name of the Performance Explorer definition to use when starting a new Performance Explorer session. The definition identifies the performance data to be collected. This parameter is required in order to start a new Performance Explorer session. This parameter cannot be specified when resuming a suspended session, since the suspended session already has an associated Performance Explorer definition.

name

Specify the name of the Performance Explorer definition.

Filter (FTR)

Specifies the name of the Performance Explorer filter to use when starting a new Performance Explorer session. The filter determines which events are collected based on the filter values which are compared to the event's actual data. If a filter is not specified, then all events in the definition are collected. This parameter cannot be specified when resuming a suspended session.

*SELECT

A list of existing filters will be displayed for user selection. This value is valid only if the command is run in an interactive job.

name

Specify the name of the Performance Explorer filter.

Examples

Example 1: Start a New Session

STRPEX   SSNID(TESTRUN2)  DFN(NEWDESC)  OPTION(*NEW)
         FTR(MYFILTER)

This command starts a new session of the performance explorer using the criteria identified in a definition named NEWDESC and a filter named MYFILTER. The new session name is TESTRUN2.

Example 2: Resume a Suspended Session

STRPEX   SSNID(TESTRUN1)  OPTION(*RESUME)

This command resumes an already existing session of the performance explorer named TESTRUN1.

Error messages

Error messages for RMVPEXDFN

*ESCAPE Messages

CPFAF05

STRPEX command was not successful. Reason code is &1. See details for more information.

CPFAF11

Unable to locate program, object, library, or file member as specified in the definition or filter.