Log Transaction (QYPELOGT, qypeLogTransaction) API

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

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

If the Performance Explorer (PEX) is running, this API generates a log 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.

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.

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 Log Transaction API should be the same as the identifier used in the call to the Start Transaction API for the same transaction.

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.

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.

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) saves and reports performance data for this API, see Usage Notes for the Start Transaction API.

Error Messages