ibm-information-center/dist/eclipse/plugins/i5OS.ic.cl_5.4.0.1/strcmtctl.htm

396 lines
17 KiB
HTML
Raw Normal View History

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">
<title>Start Commitment Control (STRCMTCTL)</title>
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body bgcolor="white">
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<a name="STRCMTCTL.Top_Of_Page"></a>
<h2>Start Commitment Control (STRCMTCTL)</h2>
<table width="100%">
<tr>
<td valign="top" align="left"><b>Where allowed to run: </b>All environments (*ALL)<br>
<b>Threadsafe: </b>Yes
</td>
<td valign="top" align="right">
<a href="#STRCMTCTL.PARAMETERS.TABLE">Parameters</a><br>
<a href="#STRCMTCTL.COMMAND.EXAMPLES">Examples</a><br>
<a href="#STRCMTCTL.ERROR.MESSAGES">Error messages</a></td>
</tr>
</table>
<div> <a name="STRCMTCTL"></a>
<p>The Start Commitment Control (STRCMTCTL) command is used to establish either a job level or activation group level commitment definition. The job's current name space determines which IASP the commitment definition is created in, and only files in that same ASP can be opened under commitment control for this commitment definition.
</p>
<p>This command also specifies the level of record locking that occurs for the commitment definition to be started. Also, a notify object can be specified.
</p>
<p>Before a commitment definition is established, the user must ensure that all database files that are to be opened under commitment control for a single commitment transaction are journaled. If only the after images are being journaled, the system implicitly begins journaling both the before and the after images for the duration of the changes being made to files opened under this commitment definition.
</p>
<p>A default journal can be specified. Entries that describe all journals and systems involved in a commitment control operation can be placed in this journal.
</p>
<p>More information on the use of journal management is in the "Journal management" article in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter. More information on commitment control is in the "Commitment control" article in the Information Center.
</p>
<p><b>Restrictions:</b>
</p>
<ol>
<li>The user must have object operational and add authority to the object named on the NFYOBJ parameter, if an object is specified.
</li>
<li>The user must have object operational and add authority to the object named on the DFTJRN parameter, if an object is specified.
</li>
</ol>
</div>
<table width="100%">
<tr><td align="right"><a href="#STRCMTCTL.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div>
<h3><a name="STRCMTCTL.PARAMETERS.TABLE">Parameters</a></h3>
<table border="1" cellpadding="4" cellspacing="0">
<!-- col1="10" col2="15" col3="30" col4="10" -->
<tr>
<th bgcolor="aqua" valign="bottom" align="left">Keyword</th>
<th bgcolor="aqua" valign="bottom" align="left">Description</th>
<th bgcolor="aqua" valign="bottom" align="left">Choices</th>
<th bgcolor="aqua" valign="bottom" align="left">Notes</th>
</tr>
<tr>
<td valign="top"><a href="#STRCMTCTL.LCKLVL"><b>LCKLVL</b></a></td>
<td valign="top">Lock level</td>
<td valign="top">*CHG, *CS, *ALL</td>
<td valign="top">Required, Positional 1</td>
</tr>
<tr>
<td valign="top" rowspan="7"><a href="#STRCMTCTL.NFYOBJ"><b>NFYOBJ</b></a></td>
<td valign="top">Notify object</td>
<td valign="top">Single values: <b><u>*NONE</u></b><br>Other values: <i>Element list</i></td>
<td valign="top" rowspan="7">Optional, Positional 2</td>
</tr>
<tr>
<td valign="top">Element 1: Object</td>
<td valign="top">
<i>Qualified object name</i></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Qualifier 1: Object</td>
<td valign="top"><i>Name</i></td>
</tr><tr>
<td valign="top" style="padding-left:10pt">Qualifier 2: Library</td>
<td valign="top"><i>Name</i>, <b><u>*LIBL</u></b>, *CURLIB</td>
</tr><tr>
<td valign="top">Element 2: Object type</td>
<td valign="top">
Single values: *MSGQ, *DTAARA<br>Other values: <i>Element list</i></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Element 1: (*MSGQ *DTAARA or *FILE)</td>
<td valign="top">
*FILE</td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Element 2: Member, if *FILE</td>
<td valign="top">
<i>Name</i>, <b><u>*FIRST</u></b></td>
</tr>
<tr>
<td valign="top"><a href="#STRCMTCTL.CMTSCOPE"><b>CMTSCOPE</b></a></td>
<td valign="top">Commitment definition scope</td>
<td valign="top"><b><u>*ACTGRP</u></b>, *JOB</td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#STRCMTCTL.TEXT"><b>TEXT</b></a></td>
<td valign="top">Text 'description'</td>
<td valign="top"><i>Character value</i>, <b><u>*DFTTEXT</u></b></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top" rowspan="3"><a href="#STRCMTCTL.DFTJRN"><b>DFTJRN</b></a></td>
<td valign="top">Journal</td>
<td valign="top">Single values: <b><u>*NONE</u></b><br>Other values: <i>Qualified object name</i></td>
<td valign="top" rowspan="3">Optional</td>
</tr>
<tr>
<td valign="top">Qualifier 1: Journal</td>
<td valign="top"><i>Name</i></td>
</tr><tr>
<td valign="top">Qualifier 2: Library</td>
<td valign="top"><i>Name</i>, <b><u>*LIBL</u></b>, *CURLIB</td>
</tr><tr>
<td valign="top"><a href="#STRCMTCTL.OMTJRNE"><b>OMTJRNE</b></a></td>
<td valign="top">Journal entries to be omitted</td>
<td valign="top"><b><u>*NONE</u></b>, *LUWID</td>
<td valign="top">Optional</td>
</tr>
</table>
<table width="100%">
<tr><td align="right"><a href="#STRCMTCTL.Top_Of_Page">Top</a></td></tr>
</table>
</div>
<div> <a name="STRCMTCTL.LCKLVL"></a>
<h3>Lock level (LCKLVL)</h3>
<p>Specifies the default level of record locking that occurs for the commitment definition to be started.
</p>
<p>This is a required parameter.
</p>
<dl>
<dt><b>*CHG</b></dt>
<dd>Every record read for update (for a file opened under commitment control) is locked. If a record is changed, added, or deleted, that record remains locked until the transaction is committed or rolled back. Records that are accessed for update operations but are released without being changed are unlocked.
</dd>
<dt><b>*CS</b></dt>
<dd>Every record accessed for files opened under commitment control is locked. A record that is read, but not changed or deleted, is unlocked when a different record is read. Records that are changed, added, or deleted are locked until the transaction is committed or rolled back.
</dd>
<dt><b>*ALL</b></dt>
<dd>Every record accessed for files opened under commitment control is locked until the transaction is committed or rolled back.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#STRCMTCTL.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="STRCMTCTL.NFYOBJ"></a>
<h3>Notify object (NFYOBJ)</h3>
<p>Specifies the name and type of the object where notification is sent regarding the status of a transaction for a commitment definition. The commitment identifier of the last successful commit operation is sent to the notify object only for the following conditions:
</p>
<ul>
<li>For a job level commitment definition, if any of the following are true:
<ul>
<li>A system failure occurs
</li>
<li>The job ends with uncommitted changes
</li>
<li>The job ends with a nonzero completion code
</li>
</ul>
</li>
<li>For an activation group level commitment definition, if any of the following are true:
<ul>
<li>A system failure occurs
</li>
<li>The job ends with uncommitted changes
</li>
<li>The job ends with a nonzero completion code
</li>
<li>The activation group ends abnormally
</li>
<li>The activation group ends with uncommitted changes and the uncommitted changes are rolled back
</li>
</ul>
</li>
</ul>
<p>For a system failure, the commitment identifier is placed in the notify object after the next successful initial program load (IPL). For a job that ends with uncommitted changes or with a nonzero completion code, the commitment identifier is placed in the notify object during end job processing. For an activation group that ends with uncommitted changes or ends abnormally, the notification text is placed in the notify object during activation group end processing.
</p>
<p>A commitment identifier (specified for the <b>Commit identification (CMTID)</b> parameter on the Commit (COMMIT) command) can be specified on each commit operation performed for a commitment definition. If more than one job is concurrently using commitment control or there is more than one commitment definition being used concurrently within a single job, then each commitment definition for each job should use a unique notify object or the specified commit identifier should contain unique text such that the text identifies a single commitment definition for a single job. If *NONE is specified for the CMTID parameter of the Commit (COMMIT) command, this entry is ignored.
</p>
<dl>
<dt><b><u>*NONE</u></b></dt>
<dd>No notification is sent after an abnormal system or process end.
</dd>
<dt><b><i>object-name</i></b></dt>
<dd>Specify the name (library-name/object-name) of the object to receive notification of the last transaction that is successfully committed. You must have correct authority for the object specified.
</dd>
</dl>
<p>The possible library values are:
</p>
<dl>
<dt><b><u>*LIBL</u></b></dt>
<dd>All libraries in the library list for the current thread are searched until the first match is found.
</dd>
</dl>
<dl>
<dt><b>*CURLIB</b></dt>
<dd>The current library for the job is used to locate the object. If no library is specified as the current library for the job, the QGPL library is used.
</dd>
<dt><b><i>library-name</i></b></dt>
<dd>Specify the library where the object is located.
</dd>
</dl>
<p>The possible object type values are:
</p>
<dl>
<dt><b>*MSGQ</b></dt>
<dd>The text identifying the last commitment boundary is placed on the specified message queue.
</dd>
<dt><b>*DTAARA</b></dt>
<dd>The text identifying the last commitment boundary is placed in the specified data area. The data area specified must be of type character, and unique to this job. The text is padded or truncated to fit the data area.
</dd>
<dt><b>*FILE</b></dt>
<dd>The text identifying the last commitment boundary is added to the specified physical file.
</dd>
</dl>
<p>The possible physical file member values are:
</p>
<dl>
<dt><b>*FIRST</b></dt>
<dd>The first member of the physical file receives the notification.
</dd>
<dt><b><i>member-name</i></b></dt>
<dd>Specify the name of the member of the physical file that receives the notification.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#STRCMTCTL.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="STRCMTCTL.CMTSCOPE"></a>
<h3>Commitment definition scope (CMTSCOPE)</h3>
<p>Specifies the scope for the commitment definition to be started.
</p>
<dl>
<dt><b><u>*ACTGRP</u></b></dt>
<dd>An activation-group-level commitment definition is started for the activation group associated with the program issuing the command.
</dd>
<dt><b>*JOB</b></dt>
<dd>The job-level commitment definition is started for the job.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#STRCMTCTL.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="STRCMTCTL.TEXT"></a>
<h3>Text 'description' (TEXT)</h3>
<p>Specifies text that briefly describes the commitment definition to be started. More information on this parameter is in the CL Reference book, Appendix A.
</p>
<dl>
<dt><b><u>*DFTTEXT</u></b></dt>
<dd>The system is to provide a default text description for the commitment definition.
</dd>
<dt><b><i>'description'</i></b></dt>
<dd>Specify no more than 50 characters of text, enclosed in apostrophes.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#STRCMTCTL.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="STRCMTCTL.DFTJRN"></a>
<h3>Journal (DFTJRN)</h3>
<p>Specifies the default journal. The default journal contains entries identifying each of the resources involved in a unit of work. Entries can also be placed when each unit of work starts or ends due to a commit or rollback operation, depending on the OMTJRNE parameter value.
</p>
<p>See the Backup and Recovery book, SC41-5304 for information on how the system performs the rollback operation under commitment control.
</p>
<p>The default journal can be used when adding a resource through the Add Committable Resource (QTNADDCR) Application Program Interface (API). If the special value *DFTJRN is specified for the journal name when calling the API, the name specified on this DFTJRN parameter is used.
</p>
<dl>
<dt><b><u>*NONE</u></b></dt>
<dd>No default journal is specified.
</dd>
</dl>
<p>The name of the default journal can be qualified by one of the following values:
</p>
<dl>
<dt><b><u>*LIBL</u></b></dt>
<dd>All libraries in the library list for the current thread are searched until the first match is found.
</dd>
</dl>
<dl>
<dt><b>*CURLIB</b></dt>
<dd>The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.
</dd>
<dt><b><i>library-name</i></b></dt>
<dd>Specify the name of the library to be searched.
</dd>
<dt><b><i>journal-name</i></b></dt>
<dd>Specify the name of the default journal.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#STRCMTCTL.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="STRCMTCTL.OMTJRNE"></a>
<h3>Journal entries to be omitted (OMTJRNE)</h3>
<p>Specifies the journal entries to omit from the default journal. If *NONE is specified on the DFTJRN parameter, this parameter is ignored.
</p>
<dl>
<dt><b><u>*NONE</u></b></dt>
<dd>No journal entries are omitted.
</dd>
<dt><b>*LUWID</b></dt>
<dd>The journal entry that contains the Logical Unit of Work Identifier (LUWID) and all the resources involved in the logical unit of work are omitted if the logical unit of work is committed or rolled back successfully. If an error occurs while committing or rolling back the logical unit of work, the entry will always be sent regardless of this value.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#STRCMTCTL.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="STRCMTCTL.COMMAND.EXAMPLES">Examples</a> </h3>
<p><b>Example 1: Defining Activation Group Level Commitment Control</b>
</p>
<p>
<pre>
STRCMTCTL LCKLVL(*CHG) CMTSCOPE(*ACTGRP) TEXT('Blue Commit Group')
</pre>
</p>
<p>This command described by the user as the Blue Commit Group starts the activation group level commitment for the activation group associated with the program issuing the command.
</p>
<p>Only records that are updated, inserted, or deleted are locked until the transaction is ended by a commit or rollback operation. No identification for the commitment boundary is sent after the initial program load (IPL) following an abnormal system end, after an abnormal end to an activation group for the job, or when the job or activation group ends either with uncommitted changes or with a nonzero completion code.
</p>
<p><b>Example 2: Defining Job Level Commitment Control</b>
</p>
<p>
<pre>
STRCMTCTL LCKLVL(*ALL) NFYOBJ(RCVLIB/MYFILE *FILE IDSAVE)
CMTSCOPE(*JOB) DFTJRN(MGWLIB/MYJRN)
</pre>
</p>
<p>This command starts the job level commitment definition. All records accessed in files opened under commitment control are locked until the commitment transaction is ended by a commit or rollback operation. If a commitment transaction ends in a manner that a notify object is to be updated with the commitment identifier of the last successful commit operation, the notify object to be updated is member IDSAVE of file MYFILE in the library RCVLIB. When a commit or rollback is done, an entry that lists information about all the resources involved in the logical unit of work is put into journal MYJRN in library MGWLIB.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#STRCMTCTL.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="STRCMTCTL.ERROR.MESSAGES">Error messages</a> </h3>
<p><b><u>*ESCAPE Messages</u></b>
</p>
<dl>
<dt><b>CPF8351</b></dt>
<dd>Commitment control already active.
</dd>
<dt><b>CPF8352</b></dt>
<dd>Attribute in notify object &amp;1 type *&amp;4 not valid.
</dd>
<dt><b>CPF8360</b></dt>
<dd>Not enough storage for commitment control operation.
</dd>
<dt><b>CPF8366</b></dt>
<dd>Commitment definition &amp;2 not created. Reason code &amp;1.
</dd>
<dt><b>CPF9801</b></dt>
<dd>Object &amp;2 in library &amp;3 not found.
</dd>
<dt><b>CPF9802</b></dt>
<dd>Not authorized to object &amp;2 in &amp;3.
</dd>
<dt><b>CPF9807</b></dt>
<dd>One or more libraries in library list deleted.
</dd>
<dt><b>CPF9808</b></dt>
<dd>Cannot allocate one or more libraries on library list.
</dd>
<dt><b>CPF9810</b></dt>
<dd>Library &amp;1 not found.
</dd>
<dt><b>CPF9815</b></dt>
<dd>Member &amp;5 file &amp;2 in library &amp;3 not found.
</dd>
<dt><b>CPF9820</b></dt>
<dd>Not authorized to use library &amp;1.
</dd>
<dt><b>CPF9830</b></dt>
<dd>Cannot assign library &amp;1.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#STRCMTCTL.Top_Of_Page">Top</a></td></tr>
</table>
</body>
</html>