End Performance Explorer (ENDPEX)

The End Performance Explorer (ENDPEX) command instructs the Performance Explorer tool to stop collecting data. The command expects a session name to accompany the request which identifies which instance of the Performance Explorer session to end.

The user can either end the data collection session or suspend the data collection session. If the user chooses to end the session, the collected data is put into an object of type *MGTCOL or into a set of database files, or it is deleted, based on the value specified for the DTAOPT parameter.

If the user chooses to suspend the collection of performance data, the session remains active. To resume data collection for a suspended session, the user can specify OPTION(*RESUME) on a subsequent call of the STRPEX (Start Performance Explorer) command.

Restrictions:

This command is shipped with public *EXCLUDE authority.
The user must have *ADD and *EXECUTE authority to the specified DTALIB and MGTCOL libraries.
The user must have *OBJMGMT, *OBJEXIST, and use authorities to the managment collection object if replacing an existing management collecton object.
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
If running ENDPEX from a secondary thread, the QAYPE* files must already exist in the DTALIB library. These files must be created in the primary thread by running ENDPEX DTAOPT(*LIB).
If running ENDPEX from a secondary thread, DTAOPT(*MGTCOL) object cannot be specified.
Two threads within the same job will not be allowed to run ENDPEX at the same time. The thread that issued ENDPEX first will run the command to completion while the second ENDPEX waits.

Parameters

Keyword	Description	Choices	Notes
SSNID	Session ID	Name, *SELECT	Optional, Positional 1
OPTION	Option	END, SUSPEND, *STOP	Optional
DTAOPT	Data option	LIB, MGTCOL, *DLT	Optional
DTALIB	Data library	Name, QPEXDATA	Optional
DTAMBR	Data member	Name, *SSNID	Optional
MGTCOL	Management collection	Qualified object name	Optional
	Qualifier 1: Management collection	Name, *SSNID
	Qualifier 2: Library	Name, QPEXDATA
RPLDTA	Replace data	NO, YES	Optional
NBRTHD	Number of threads	1-256, *CALC	Optional
TEXT	Text 'description'	Character value, *BLANK	Optional

Top

Session ID (SSNID)

Specifies which Performance Explorer session to end. This is the session identifier that was specified on the STRPEX (Start Performance Explorer) command.

*SELECT: A list panel of all active Performance Explorer data collection sessions will be displayed with an option to select which session to end. *SELECT is only valid if the ENDPEX command is being run interactively. If the command is being run in batch, a session identifier must be specified.
session-identifier: Specify the Performance Explorer data collection session to end.

Option (OPTION)

Specifies whether to end the data collection session or just suspend collection of performance data for the session.

*END

The Performance Explorer session is ended. The user is prompted for a choice of three methods to handle the collected data:

Save the collected data to a set of database files.
Save the data to a single file (used for sending data to IBM for analysis).
Discard the data.

*SUSPEND

The Performance Explorer session is suspended, and the session remains active but no additional data is collected for this session. Once a session is suspended, the user can use STRPEX with OPTION(*RESUME) to resume data collection, end the suspended session by specifying ENDPEX with OPTION(*END), or stop the suspended session by specifying ENDPEX with OPTION(*STOP).

*STOP

The Performance Explorer session is ended and the jobs are removed from the collection. The session cannot be started up again. Addresses are not resolved to object names, and no database files are created. The address data and database files can be created at a later time with the OPTION(*END) and DTAOPT(*LIB or *MGTCOL) options of ENDPEX. However, Performance Explorer may not be able to resolve some of the addresses if objects get deleted. The longer the time between *STOP and *END, the greater the chance the resolved address data will be incomplete.

Data option (DTAOPT)

Specifies how to handle the collected data. The collected data can be stored in a set of database files or a management collection object (*MGTCOL), or both. The temporary management collection object used to hold the collected data will be deleted. To delete the temporary management collection object without storing the collected data, specify *DLT.

Note: This parameter is valid only if OPTION(*END) is specified.

*LIB: Indicates to store all of the collected performance data for the session into a set of database files located in the library specified on the DTALIB parameter. The Performance Explorer tool creates all the necessary files if this is the first time that a library is being used to store performance data. The member name for each of the files where the session data is stored can be controlled through the DTAMBR parameter, but defaults to be the same name as the session identifier.
*MGTCOL: Indicates to store all of the collected data in a management collection object (type *MGTCOL). No database files will be created. This option can be used if the data is to be shipped to another system or to your service provider for analysis.
*DLT: The collected performance data for the session is to be deleted from the system.

Data library (DTALIB)

Specifies the name of the library that contains the set of database files where the collected performance data is stored.

Note: This parameter is valid only if the user specified DTAOPT(*LIB).

QPEXDATA: The QPEXDATA library is the recommended library for storing data collected with the Performance Explorer tool. The first time the Performance Explorer tool is used, this library is created for the user, and a set of database files to store the information is created in that library.
library-name: Specifies the name of the library in which to store the collected data. If the library does not exist, the command ends in an error condition. After the library is created, retry the command. If the specified library does not already have the performance database files, they are created and the data is stored.

Data member (DTAMBR)

Specifies the name to be used for the database file members where the collected performance data is stored. If a member does not exist by the specified name, it is created.

Note: This parameter is valid only when DTAOPT(*LIB) is specified.

*SSNID: The member name is the same as the value specified for the SSNID parameter.
member-name: Specify the member name to use when storing the collected data in Performance Explorer database files.

Management collection (MGTCOL)

Specifies the name of a management collection object to store the collected performance data.

Note: This parameter is valid only if DTAOPT(*MGTCOL) is specified.

The *MGTCOL object name can be qualified by one of the following library values:

QPEXDATA

The QPEXDATA library is the recommended library for storing data collected by the Performance Explorer tool. The first time the Performance Explorer tool is used, this library is created for the user.

data-library-name

Specify the name of the library to store the collected data. If the library does not exist, the command ends in an error condition. After the library is created, retry the command.

*SSNID: The name specified for the SSNID parameter is used when creating the management collection object to contain the collected performance data.
management-collection-name: Specify the name to use when creating the management collection object to contain the collected performance data.

Replace data (RPLDTA)

Specifies whether to replace the data in an existing file member or management collection object with the new performance data. If DTAMBR was specified and a member with the same name already exists in any of the Performance Explorer database files in the specified library (DTALIB parameter), this parameter controls whether the member data is replaced. If MGTCOL was specified and an object already exists with the same name, this parameter controls whether the data in that object is replaced.

*NO: If a member already exists with the same name, an error message is sent to the user. This prevents the user from inadvertently writing over existing data.
*YES: If a member already exists with the same name, the old data is lost and is replaced by the new data.

Number of threads (NBRTHD)

Specifies the number of concurrent threads that the ENDPEX command uses to process the data in the session being ended. Specifying a number greater than 1 allows the ENDPEX command to take advantage of available CPU cycles, especially on a multi-processor system. While this may speed up the command processing, it may also degrade the performance of other jobs on the system. You can minimize this impact by changing the priority of the job that runs the ENDPEX command to a higher number. You should also verify that the disk subsystem can handle the additional threads.

*CALC: The system calculates a reasonable number of threads to do the command processing which does not use excessive CPU or disk resources.
*MAX: The system calculates a maximum number of threads to do the command processing. An attempt will be made to maximize utilization on all resources to minimize processing time. This may cause severe degradation for all other jobs on the system.
number-of-threads: Specify the number of threads for the ENDPEX command to use to process the collected data.

Examples

Example 1: End a Session and Save the Database Files

ENDPEX   SSNID(TEST3)  OPTION(*END)  DTAOPT(*LIB)
         DTAMBR(SYS1DATA)

This command ends the performance explorer session named TEST3 and saves the data in a set of database files in library QPEXDATA. The member name to be used for each file is SYS1DATA.

Example 2: End a Session and Delete the Data

ENDPEX   SSNID(TESTRUN)  OPTION(*END)  DTAOPT(*DLT)

This command ends the performance explorer session named TESTRUN and deletes the collected performance data.

Example 3: End a Session and Save the *MGTCOL

ENDPEX   SSNID(TEST3)  OPTION(*END)  DTAOPT(*MGTCOL)
         MGTCOL(MYLIB/SYS1DATA)  NBRTHD(*CALC)

This command ends the performance explorer session named TEST3 and saves the data in a management collection object in library MYLIB in the management collection object named SYS1DATA. ENDPEX will calculate a number of threads to process this request. This number of threads will do the ENDPEX processing as quickly as possible without disrupting the rest of the system.