Add Trace Point (QYPEADDT, qypeAddTracePoint) API
Required Parameter Group:
| 1 | Application identifier | Input | Char(20) |
| 2 | Event subtype identifier | Input | Char(10) |
| 3 | Application trace data | Input | Char(*) |
| 4 | Length of application trace data | Input | Binary(4) Unsigned |
| 5 | Error code | I/O | Char(*) |
Service Program Name: QYPESVPG
Default Public Authority: *USE
Threadsafe: Yes
The Add Trace Point (OPM, QYPEADDT; ILE, qypeAddTracePoint) API is used to record application-defined trace data.
If Performance Explorer (PEX) is running, this API generates a trace record of the type specified in the event subtype identifier parameter. 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 trace data 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.
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.
- Event subtype identifier
- INPUT; CHAR(10)
The Performance Explorer (PEX) event subtype to be used for the trace record. Allowed values for this parameter are:
- *APPEVT1
- *APPEVT2
- *APPEVT3
- *APPEVT4
To configure PEX to collect data generated by this API, use the same event subtype identifier on the application events (APPEVT) parameter of the Add PEX Definition (ADDPEXDFN) command.
- 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 trace record. The data can be up to 3042 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 3042.
- 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
Application-defined trace data is reported in the QMUDTA field of the QAYPEMIUSR file.
The format of the QMUDTA field of the QAYPEMIUSR file is described below.
The QMUDTA field has a common header. The following APIs use this header:
- Start Transaction (QYPESTRT, qypeStartTransaction)
- End Transaction (QYPEENDT, qypeEndTransaction)
- Log Transaction (QYPELOGT, qypeLogTransaction)
- Add Trace point (QYPEADDT, qypeAddTracePoint)
| 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 Add Trace Point API:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 25 | 19 | CHAR(1) | Reserved |
| 26 | 1A | BINARY(4) UNSIGNED | Length of application trace data |
| 30 | 1E | CHAR(*) | Application trace data |
Error Messages
| 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. |
API introduced: V5R2
[ Back to top | Performance Management APIs | APIs by category ]