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:

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:

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:
0 Generic trace point
1 Start of transaction
2 End of transaction
3 Log transaction

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 ]