461 lines
16 KiB
HTML
461 lines
16 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>Start Transaction (QYPESTRT, qypeStartTransaction) API</title>
|
||
|
|
<!-- Begin Header Records ========================================== -->
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- Created for V5R2 -->
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>Start Transaction (QYPESTRT, qypeStartTransaction) API</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 80%;">
|
||
|
|
<br>
|
||
|
|
Required Parameter Group:<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
<table width="100%">
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">1</td>
|
||
|
|
<td align="left" valign="top" width="45%">Application identifier</td>
|
||
|
|
<td align="left" valign="top" width="15%">Input</td>
|
||
|
|
<td align="left" valign="top" width="30%">Char(20)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">Transaction identifier</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Binary(4) Unsigned</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">3</td>
|
||
|
|
<td align="left" valign="top">Application trace data</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">Length of application trace data</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Binary(4) Unsigned</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">5</td>
|
||
|
|
<td align="left" valign="top">Transaction start time</td>
|
||
|
|
<td align="left" valign="top">Output</td>
|
||
|
|
<td align="left" valign="top">Char(8)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">6</td>
|
||
|
|
<td align="left" valign="top">Error code</td>
|
||
|
|
<td align="left" valign="top">I/O</td>
|
||
|
|
<td align="left" valign="top">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Service Program Name: QYPESVPG<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The Start Transaction (OPM, QYPESTRT; ILE, qypeStartTransaction) API is used
|
||
|
|
together with the <a href="qypeendt.htm">End Transaction</a> (QYPEENDT,
|
||
|
|
qypeEndTransaction) API and the <a href="qypelogt.htm">Log Transaction</a>
|
||
|
|
(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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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 <a href="#USAGENOTES">
|
||
|
|
Usage notes</a>). The performance counters are written to individual fields in
|
||
|
|
the QAYPEMIUSR and QAYPETIDX files.</p>
|
||
|
|
|
||
|
|
<p>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 <a href="qypeendt.htm">End
|
||
|
|
Transaction</a> (QYPEENDT, qypeEndTransaction) API).</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>API Public Authority</em></dt>
|
||
|
|
|
||
|
|
<dd>*USE</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Required Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Application identifier</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(20)
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Transaction identifier</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4) UNSIGNED
|
||
|
|
|
||
|
|
<p>Any sort of unique transaction identifier, such as a sequential number. The
|
||
|
|
transaction identifier is not used by Collection Services.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Application trace data</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>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 <a
|
||
|
|
href="#USAGENOTES">Usage notes</a> for more information.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of application trace data</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4) UNSIGNED
|
||
|
|
|
||
|
|
<p>The length (in bytes) of user-defined data to be captured by PEX. The value
|
||
|
|
must be between 0 and 3032.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Transaction start time</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; CHAR(8)
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Error code</strong></dt>
|
||
|
|
|
||
|
|
<dd>I/O; CHAR(*)
|
||
|
|
|
||
|
|
<p>The structure in which to return error information. For the format of the
|
||
|
|
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3><a name="USAGENOTES"></a>Usage Notes</h3>
|
||
|
|
|
||
|
|
<h3>How the data is collected</h3>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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 <a href="qypeendt.htm">End Transaction</a>
|
||
|
|
(QYPEENDT, qypeEndTransaction) API).</p>
|
||
|
|
|
||
|
|
<p>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 <a href=
|
||
|
|
"../rzahx/rzahxcollectdatacs.htm">Collection Services</a> for more information
|
||
|
|
on Collection Services and performance database files.)</p>
|
||
|
|
|
||
|
|
<h3>How to use collected data</h3>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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).</p>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong>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.</p>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<blockquote><samp>value per transaction =<br>
|
||
|
|
value from the End Transaction API - value from the Start Transaction
|
||
|
|
API</samp></blockquote>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<blockquote><samp>value per transaction =<br>
|
||
|
|
( value from the Log Transaction API in thread 1 - value from the Start
|
||
|
|
Transaction API )<br>
|
||
|
|
+ ( value from the End Transaction API - value from the Log Transaction API in
|
||
|
|
thread 2 )</samp></blockquote>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<h3>The format of the QMUDTA field of the QAYPEMIUSR file</h3>
|
||
|
|
|
||
|
|
<p>The QMUDTA field has a common header. The following APIs use this
|
||
|
|
header:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="#Top_Of_Page">Start Transaction (QYPESTRT,
|
||
|
|
qypeStartTransaction)</a></li>
|
||
|
|
|
||
|
|
<li><a href="qypeendt.htm">End Transaction (QYPEENDT,
|
||
|
|
qypeEndTransaction)</a></li>
|
||
|
|
|
||
|
|
<li><a href="qypelogt.htm">Log Transaction (QYPELOGT,
|
||
|
|
qypeLogTransaction)</a></li>
|
||
|
|
|
||
|
|
<li><a href="qypeaddt.htm">Add Trace point (QYPEADDT,
|
||
|
|
qypeAddTracePoint)</a></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<table border width="80%">
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom">Dec</th>
|
||
|
|
<th align="center" valign="bottom">Hex</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
|
<td align="left" valign="top" width="20%">CHAR(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">"API " eye catcher</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">CHAR(20)</td>
|
||
|
|
<td align="left" valign="top">Application identifier</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">24</td>
|
||
|
|
<td align="center" valign="top">18</td>
|
||
|
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
|
<td align="left" valign="top">Type of data:
|
||
|
|
|
||
|
|
<table>
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
|
<td align="left" valign="top">Generic trace point</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td align="left" valign="top">Start of transaction</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
|
<td align="left" valign="top">End of transaction</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>3</em></td>
|
||
|
|
<td align="left" valign="top">Log transaction</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>After the common header, the QMUDTA field has the following format for the
|
||
|
|
Start Transaction, End Transaction, and Log Transaction APIs:</p>
|
||
|
|
|
||
|
|
<table border width="80%">
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom">Dec</th>
|
||
|
|
<th align="center" valign="bottom">Hex</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">25</td>
|
||
|
|
<td align="center" valign="top" width="10%">19</td>
|
||
|
|
<td align="left" valign="top" width="20%">CHAR(10)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Transaction identifier</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">35</td>
|
||
|
|
<td align="center" valign="top">23</td>
|
||
|
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
|
<td align="left" valign="top">Reserved</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">36</td>
|
||
|
|
<td align="center" valign="top">24</td>
|
||
|
|
<td align="left" valign="top">BINARY(4) UNSIGNED</td>
|
||
|
|
<td align="left" valign="top">Length of application trace data</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">40</td>
|
||
|
|
<td align="center" valign="top">28</td>
|
||
|
|
<td align="left" valign="top">CHAR(*)</td>
|
||
|
|
<td align="left" valign="top">Application trace data</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Message ID</th>
|
||
|
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="15%">CPF3C36 E</td>
|
||
|
|
<td align="left" valign="top" width="85%">Number of parameters, &1, entered
|
||
|
|
for this API was not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3C3C E</td>
|
||
|
|
<td align="left" valign="top">Value for parameter &1 is not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3CF2 E</td>
|
||
|
|
<td align="left" valign="top">Error(s) occurred during running of &1
|
||
|
|
API.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
API introduced: V5R2
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<table align="center" cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"perf1.htm">Performance Collector APIs</a> | <a href="aplist.htm">APIs by
|
||
|
|
category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|