friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/QTNRCMTI.htm

813 lines
23 KiB
HTML
Raw Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<!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>Retrieve Commitment Information (QTNRCMTI) 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. -->
<!-- JC1 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited by Kersten Oct 2001 -->
<!--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>Retrieve Commitment Information (QTNRCMTI) API</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;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="50%">Receiver variable</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Length of receiver variable</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Format name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/0</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve Commitment Information (QTNRCMTI) API allows you to determine
if commitment control is active within the activation group for the program
performing the retrieve request. Other information that can be retrieved
includes:</p>
<ul>
<li>Default lock level and default journal name and library</li>
<li>Commitment definition scope</li>
<li>Activation group commitment definition status</li>
<li>Commitment options</li>
<li>Logical unit of work identifier</li>
</ul>
<p>Information about commitment definitions that are started by the system for
system use only is not available through this API.</p>
<br>
<!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. -->
<!-- Instead, use the commented out coding below to indicate NONE. -->
<h3>Authorities and Locks</h3>
<!-- Use this if there are no authorities and locks. -->
<p>None.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The receiver variable that is to receive the information requested. You can
specify the size of the area smaller than the format requested as long as you
specify the receiver variable length parameter correctly. As a result, the API
returns only the data the area can hold.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable. The length must be at least 8 bytes. If
the variable is not long enough to hold the information, the data is truncated.
If the length is larger than the size of the receiver variable, the results are
not predictable.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format name CMTI0100 is the only valid format name used by this API. For
more information, see <a href="#HDRRTVCIF1">CMTI0100 Format</a>.</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="HDRRTVCIF1">CMTI0100 Format</a></h3>
<p>The structure of the information returned is determined by the specified
format name. For detailed descriptions of the fields, see <a href=
"#HDRRTVFDES">Field Descriptions</a>.<br>
<br>
</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%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Bytes returned</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Bytes available</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Commitment definition status</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="center" valign="top">9</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Commitment definition default lock level</td>
</tr>
<tr>
<td align="center" valign="top">19</td>
<td align="center" valign="top">13</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Commitment definition scope</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Commitment definition status for the activation
group</td>
</tr>
<tr>
<td align="center" valign="top">21</td>
<td align="center" valign="top">15</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Wait for outcome commitment option</td>
</tr>
<tr>
<td align="center" valign="top">22</td>
<td align="center" valign="top">16</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Action if problems commitment option</td>
</tr>
<tr>
<td align="center" valign="top">23</td>
<td align="center" valign="top">17</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Vote read-only permitted commitment option</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">Action if ENDJOB commitment option</td>
</tr>
<tr>
<td align="center" valign="top">25</td>
<td align="center" valign="top">19</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Default journal name</td>
</tr>
<tr>
<td align="center" valign="top">35</td>
<td align="center" valign="top">23</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Default journal library name</td>
</tr>
<tr>
<td align="center" valign="top">45</td>
<td align="center" valign="top">2D</td>
<td align="left" valign="top">CHAR(39)</td>
<td align="left" valign="top">Logical unit of work identifier</td>
</tr>
<tr>
<td align="center" valign="top">84</td>
<td align="center" valign="top">54</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Last agent permitted commitment option</td>
</tr>
<tr>
<td align="center" valign="top">85</td>
<td align="center" valign="top">55</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">OK to leave out commitment option</td>
</tr>
<tr>
<td align="center" valign="top">86</td>
<td align="center" valign="top">56</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Accept vote reliable commitment option</td>
</tr>
</table>
<br>
<h3><a name="HDRRTVFDES">Field Descriptions</a></h3>
<p>For more detailed descriptions of these fields and their values, refer to <a
href="QTNCHGCO.htm#HDRCHGCOFM">Commitment Options Format</a> in the Change
Commitment Options (QTNCHGCO) API.</p>
<p><strong>Accept vote reliable commitment option.</strong> The current value
of this commitment option.</p>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>Y</em> </td>
<td valign="top">The system accepts the vote reliable indicator if it is
returned from its agents during the prepare wave of a commit operation. Control
is returned to the application before the committed wave is completed for
agents that send the vote reliable indicator if this system accepts it. If
heuristic damage is encountered during the committed wave at any agents that
voted reliable, it is not reported to the application.</td>
</tr>
<tr>
<td valign="top"><em>N</em> </td>
<td valign="top">The system does not accept the vote reliable indicator.
Control is returned to the application after the committed wave is completed
for all agents. If heuristic damage is encountered during the committed wave,
it is reported to the application as an escape message.</td>
</tr>
</table>
<br>
<p><strong>Action if ENDJOB commitment option.</strong> The current value of
this commitment option.</p>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>W</em> </td>
<td valign="top">The system waits to allow the normal processing of the logical
unit of work to complete.</td>
</tr>
<tr>
<td valign="top"><em>R</em> </td>
<td valign="top">Local resources whose status is in doubt are rolled back in
the event of an ENDJOB.</td>
</tr>
<tr>
<td valign="top"><em>C</em></td>
<td valign="top">Local resources whose status is in doubt are committed in the
event of an ENDJOB.</td>
</tr>
</table>
<br>
<p><strong>Action if problems commitment option.</strong> The current value of
this commitment option.</p>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>R</em></td>
<td valign="top">If a problem is detected and the local resources have not been
committed or rolled back, the local resources will be rolled back.</td>
</tr>
<tr>
<td valign="top"><em>C</em> </td>
<td valign="top">If a problem is detected and the local resources have not been
committed or rolled back, the local resources will be committed.</td>
</tr>
</table>
<br>
<p><strong>Bytes available.</strong> The length in bytes of all data available
to return. All available data is returned if enough space is provided.</p>
<p><strong>Bytes returned.</strong> The length in bytes of all data actually
returned.</p>
<p><strong>Commitment-definition default lock level.</strong> The default lock
level at the start of commitment control for the commitment definition. This is
the level of record locking that applies to records in all commitment resources
under commitment control for the commitment definition. The level of record
locking is this value unless it is overridden when the file is opened. You
cannot override this value; however, the system can override for files opened
for system functions.</p>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>blank</em> </td>
<td valign="top">Blanks are returned when I is returned for commitment
definition status.</td>
</tr>
<tr>
<td valign="top"><em>*ALL</em> </td>
<td valign="top">Changed and retrieved records are protected from changes by
other jobs running at the same time.</td>
</tr>
<tr>
<td valign="top"><em>*CHG</em> </td>
<td valign="top">Changed records are protected from changes by other jobs
running at the same time.</td>
</tr>
<tr>
<td valign="top"><em>*CS</em> </td>
<td valign="top">Changed and retrieved records are protected from changes by
other jobs running at the same time. Retrieved records are protected until they
are released or until a different record is retrieved.</td>
</tr>
</table>
<br>
<p><strong>Commitment definition scope.</strong> The scope for the commitment
definition currently active within the activation group for the program
performing the retrieve request.</p>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>A</em> </td>
<td valign="top">Activation group level</td>
</tr>
<tr>
<td valign="top"><em>J</em> </td>
<td valign="top">Job level</td>
</tr>
</table>
<br>
<p><strong>Commitment definition status.</strong> The overall status of the
commitment definition currently active for the activation group for the program
performing the retrieve request. The scope for this commitment definition is
returned in the commitment definition scope field.</p>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>I</em> </td>
<td valign="top">Commitment control is not active at either the activation
group level or the job level for the program making the retrieve request.</td>
</tr>
<tr>
<td valign="top"><em>A</em> </td>
<td valign="top">The commitment definition is active within the activation
group for the program performing the retrieve request. No local, remote, or API
commitment resource is associated with the commitment definition.</td>
</tr>
<tr>
<td valign="top"><em>L</em> </td>
<td valign="top">The commitment definition is active on the local system within
the activation group for the program performing the retrieve request.</td>
</tr>
<tr>
<td valign="top"></td>
<td valign="top">An <em>L</em> is returned if one or more of the following
resources are under commitment control.
<ul>
<li>Local, open database files</li>
<li>Local, closed database files with pending changes</li>
<li>Resources with object-level changes</li>
<li>Local relational database resources</li>
<li>API commitment resources</li>
</ul>
</td>
</tr>
<tr>
<td valign="top"><em>R</em> </td>
<td valign="top">The commitment definition is active on one or more remote
systems within the activation group for the program performing the retrieve
request.</td>
</tr>
<tr>
<td valign="top"></td>
<td valign="top">An <em>R</em> is returned if one or more of the following
resources are under commitment control.
<ul>
<li>Remote DDM resources</li>
<li>Remote distributed relational database resources</li>
<li>Protected conversations</li>
</ul>
</td>
</tr>
<tr>
<td valign="top"><em>B</em> </td>
<td valign="top">The commitment definition is active on both the local and one
or more remote systems.</td>
</tr>
<tr>
<td valign="top"></td>
<td valign="top">If both <em>L</em> and <em>R</em> could be returned, a
<em>B</em> will be returned.</td>
</tr>
</table>
<br>
<p><strong>Commitment definition status for the activation group.</strong> The
status of the commitment definition currently active for the activation group
for the program performing the retrieve request, but specifically regarding any
commitment resource changes made by programs running within the activation
group.</p>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>I</em> </td>
<td valign="top">Commitment control is not active at the activation group level
or the job level for the program making the retrieve request. The overall
status for the job-level commitment definition is also not active.</td>
</tr>
<tr>
<td valign="top"><em>A</em> </td>
<td valign="top">The commitment definition is currently being used by one or
more programs running within this activation group. Local, remote or API
commitment resources may have been placed under commitment control to the
commitment definition by a program running within the activation group. The
overall status for the commitment definition is either active (A), active on
the local system (L), active on a remote system (R), or active on both the
local and one or more remote systems (B).</td>
</tr>
<tr>
<td valign="top"><em>N</em> </td>
<td valign="top">The job-level commitment definition is active but is not in
use by any program running within this activation group. The overall status for
the commitment definition is either active (A), active on the local system (L),
active on a remote system (R), or active on both the local and one or more
remote systems (B). It is possible to start the activation-group-level
commitment definition for programs running within this activation group.</td>
</tr>
</table>
<br>
<p><strong>Default journal name.</strong> The journal name specified for the
default journal when this commitment definition was started. If no default
journal was specified, blanks are returned.</p>
<p><strong>Default journal library name.</strong> The journal library name
specified for the default journal when this commitment definition was started.
If no default journal was specified, blanks are returned.</p>
<p><strong>Last agent permitted commitment option.</strong> The current value
of this commitment option.</p>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>S</em> </td>
<td valign="top">The system is allowed to select a last agent.</td>
</tr>
<tr>
<td valign="top"><em>N</em> </td>
<td valign="top">The system is not allowed to select a last agent.</td>
</tr>
</table>
<br>
<p><strong>Logical unit of work identifier.</strong> The identifier for the
logical unit of work currently associated with this commitment definition.</p>
<br>
<p><strong><a name="TBLLUWFRMT">Table 1. Logical Unit of Work Identifier
Format</a></strong></p>
<table border width="80%">
<!-- cols="20 20 60" -->
<tr>
<th align="left" valign="top">Field</th>
<th align="left" valign="top">Type</th>
<th align="left" valign="top">Description</th>
</tr>
<tr>
<td align="left" valign="top">Network ID</td>
<td align="left" valign="top">CHAR(0-8)</td>
<td align="left" valign="top">Network identifier</td>
</tr>
<tr>
<td align="left" valign="top">Separator</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">The separator character "."</td>
</tr>
<tr>
<td align="left" valign="top">Local location name</td>
<td align="left" valign="top">CHAR(0-8)</td>
<td align="left" valign="top">The name of the local location</td>
</tr>
<tr>
<td align="left" valign="top">Separator</td>
<td align="left" valign="top">CHAR(3)</td>
<td align="left" valign="top">The separator characters ".X'"</td>
</tr>
<tr>
<td align="left" valign="top">Instance number</td>
<td align="left" valign="top">CHAR(12)</td>
<td align="left" valign="top">The hex value of the instance number converted to
decimal</td>
</tr>
<tr>
<td align="left" valign="top">Separator</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">The separator characters "'."</td>
</tr>
<tr>
<td align="left" valign="top">Sequence number</td>
<td align="left" valign="top">CHAR(5)</td>
<td align="left" valign="top">The hex value of the sequence number converted to
decimal</td>
</tr>
</table>
<br>
<p><strong>OK to leave out commitment option.</strong> The current value of
this commitment option.</p>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>Y</em> </td>
<td valign="top">If this location does not initiate the commit operation, it
may be left out of subsequent logical units of work. Control is not returned to
the application until a data flow is received from the initiator.</td>
</tr>
<tr>
<td valign="top"><em>N</em> </td>
<td valign="top">This location may not be left out of subsequent logical units
of work. Control is returned to the application immediately after the commit
operation completes.</td>
</tr>
</table>
<br>
<p><strong>Vote read-only permitted commitment option.</strong> The current
value of this commitment option.</p>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>N</em> </td>
<td valign="top">This location is not allowed to vote read-only in response to
a prepare request from a remote location.</td>
</tr>
<tr>
<td valign="top"><em>Y</em> </td>
<td valign="top">This location is allowed to vote read-only in response to a
prepare request from a remote location. Control will not be returned to the
application until data is sent from the remote location that sent the prepare
request.</td>
</tr>
</table>
<br>
<p><strong>Wait for outcome commitment option.</strong> The current value of
this commitment option.</p>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>Y</em> </td>
<td valign="top">If a remote resource failure occurs during a commit or
rollback operation, the system will not return from the operation until
resynchronization is complete.</td>
</tr>
<tr>
<td valign="top"><em>L</em> </td>
<td valign="top">Value L has the same effect as value Y when this location is
the initiator of the commit or rollback operation. When this location is not
the initiator and the initiator supports the presumed abort protocol, the Wait
for outcome value is inherited from the initiator. When this location is not
the initiator and the initiator does not support the presumed abort protocol,
value L has the same effect as value Y.</td>
</tr>
<tr>
<td valign="top"><em>N</em> </td>
<td valign="top">If a remote resource failure occurs during a commit or
rollback operation, the system will attempt to resynchronize with the failed
resource once. If the one attempt fails, resynchronization will then be done in
a system job and control is returned to the application.</td>
</tr>
<tr>
<td valign="top"><em>U</em> </td>
<td valign="top">Value U has the same effect as value N when this location is
the initiator of the commit or rollback operation. When this location is not
the initiator and the initiator supports the presumed abort protocol, the Wait
for outcome value is inherited from the initiator. When this location is not
the initiator and the initiator does not support the presumed abort protocol,
value U has the same effect as value N.</td>
</tr>
</table>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="3">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPF24B4 E</td>
<td width="85%" valign="top">Severe error while addressing parameter list.</td>
</tr>
<tr>
<td valign="top">CPF3C90 E</td>
<td valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td valign="top">CPF3CF1 E</td>
<td valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C21 E</td>
<td valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C24 E</td>
<td valign="top">Length of the receiver variable is not valid.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
API introduced: V2R2
<hr>
<table cellpadding="2" cellspacing="2" align="center">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"jc1.htm">Journal and Commit APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</body>
</html>
Reference in New Issue Copy Permalink