End Transaction (QYPEENDT, qypeEndTransaction) API

The End Transaction (OPM, QYPEENDT; ILE, qypeEndTransaction) API is used together with the Start Transaction (QYPESTRT, qypeStartTransaction) API and the Log Transaction (QYPELOGT, qypeLogTransaction) API to collect performance data for user-defined transactions. The End Transaction API is called by an application at the end of a user-defined transaction.

This API can be used to provide both trace type of performance data - collected by Performance Explorer (PEX) - and interval type of performance data - collected by Collection Services.

If the Performance Explorer (PEX) is running, this API generates an end of transaction trace record. In addition to the data supplied by the application in the application trace data parameter, PEX will capture the current values of performance counters associated with the current thread such as CPU time used, I/O activity and seize/lock activity. After the End Performance Explorer (ENDPEX) command is run, the application-supplied data for this record is written to the QMUDTA field in the QAYPEMIUSR file. The performance counters are written to individual fields in the QAYPEMIUSR and QAYPETIDX files.

If Collection Services is collecting data for the user-defined transaction (*USRTNS) category, this API will save transaction performance data for the current transaction. This data includes transaction response time as well as optional performance counters provided by the application in the application performance counters parameter.

See Usage Notes for the Start Transaction (QYPESTRT, qypeStartTransaction) API for more information.

Authorities and Locks

API Public Authority

*USE

Required Parameter Group

Application identifier

INPUT; CHAR(20)

The name of the application. Given that many applications could use this API, the name should be chosen so that it is unique. Application identifiers starting with "QIBM_Qccc_", where ccc is a component identifier, are reserved for IBM use.

The application identifier is used as the transaction type by Collection Services. The application identifier should be chosen carefully, because Collection Services will only report information about the first 15 unique transaction types for every job which uses user-defined transaction APIs. All other transaction types for each job will be combined in a single type *OTHER.

Transaction identifier

INPUT; BINARY(4) UNSIGNED

Any sort of unique transaction identifier, such as a sequential number. In order to collect meaningful data, the identifier passed to the End Transaction API should be the same as the identifier used in the call to the Start Transaction API for the same transaction.

The transaction identifier is not used by Collection Services.

Application trace data

INPUT; CHAR(*)

Application-defined trace data to be saved by PEX. This can be any data that the user wants to associate with this transaction - for example, the user ID of the client performing the transaction, the name of the file being updated by the transaction, or the account ID being accessed by the transaction. The data can be up to 3032 bytes long. This data is reported by PEX in the QAYPEMIUSR file. Application trace data is not processed by Collection Services.

Length of application trace data

INPUT; BINARY(4) UNSIGNED

The length (in bytes) of application-defined trace data to be saved by PEX. The value must be between 0 and 3032.

Transaction start time

INPUT; CHAR(8)

The time (in MI timestamp format) that the transaction started. The user should provide the transaction start time that was previously returned from the call to the corresponding Start Transaction API. If a null pointer is passed for this parameter, Collection Services will ignore this request. Transaction start time is not used by PEX.

Application performance counters

INPUT; CHAR(*)

Application-provided counter data to be collected by Collection Services. The application can define from 0 to 16 BINARY(8) UNSIGNED counters that Collection Services will collect. These counters may contain any kind of information the application wants to associate with this transaction; for exampel, the number of SQL statements processed to serve the transaction, the number of pages printed for the transaction, and so on. The user should reset these counters just before calling the Start Transaction API and provide these counters when calling the corresponding End Transaction API. If the application trace data is suitably organized - if it is a sequence of BINARY(8) UNSIGNED counters - the application performance counters parameter can be a subset of the application trace data parameter .

Application performance counters are not processed by PEX.

Length of application performance counters

INPUT; BINARY(4) UNSIGNED

The length (in bytes) of the application-provided counter data to be collected by Collection Services. This length can range from 0 (no counters) to 128 (16 BINARY(8) UNSIGNED counters) and must be a multiple of 8.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Usage Notes

For the description of how Performance Explorer (PEX) and Collection Services save and report performance data for this API, see Usage Notes for the Start Transaction API.

Error Messages