CHGPEXDFN (Change Performance Explorer Definition)

CHGPEXDFN Command syntax diagram

 

Purpose

The Change Performance Explorer Definition (CHGPEXDFN) command changes an existing performance explorer definition. The current values stored in an existing definition are inserted when the CHGPEXDFN command is prompted. Each definition is stored as a member in the QAPEXDFN file in library QUSRSYS. A performance explorer definition identifies the performance data to be collected during a performance explorer session. A session can be started using the Start Performance Explorer (STRPEX) command. When starting a new session, a performance explorer definition name must be provided.

Additional information about the performance explorer tool can be found in the Performance Tools for iSeries book.

 

Restrictions

  1. This command is shipped with PUBLIC *EXCLUDE authority.

  2. You must have execute authority to the PGM library if PGM is specified.

  3. To use this command have *SERVICE special authority, or be authorized to the Service Trace function of Operating System/400 through iSeries Navigator's Application Administration support. The Change Function Usage Information (QSYCHFUI) API, with a function ID of QIBM_SERVICE_TRACE, can also be used to change the list of users that are allowed to perform trace operations.

  4. The following user profiles have private authorities to use the command:

    • QPGMR

    • QSRV

    >

 

Required Parameters

DFN
Specifies the name of the performance explorer definition to be changed. If no definition by this name exists (that is, no member by this name exists in file QAPEXDFN in library QUSRSYS), an error condition will occur. The user can either change the definition name or add a definition by the specified name using the Add Performance Explorer Definition (ADDPEXDFN) command, and try this command again.

definition-name: Specify the name of the performance explorer definition to change.

 

Optional Parameters

TYPE
Specifies the type of performance data to be collected.

*SAME: The value does not change.

*STATS: General performance statistics are collected to help identify the problem areas. This mode is mainly used as a map to help determine if and where more detailed information should be collected and analyzed.

*TRACE: Detailed trace information is collected. This is the most detailed type of performance data collection available.

*PROFILE: Specific programs are sampled to identify sections of code that are using larger amounts of resources. This information is very valuable when the user wants to improve the performance of a specific program or application.

JOB
Specifies which jobs are included in the performance explorer data collection session.

Single Value>

*SAME: The value does not change.

*: Only the job that issues the STRPEX (Start Performance Explorer) command is included.

*ALL: All jobs on the system are included.

Element 1: Job Identifier>

job-name: Specify the name of the job to be included.

generic*-job-name: Specify the generic name of the jobs to be included.

Job User Name Qualifier>

*ALL: All jobs that match the specified job name will be included.

user-name: Specify a user name to further qualify the job name.

generic*-user-name: Specify the generic user name of the jobs to be included.

Job Number Qualfier

*ALL: All jobs that match the specified job name and user name are included.

job-number: Specify the job number to further qualify the job name and user name.

TASK
Specifies which licensed internal code (LIC) tasks are included in the performance explorer data collection session.

*SAME: The value does not change.

*NONE: No LIC tasks on the system are included.

*ALL: All LIC tasks on the system are included.

task-name: Specify the name of the task to be included in the performance explorer data collection session.

generic*-task-name: Specify the generic name of the task to be included. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. For more information on the use of generic names, refer to generic names.

PGM
Specifies the program whose performance profile data is collected. Up to 16 programs may be specified.

Note: This parameter is only valid when TYPE(*PROFILE) is specified.

*SAME: The value does not change.

Element 1: Program Name

The program name can be qualified by one of the following library values:

*LIBL: The library list of the job that issues the STRPEX command is searched to find the specified program or service program.

library-name: Specify the name of the library which contains the program or service program.

program-name: Specify the name of the program to be sampled.

Element 2: Module Name

*ALL: All modules in the program or service program are sampled. If sampling an OPM (Original Program Model) *PGM, specify *ALL or *N for this element.

*PGM: Only the module that has the same name as the program or service program is sampled.

module-name: Specify the name of the module within the program or service program that is to be sampled.

Element 3: Procedure Name

*ALL: All procedures in the specified module are sampled. If sampling an OPM (Original Program Model) *PGM, specify *ALL or *N for this element.

procedure-name: Indicate a specific procedure within the specified module that is to be sampled.

Element 4: Program Type

Indicate the type of program being specified. All procedures in the specified module are sampled. If sampling an OPM (Original Program Model) *PGM, specify *ALL or *N for this element.

*PGM: The program being specified is a program (*PGM) object.

*SRVPGM: The program being specified is a service program (*SRVPGM) object.

Element 5: Pane Size

Specifies the pane size, which is the number of consecutive program instruction addresses assigned to each counter. The smaller the pane size, the more fine-grained the program profile information will be.

4: Default pane size is 4.

pane-size: Specify the pane size to use for the program. Valid values are 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096.

DTAORG
Specifies how the data will be organized.

Note: This parameter is only valid if TYPE(*STATS) is specified.

*SAME: The value does not change.

*FLAT: The performance explorer tool will not collect data for a parent-child relationship.

*HIER: The performance explorer tool will collect data for a parent-child relationship.

MAXSTG
Specifies the maximum amount of storage, in kilobytes (K), that the performance explorer tool will use for collecting trace data.

Note: This parameter is only valid if TYPE(*TRACE) is specified.

*SAME: The value does not change.

maximum-K-bytes: Specify the maximum amount of storage, in kilobytes, used to store trace records (one K equals 1024 bytes). Valid values range from 1K to 4000000K (4 gigabytes).

TRCFULL
Specifies whether the trace records wrap (replace oldest records with new records) or whether the trace stops when all of the storage specified by the MAXSTG parameter has been used.

Note: This parameter is only valid if TYPE(*TRACE) is specified.

*SAME: The value does not change.

*STOPTRC: Tracing stops when the trace file is full of trace records.

*WRAP: When the trace file is full, the trace wraps to the beginning. The oldest trace records are written over by new ones as they are collected.

MRGJOB
Specifies whether the data from different jobs should be merged in one data area or kept separate (for example, one data area for each job).

Note: This parameter is only valid if DTAORG(*FLAT) is specified.

*SAME: The value does not change.

*YES: The data of individual jobs is merged.

*NO: The data of individual jobs is kept separate.

INTERVAL
Specifies the interval at which samples are taken of the program. A low interval will cause a high number of samples to be taken, and will also cause higher overhead. A low interval will also provide a significant amount of data.

Note: This parameter is only valid when TYPE(*TRACE) or TYPE(*PROFILE) is specified.

*SAME: The value does not change.

sampling-interval: Specify the interval at which samples are taken of the program. Valid values range from 0.1 to 200.0 milliseconds.

TRCTYPE
Specifies the types of trace performance data to be collected.

Note: This parameter is only valid if TYPE(*TRACE) is specified.

Note: Additional information about the TRCTYPE options can be found in the Performance Tools for iSeries book.

Single Values

*SAME: The value does not change.

*SLTEVT: Only selected individual events and machine instructions are included in the trace definition.

Note: If TRCTYPE(*SLTEVT) is specified, SLTEVT(*YES) must have been specified when the performance explorer definition was created (ADDPEXDFN command).

Trace Event Categories

Specify one or more categories of events to be included in the trace definition.

*CALLRTN: Specifies that call return events are included in the trace definition. Call return events occur when a program is entered and exited as well as when certain machine instruction are started and completed.

*BASIC: Specifies that events relative to general performance analysis are included in the trace definition. This option should be used when it is unclear as to what type of performance problem determination is necessary.

*DSKIO1: Specifies that events associated with disk input/output operations are included in the trace definition.

*DSKIO2: Specifies that events associated with disk input/output operations plus higher level requests to do input/output operations are included in the trace definition.

*DSKSVR: Specifies that events associated with disk server operations are included in the trace definition.

*DSKSTG: Specifies that events associated with disk space consumption are included in the trace definition.

*VRTADR: Specifies that events associated with virtual address assignment are included in the trace definition.

*PGMACT: Specifies that events associated with program activations and deactivations are included in the trace definition.

*FILEOPEN: Specifies that events associated with file opens are included in the trace definition.

*PRFDTA: Specifies that events associated CPU instruction profiling are included in the trace definition.

*TASKSWT: Specifies that events associated with tasking are included in the trace definition.

TEXT
Specifies the text that briefly describes the performance explorer definition. More information is in Commonly used parameters.

*SAME: The value does not change.

*BLANK: Text is not specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Examples for CHGPEXDFN

Example 1: Using TYPE(*TRACE) 

CHGPEXDFN   DFN(TEST1)  TYPE(*TRACE)
  JOB(*)  MAXSTG(5000)

This command changes the performance definition named TEST1. When this definition is used to start a performance explorer session (STRPEX command), detailed trace information will be collected for the job that invoked the STRPEX command. A maximum of 5000 kilobytes of trace data will be collected. When the trace record storage area is full no more trace records will be collected.

Example 2: Using TYPE(*PROFILE) 

CHGPEXDFN   DFN(TEST2)  TYPE(*PROFILE)
  PGM((MYLIB/MYSRVPGM1 *ALL *ALL *SRVPGM))

This command changes the performance explorer definition named TEST2. When this definition is used to start a performance explorer session (STRPEX command), performance profile information for service program MYSRVPGM1 in library MYLIB will be collected.

Error messages for CHGPEXDFN

*ESCAPE Messages

CPFAF0E
Definition not found.