| 1 | Application identifier | Input | Char(20) |
| 2 | Transaction identifier | Input | Binary(4) Unsigned |
| 3 | Application trace data | Input | Char(*) |
| 4 | Length of application trace data | Input | Binary(4) Unsigned |
| 5 | Transaction start time | Output | Char(8) |
| 6 | Error code | I/O | Char(*) |
The Start Transaction (OPM, QYPESTRT; ILE, qypeStartTransaction) API is used together with the End Transaction (QYPEENDT, qypeEndTransaction) API and the Log Transaction (QYPELOGT, qypeLogTransaction) API to collect performance data for user-defined transactions. The Start Transaction API is called by an application at the beginning 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 a start 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 (see Usage Notes). 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 provides a reference point for the End Transaction API to calculate transaction response time. (See the End Transaction (QYPEENDT, qypeEndTransaction) API).
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.
Any sort of unique transaction identifier, such as a sequential number. The transaction identifier is not used by Collection Services.
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. See Usage Notes for more information.
The length (in bytes) of user-defined data to be captured by PEX. The value must be between 0 and 3032.
The time (in MI timestamp format) that the transaction started. The user should save this value and pass it unchanged to the corresponding End 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.
The structure in which to return error information. For the format of the structure, see Error code parameter.
Performance data provided by an application to the user-defined transaction APIs (the Start Transaction API, the End Transaction API and the Log Transaction API) is collected by both Performance Explorer (PEX) and Collection Services.
To capture the trace data provided by the APIs, a Performance Explorer session muct be active for the current thread. To configure PEX to collect data for user-defined transaction APIs, use *USRTNS event on the operating system events (OSEVT) parameter of the Add PEX Definition (ADDPEXDFN) command.
When a PEX session is active for the current thread, a call to the Start Transaction API, the End Transaction API or the Log Transaction API will produce a trace record. In addition to the trace data passed by the application in the application trace data parameter, PEX will capture current values of system performance counters associated with the current thread.
The application trace data is reported by PEX in the QMUDTA field of the QAYPEMIUSR file (see below). The performance counters are reported in individual fields in the QAYPEMIUSR and QAYPETIDX files. This data can be used later to calculate resource consumption for the specific transaction.
Collection Services collects transaction-related statistics in a management collection (*MGTCOL) object when the collection is enabled for the *USRTNS performance category. The Create Performance Data (CRTPFRDTA) command exports the user transaction data collected by Collection Services from the *MGTCOL object to the user-defined transaction (QAPMUSRTNS) file. This file contains one record per transaction type per job per Collection Services collection interval. The data reported in the file includes standard data such as the total transaction time and total number of transactions, as well as optional application-provided counters (see End Transaction (QYPEENDT, qypeEndTransaction) API).
Collection Services summarizes transaction data within a job by transaction type. Collection Services uses the API application identifier parameter as the transaction type. Collection Services stores transaction data for the first 15 transaction types it encounters for a job. If more than 15 transaction types are encountered in a job, it still collects the data; however, the data is combined and reported under a transaction type of *OTHER. (See Collection Services for more information on Collection Services and performance database files.)
It is the application's responsibility to decide what constitutes a transaction and to use the user-defined transation APIs in a consistent way; that is, for every call to the Start Transaction API, there should be a call to the End Transaction API with the same transaction identifier.
Performance Explorer collects application-provided trace data as well as current values for a set of system performance counters. These performance counters are a snapshot of the current thread activity when the event was recorded - this means that all numeric values are total numbers for the entire life of the thread (in other words, "raw" values as opposed to "delta" values).
Note:The performance counters are defined as 8 byte unsigned binary values in the QAYPEMIUSR file. However the data is coming from 4 byte unsigned binary values. For this reason, code which does computations with the values of the performance counters must check for counter wrap - counters will increment from 4,294,967,295 (or FFFFFFFF hexadecimal) to 0. The counters were defined as 8 byte fields to allow expansion in the future.
If a transaction ends in the same thread it was started in, values captured by the Start Transaction API can be subtracted from the values captured by the End Transaction API to get the amount consumed by this transaction:
value per transaction =
value from the End Transaction API - value from the Start Transaction API
However, if a transaction ends in a different thread than it was started in, this simple subtraction cannot be done. Rather, it is necessary to use the Log Transaction API to record two additional events - one when the transaction in the first thread ends and the other one when the transaction in the second thread begins. Then values per transaction can be be calculated in the following way:
value per transaction =
( value from the Log Transaction API in thread 1 - value from the Start Transaction API )
+ ( value from the End Transaction API - value from the Log Transaction API in thread 2 )
Collection Services does not collect additional system performance counters for the *USRTNS category. However, Collection Services collects many types of performance data for other performance categories. By joining records from the QAPMUSRTNS file with records from other performance database files produced for the same collection interval, one can calculate average resource consumption for transactions of different types.
The QMUDTA field has a common header. The following APIs use this header:
| Offset | Type | Field | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Dec | Hex | ||||||||||
| 0 | 0 | CHAR(4) | "API " eye catcher | ||||||||
| 4 | 4 | CHAR(20) | Application identifier | ||||||||
| 24 | 18 | CHAR(1) | Type of data:
|
||||||||
After the common header, the QMUDTA field has the following format for the Start Transaction, End Transaction, and Log Transaction APIs:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 25 | 19 | CHAR(10) | Transaction identifier |
| 35 | 23 | CHAR(1) | Reserved |
| 36 | 24 | BINARY(4) UNSIGNED | Length of application trace data |
| 40 | 28 | CHAR(*) | Application trace data |
| Message ID | Error Message Text |
|---|---|
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C3C E | Value for parameter &1 is not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
[ Back to top | Performance Management APIs | APIs by category ]