Change PEX Definition (CHGPEXDFN)

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 that is to be collected during a Performance Explorer session. A session can be started using the STRPEX (Start Performance Explorer) 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 Management information at http://www.ibm.com/servers/eserver/iseries/perfmgmt/resource.htm.

Restrictions:

This command is shipped with public *EXCLUDE authority.
You must have *EXECUTE authority to the library of each program specified on the PGM parameter.
To use this command you must have *SERVICE special authority, or be authorized to the Service Trace function of i5/OS 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.
The following user profiles have private authorities to use the command:
- QPGMR
- QSRV
Two threads within the same job will not be allowed to run CHGPEXDFN at the same time. The thread that issued CHGPEXDFN first will run the command to completion while the second CHGPEXDFN waits.

Parameters

Keyword	Description	Choices	Notes
DFN	Definition	Name	Required, Key, Positional 1
TYPE	Type	SAME, STATS, TRACE, PROFILE	Optional
JOB	Jobs	Single values: SAME, ALL, * Other values (up to 8 repetitions): Element list	Optional
	Element 1: Job name	Qualified job name
	Qualifier 1: Job name	Generic name, name
	Qualifier 2: User	Generic name, name, *ALL
	Qualifier 3: Number	000001-999999, *ALL
	Element 2: Thread identifier	Values (up to 20 repetitions): 00000001-FFFFFFFF, ALL, INITIAL, *SELECT
TASK	Task name	Single values: SAME, NONE, ALL Other values (up to 10 repetitions): Generic name, name*	Optional
PGM	Program to monitor	Single values: SAME Other values (up to 16 repetitions): Element list*	Optional
	Element 1: Program	Qualified object name
	Qualifier 1: Program	Name
	Qualifier 2: Library	Name, *LIBL
	Element 2: Module	Name, *ALL
	Element 3: Procedure	Character value, *ALL
	Element 4: Type	PGM, SRVPGM
	Element 5: Pane size	4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096
DTAORG	Data organization	SAME, FLAT, *HIER	Optional
MAXSTG	Maximum storage to use	1-4000000, *SAME	Optional
TRCFULL	Trace full	SAME, STOPTRC, *WRAP	Optional
MRGJOB	Merge job data	SAME, NO, *YES	Optional
ADDTHDOPT	Add threads/tasks option	ALL, NEW, *CURRENT	Optional
LSTALLJOB	List all jobs/tasks	SAME, NO, *YES	Optional
INTERVAL	Sampling interval	Element list	Optional
	Element 1: Milliseconds	0.1-200.0, SAME, NONE
	Element 2: Randomize	SAME, FIXED, *VARY
TRCTYPE	Trace type	Single values: SAME Other values (up to 11 repetitions): CALLRTN, BASIC, DSKIO1, DSKIO2, DSKSVR, DSKSTG, VRTADR, PGMACT, FILEOPEN, PRFDTA, TASKSWT	Optional
TEXT	Text 'description'	Character value, SAME, BLANK	Optional

Top

Type (TYPE)

Specifies the type of performance data to be collected.

*SAME: The value does not change.

*STATS

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

In addition to collecting the information specified above, TYPE(*STATS) also provides the option of counting the occurrences of specific types of events. These can be counted in any of 4 counters provided.

To count the occurrences of a particular type of event, specify SLTEVT(*YES) and then choose the event-identifier(s) to be counted from the various event categories.

For example, TYPE(*STATS) SLTEVT(*YES) JOBEVT((*ALL 1)) would count all job events in counter 1.

*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 name (JOB)

Specifies which jobs are included in the Performance Explorer data collection session.

Single values

*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 name

Qualifier 1: Job name

job-name: Specify the name of the job to be included in the Performance Explorer data collection session.
generic*-job-name: Specify the generic name of the job 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 about generic object names, see the i5/OS objects topic under Programming->CL in the iSeries Information Center at the Web site: http://www.ibm.com/eserver/iseries/infocenter

Qualifier 2: User

*ALL: All jobs that match the specified job name are included.
user-name: Specify the name of the user of the job to be included.
generic*-user-name: Specify the generic user name of the jobs to be included.

Qualifier 3: Number

*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.

Element 2: Thread identifier

*ALL: All threads of the specified job are included.
*INITIAL: Only the initial thread of the specified job is included.
*SELECT: Select the threads from a list of threads for the specified job. This value is only valid if the command is run in an interactive job.
thread-identifier: Specify the thread identifier of the job to be included. This is the thread ID as shown by the WRKJOB command.

Task name (TASK)

Specifies which licensed internal code (LIC) tasks are included in the Performance Explorer data collection session. Up to 8 task names may be specified.

Note: LIC tasks can be obtained from the Performance Tools reports and WRKSYSACT command. There is no guarantee that LIC task names will remain the same or exist from system to system or release to release.

Single values

*SAME: The value does not change.

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

Other values

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.

Program to monitor (PGM)

Specifies the program whose performance profile data is collected. This parameter is only valid if TYPE(*PROFILE) is specified. Up to 16 programs may be specified.

Single values

*SAME: The value does not change.

Element 1: Program

Qualifier 1: Program

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

Qualifier 2: Library

*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 library which contains the program or service program.

Element 2: Module

*ALL: All modules in the program or service program will be sampled. If sampling an OPM (Original Program Model) program, specify *ALL for this element.
module-name: Specify the name of the module within the program or service program that is to be sampled.

Element 3: Procedure

*ALL: All procedures in the specified module are sampled.
'procedure-name': Specify the name of a procedure within the specified module that is to be sampled. Specify the procedure name within single quotes if the procedure name contains lower case characters.

Element 4: Type

*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

The pane size 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: The default pane size is 4.
number: Specify the pane size to use for the program. Valid values are 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, and 4096.

Maximum storage to use (MAXSTG)

Specifies the maximum amount of storage, in kilobytes (K), that the Performance Explorer tool uses for collecting trace data.

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

*SAME: The value does not change.

maximum-K-bytes: Specifies the requested maximum amount of storage, in kilobytes (K), to use for the collected trace records. The system calculates the minimum amount of storage that is necessary for the trace. This minimum storage size calculation depends on the system's processor configuration. The minimum amount of storage may be significantly larger than the size specified on the MAXSTG parameter. The system uses the larger of the two values.

Trace full (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.

Add threads/tasks option (ADDTHDOPT)

Specifies what types of threads and tasks should be included in the Performance Explorer session based on the creation time of the threads and tasks relative to the start time of the Performance Explorer session.

*SAME: The value does not change.

*ALL: The collection will include all threads and tasks that satisfy the criteria specified by the JOB and TASK parameters.
*NEW: The collection will include only new threads and tasks that satisfy the criteria specified by the JOB and TASK parameters and are created after the Performance Explorer session is started. Any threads or tasks that are active at the time the Performance Explorer session is started will not be included.
*CURRENT: The collection will include only threads and tasks that satisfy the criteria specified by the JOB and TASK parameters and are active at the time the Performance Explorer session is started. Any threads or tasks created after the start of the Performance Explorer session will not be included.

List all jobs/tasks (LSTALLJOB)

Specifies whether summary data should be listed for all jobs and tasks in the system, or only those jobs and tasks specified on the JOB or TASK parameter.

*SAME: The value does not change.

*NO: Data for a job or task is listed in the task information file only if that job or task is specified on the JOB or TASK parameter.
*YES: Data for all jobs and tasks is listed in the task information file, even if the job or task is not specified on the JOB or TASK parameter.

Sampling interval (INTERVAL)

Specifies the interval at which samples are taken of the program. A small interval will cause a high number of samples to be taken, and will also cause higher overhead. The smaller the sampling interval, the larger the amount of trace data collected.

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

Single values

*SAME: The value does not change.

Element 1: Milliseconds

*NONE: Interval is not used.
0.1-200.0: Specify the interval at which samples of the program are taken. Valid values range from 0.1 to 200.0 milliseconds.

Element 2: Randomize

*FIXED: The sampling interval will always be the value specified for element 1 of this parameter.
*VARY: The sampling interval will be approximately the value specified for element 1 of this parameter. The specified interval will be changed each time by adding or subtracting a small random percentage of the interval. This may be necessary to eliminate harmonics when the set of threads/tasks in a collection have settled into a steady state sequence of machine cycles that do not vary in order or length during the collection.

Trace type (TRCTYPE)

Specifies what type of trace performance data to be collected. Additional information about the TRCTYPE options can be found in the Performance Management information at http://www.ibm.com/servers/eserver/iseries/perfmgmt/resource.htm.

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

Single values

*SAME: The value does not change.

Other values

*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 instructions 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 storage 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 (*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.

Examples

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.