File integrity and recovery: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
 
(42 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<div class="toclimit-3">
==Overview==
==Overview==
<p>After files have been designed and loaded, one of the file manager's most important responsibilities is to maintain the integrity of the files. This chapter describes some of the error conditions that threaten file structures and the steps that you can take to safeguard the files.    </p>
<p>
After files have been designed and loaded, one of the file manager's most important responsibilities is to maintain the integrity of the files. This topic describes some of the error conditions that threaten file structures and the steps that you can take to safeguard the files.    </p>
 
==Error recovery features==
==Error recovery features==
<p><var class="product">Model&nbsp;204</var> provides many features to ensure the data integrity, including:</p>
<p>
<var class="product">Model&nbsp;204</var> provides many features to ensure the data integrity, including:</p>
<ul>
<ul>
<li>Extensive command syntax checking and compiler diagnostics.</li>
<li>Extensive command syntax checking and compiler diagnostics.</li>
<li>Double-checking of files and tape backups to ensure that files are correctly mounted.</li>
<li>Double-checking of files and tape backups to ensure that files are correctly mounted.</li>
<li>SNA Communications Server (formerly VTAM) error recovery routines for data transmission from user terminals. </li>
<li>SNA Communications Server (formerly VTAM) error recovery routines for data transmission from user terminals. </li>
<li>Trailers on each page with information such as file name, page number, and table number, which <var class="product">Model&nbsp;204</var> checks every time the page is read or written to protect against loss of integrity due to a disk error.</li>
<li>Trailers on each page with information such as file name, page number, and table number, which <var class="product">Model&nbsp;204</var> checks every time the page is read or written to protect against loss of integrity due to a disk error.</li>
</ul>
</ul>
<p>In addition, <var class="product">Model&nbsp;204</var> provides error recovery facilities as described in the following sections.</p>
<p>
===Transaction Back Out facility===
In addition, <var class="product">Model&nbsp;204</var> provides error recovery facilities as described in the following sections.</p>
<p>Data integrity and logical consistency of the files are protected by the <var class="product">Model&nbsp;204</var> Transaction Back Out facility, which can undo the effects of incomplete transactions on file data. <var class="product">Model&nbsp;204</var> automatically backs out an incomplete transaction for a transaction back out file if a user's request is canceled, if <var class="product">Model&nbsp;204</var> detects a file problem such as a table full condition, or if <var class="product">Model&nbsp;204</var> is restarting the user. See the Transaction Backout chapter for details.  </p>
 
===RESTART Recovery facility===
===Transaction back out facility===
<p>The system manager must include a RESTART command as part of User 0's input if an installation is to use system recovery facilities. The Rocket <var class="product">Model&nbsp;204</var> System Manager's Guide discusses the syntax of this command and describes ROLL BACK and ROLL FORWARD features. </p>
<p>
Data integrity and logical consistency of the files are protected by the <var class="product">Model&nbsp;204</var> Transaction back out facility, which can undo the effects of incomplete transactions on file data. <var class="product">Model&nbsp;204</var> automatically backs out an incomplete transaction for a transaction back out file if a user's request is canceled, if <var class="product">Model&nbsp;204</var> detects a file problem such as a table full condition, or if <var class="product">Model&nbsp;204</var> is restarting the user.
See [[Transaction back out]] for details.  </p>
===RESTART recovery facility===
<p>
The system manager must include a RESTART command as part of User 0's input if an installation is to use system recovery facilities.
The <var>[[RESTART command|RESTART]]</var> command and [[System and media recovery]] pages discuss the syntax of this command and describe the Roll Back, Roll Forward, and Ignore features. </p>
 
===Media recovery===
===Media recovery===
<p>In the event of a media failure, such as a disk head crash, <var class="product">Model&nbsp;204</var> allows you to recover files using the media recovery feature. Media recovery works by restoring files from a previously made backup copy, and then using the roll forward feature to reapply the updates that were made to the files since the time the copy was made. </p>
<p>
<b>Note</b>
In the event of a media failure, such as a disk head crash, <var class="product">Model&nbsp;204</var> allows you to recover files using the media recovery feature. Media recovery works by restoring files from a previously made backup copy, and then using the Roll Forward feature to reapply the updates that were made to the files since the time the copy was made. </p>
<p>The REGENERATE command invokes the restore and roll forward facilities automatically. In a media recovery run, the RESTORE and RESTART commands are not specified.    </p>
<p class="note"><b>Note:</b>
==FRCVOPT and FOPT parameters==
The <var>[[REGENERATE command|REGENERATE]]</var> command invokes the Restore and Roll Forward facilities automatically. In a media recovery run, the RESTORE and RESTART commands are not specified.    </p>
<p>The FRCVOPT parameter determines whether or not an installation logs checkpoint and/or Roll Forward information. The system manager also must include the RESTART command in a <var class="product">Model&nbsp;204</var> job in order for recovery to run. If an installation uses the system recovery facilities, the file manager can control how files are affected.    </p>
<p>The default setting of FRCVOPT is X'00'. The file participates in checkpointing, and batch <var class="product">Model&nbsp;204</var> jobs that update the file can be run while the Online job is up. If your installation uses Roll Forward, the file participates. The back out mechanism of transaction back out is enabled. If FOPT is also set to X'00' (enabling lock pending updates), the file is a transaction back out file. If the FOPT setting includes the X'02' option, <var class="product">Model&nbsp;204</var> automatically disables transaction back out by turning on the X'08' bit of FRCVOPT.    </p>
==<b id="frcvAndFOpts"></b>FRCVOPT and FOPT parameters==
<p>
The <var>[[FRCVOPT parameter|FRCVOPT]]</var> (file recovery options) parameter determines whether or not an installation logs checkpoint and/or Roll Forward information. The system manager also must include the <var>[[RESTART command|RESTART]]</var> command in a <var class="product">Model&nbsp;204</var> job in order for recovery to run. If an installation uses the system recovery facilities, the file manager can control how files are affected.    </p>
<p>
The default setting of FRCVOPT is X'00'. The file participates in checkpointing, and batch <var class="product">Model&nbsp;204</var> jobs that update the file can be run while the Online job is up. If your installation uses Roll Forward, the file participates. The back out mechanism of transaction back out is enabled. </p>
<p>
If the <var>[[FOPT parameter|FOPT]]</var> parameter is also set to X'00' (enabling lock pending updates), the file is a transaction back out file. If the FOPT setting includes the X'02' option, disabling lock pending updates, <var class="product">Model&nbsp;204</var> automatically disables transaction back out by turning on the X'08' bit of FRCVOPT.    </p>
 
===FRCVOPT parameter===
===FRCVOPT parameter===
<p>File recovery options are controlled by the FRCVOPT parameter. The possible FRCVOPT settings are: </p>
<p>
File recovery options are controlled by the FRCVOPT parameter. The possible FRCVOPT settings are: </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 28: Line 52:
<th>Meaning</th>
<th>Meaning</th>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'80'</td>
<td align="right"> X'80'</td>
<td>File cannot be updated if Roll Forward logging is not active. </td>
<td>File cannot be updated if Roll Forward logging is not active. </td>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'40'</td>
<td align="right"> X'40'</td>
<td>File cannot be updated if checkpoint logging is not active. </td>
<td>File cannot be updated if checkpoint logging is not active. </td>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'20'</td>
<td align="right"> X'20'</td>
<td>File does not participate in checkpoint logging.</td>
<td>File does not participate in checkpoint logging.</td>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'10'</td>
<td align="right"> X'10'</td>
<td>Discontinuities not allowed (hold enqueuing while file is closed if the file has been updated in this run).</td>
<td>Discontinuities not allowed (hold enqueuing while file is closed if the file has been updated in this run).</td>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'08'</td>
<td align="right"> X'08'</td>
<td>Transaction back out is disabled. If X'01' is specified, this option is automatically set. </td>
<td>Transaction back out is disabled. If X'01' is specified, this option is automatically set. </td>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'04'</td>
<td align="right"> X'04'</td>
<td>File does not participate in Roll Forward logging.</td>
<td>File does not participate in Roll Forward logging.</td>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'02'</td>
<td align="right"> X'02'</td>
<td>File does not participate in Roll Forward logging.</td>
<td>File does not participate in Roll Forward logging.</td>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'01'</td>
<td align="right"> X'01'</td>
<td>All updates are reapplied to the file during Roll Forward, without regard to update unit boundaries. Because transactions are explicitly handled differently between transaction back out (X'08' off) and roll-forward-all-the-way (X'01' on), this option forces the X'08' option; that is, transaction back out is automatically turned off.  </td>
<td>All updates are reapplied to the file during Roll Forward, without regard to update unit boundaries. Because transactions are explicitly handled differently between transaction back out (X'08' off) and Roll Forward all the way (X'01' on), this option forces the X'08' option; that is, transaction back out is automatically turned off.  </td>
</tr>
</tr>
</table>
</table>
===Eliminating checkpoints and roll forward logging===
 
<p>You can eliminate the overhead of checkpoint and Roll Forward logging if system crashes are infrequent and if manual backup facilities provide sufficient protection. To do this, turn on the X'24' bits of FRCVOPT. This strategy also works well for scratch files.</p>
===Eliminating checkpoints and Roll Forward logging===
<p>
You can eliminate the overhead of checkpoint and Roll Forward logging if system crashes are infrequent and if manual backup facilities provide sufficient protection. To do this, turn on the X'24' bits of FRCVOPT. This strategy also works well for scratch files.</p>
 
===Logging all changes===
===Logging all changes===
<p>At the other extreme, you might want to log all changes for recovery purposes. You can enforce this by setting the X'C0' bits of FRCVOPT. OPEN turns off all updating if logging is not active. The X'80' and X'40' bits are ignored if the OPEN command or statement is issued by User 0 and the file privileges include file manager. This override capability is designed to allow you to run batch update jobs, such as the File Load utility, without the overhead of logging.</p>
<p>
At the other extreme, you might want to log all changes for recovery purposes. You can enforce this by setting the X'C0' bits of FRCVOPT. OPEN turns off all updating if logging is not active. The X'80' and X'40' bits are ignored if the OPEN command or statement is issued by User 0 and the file privileges include file manager. This override capability is designed to allow you to run batch update jobs, such as the File Load utility, without the overhead of logging.</p>
 
===Setting and clearing the X'10' bit===
===Setting and clearing the X'10' bit===
<p>The X'10' bit (discontinuities not allowed) is somewhat independent of the recovery facilities, although preventing discontinuities is less important when checkpointing is not being used. After the file has been updated, if the X'10' bit is set, <var class="product">Model&nbsp;204</var> retains a share enqueue for the file, even if all users have closed the file. A separate retrieval job runs, but an updating job waits. To allow a specific job to run, clear the X'10' bit of FRCVOPT and then close the file. If no other users have the file open, the batch job runs. After the batch job has finished, set the X'10' bit again.            </p>
<p>
===FOPT parameter===
The FRCVOPT X'10' bit (discontinuities not allowed) is somewhat independent of the recovery facilities, although preventing discontinuities is less important when checkpointing is not being used. After the file has been updated, if the X'10' bit is set, <var class="product">Model&nbsp;204</var> retains a share enqueue for the file, even if all users have closed the file. A separate retrieval job runs, but an updating job waits.</p>
<p>The valid settings of FOPT are (options can be summed): </p>
<p>
<table>
To allow a specific job to run, clear the X'10' bit of FRCVOPT and then close the file. If no other users have the file open, the batch job runs. After the batch job has finished, set the X'10' bit again.</p>
<tr class="head">
 
<th>Setting</th>
<th>Meaning</th>
</tr>
<tr>
<td align="right">X'80'</td>
<td>Prohibits statement numbers in procedures.</td>
</tr>
<tr>
<td align="right">X'40'</td>
<td>Prohibits statement labels in procedures. </td>
</tr>
<tr>
<td align="right">X'08'</td>
<td>Indicates append-first mode in an RDFS file. Without the X'08' option, an RDFS file is in reuse-first mode. The FILEORG parameter contains option 4. Option X'08' is ignored in Release 9.0 and later releases.</td>
</tr>
<tr>
<td align="right">X'02'</td>
<td>Disables lock pending updates. <var class="product">Model&nbsp;204</var> automatically disables transaction back out by turning on the X'08' bit of the FRCVOPT parameter. The X'02' bit of the FOPT parameter and the X'08' bit of the FRCVOPT parameter for a file must be turned off to activate the transaction back out facility.</td>
</tr>
<tr>
<td align="right"> X'01'</td>
<td>Prevents the definition of new field names by users other than the file manager.</td>
</tr>
<tr>
<td align="right"> X'00'</td>
<td>Allows labels and statement numbers in the same file.</td>
</tr>
</table>
<b>Note</b>
<p>When a file is opened, bits that are not currently defined by Rocket Software for FOPT are reset. This bit resetting permits the possible use of these bits by features to be introduced in future <var class="product">Model&nbsp;204</var> releases. Version 2.1.0 and later releases prohibit the use of the RESET command to set bits that are currently undefined by Rocket Software.</p>
<p>If an application uses any of the undefined bits of the FOPT parameter, it might produce unexpected results when run under Version 2.1.0 or later releases.    </p>
<p>For a more complete discussion of the FOPT parameter, see the <var class="product">Model&nbsp;204</var> Parameter and Command Reference. </p>
===Crash recovery features===
===Crash recovery features===
<p>In case of failure, <var class="product">Model&nbsp;204</var> makes every effort to clean up files and shut down softly. If <var class="product">Model&nbsp;204</var> or the operating system under which it is running crashes, any <var class="product">Model&nbsp;204</var> file being updated is flagged by a special setting of the FISTAT parameter described in [[#FISTAT parameter|FISTAT parameter]]. The FILE PHYSICALLY INCONSISTENT message is issued whenever the file is opened thereafter until recovery procedures have been executed. In this case, or in the case of a hard crash, integrity can be recovered using the DUMP/RESTORE utility or restart/recovery facility.    </p>
<p>
In case of failure, <var class="product">Model&nbsp;204</var> makes every effort to clean up files and shut down softly. If <var class="product">Model&nbsp;204</var> or the operating system under which it is running crashes, any <var class="product">Model&nbsp;204</var> file being updated is flagged by a special setting of the <var>[[FISTAT parameter|FISTAT]]</var> parameter. The FILE PHYSICALLY INCONSISTENT message is issued whenever the file is opened thereafter until recovery procedures have been executed. In this case, or in the case of a hard crash, integrity can be recovered using the DUMP/RESTORE utility or restart/recovery facility.    </p>
 
==FISTAT parameter==
==FISTAT parameter==
<p>FISTAT is a flag parameter that provides control of update completion and other file status information. Generally, the meaning of the FISTAT setting and the actual state of the file determine any special action to be taken. </p>
<p>
<p>It is important to understand the different types of errors that can occur during processing, the effect each error has on the file and the setting of FISTAT, and the separation of updates into "update units."    </p>
FISTAT is a flag parameter that provides control of update completion and other file status information. Generally, the meaning of the FISTAT setting and the actual state of the file determine any special action to be taken. </p>
<p>The possible settings of FISTAT are:  </p>
<p>
It is important to understand the different types of errors that can occur during processing, the effect each error has on the file and the setting of FISTAT, and the separation of updates into "update units."    </p>
<p>
The possible settings of FISTAT are:  </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 114: Line 124:
<th>Meaning</th>
<th>Meaning</th>
</tr>
</tr>
<tr>
<tr>
<td align="right">X'40'</td>
<td align="right">X'40'</td>
<td>File might be logically inconsistent. (Soft restart might have occurred.) Logical inconsistencies are described in more detail in [[#Logically inconsistent files|Logically inconsistent files]].</td>
<td>File might be logically inconsistent. (Soft restart might have occurred.) Logical inconsistencies are described in more detail in [[#Logically inconsistent files|Logically inconsistent files]].</td>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'20'</td>
<td align="right"> X'20'</td>
<td>File is in deferred update mode. Either a file load program or an OPEN in deferred update mode was applied to the file, and the Z command has not yet been issued. See the deferred updates chapter for more information about deferred update mode. </td>
<td>File is in deferred update mode. Either a file load program or an OPEN in deferred update mode was applied to the file, and the Z command has not yet been issued.
See [[Deferred update feature]] for more information about deferred update mode. </td>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'10'</td>
<td align="right"> X'10'</td>
<td>File has been recovered. This notifies you that the file is intact but that some updates might have been undone. You might need to do some additional work to get the file to its most up-to-date state. Messages that describe the last updates applied are displayed when the file is opened. </td>
<td>File has been recovered. This notifies you that the file is intact but that some updates might have been undone. You might need to do some additional work to get the file to its most up-to-date state. Messages that describe the last updates applied are displayed when the file is opened. </td>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'08'</td>
<td align="right"> X'08'</td>
<td>File is full. One of the Tables A, B, C, or D has filled up. If Table A or C fills up, or if Table B fills up in a hashed file, a reorganization is required. Otherwise, the INCREASE command can be used to add more space.</td>
<td>File is full. One of the Tables A, B, C, or D has filled up. If Table A or C fills up, or if Table B fills up in a hashed file, a reorganization is required. Otherwise, the INCREASE command can be used to add more space.</td>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'02'</td>
<td align="right"> X'02'</td>
<td>File is physically inconsistent. The file was being updated when some form of severe error or a system crash occurred. This is described in detail in [[#Hard restarts|Hard restarts]]. This setting produces the FILE PHYSICALLY INCONSISTENT message. (A hard restart might have occurred.) </td>
<td>File is physically inconsistent. The file was being updated when some form of severe error or a system crash occurred. This is described in detail in [[#Hard restarts|Hard restarts]]. This setting produces the FILE PHYSICALLY INCONSISTENT message. (A hard restart might have occurred.) </td>
</tr>
</tr>
<tr>
<tr>
<td align="right"> X'01'</td>
<td align="right"> X'01'</td>
<td>File is not initialized. After a file is created, it must be initialized before data can be added. See the file initialization chapter for more information.</td>
<td>File is not initialized. After a file is created, it must be initialized before data can be added.
See [[Initializing files]] for more information.</td>
</tr>
</tr>
</table>
</table>
==Restarts==
==Restarts==
<p><var class="product">Model&nbsp;204</var> provides two kinds of restarts: </p>
<p>
<var class="product">Model&nbsp;204</var> provides two kinds of restarts: </p>
<ul>
<ul>
<li>Soft</li>
<li>Soft</li>
<li>Hard</li>
<li>Hard</li>
</ul>
</ul>
===Soft restarts===
===Soft restarts===
<p>Soft restarts occur when <var class="product">Model&nbsp;204</var> recognizes a severe error that occurs between (as opposed to during) active update operations. </p>
<p>
Soft restarts occur when <var class="product">Model&nbsp;204</var> recognizes a severe error that occurs between (as opposed to during) active update operations. </p>
====Causes of soft restarts====
====Causes of soft restarts====
<p>Severe errors include nonrecoverable terminal I/O errors such as: </p>
<p>
Severe errors include nonrecoverable terminal I/O errors such as: </p>
<ul>
<ul>
<li>Phone is hung up</li>
<li>Phone is hung up</li>
<li>No input is coming in on a thread (with the inactive thread timeout feature enabled) for a specified number of seconds (see the Rocket <var class="product">Model&nbsp;204</var> System Manager's Guide)</li>
 
<li>No input is coming in on a thread (with the inactive thread timeout feature enabled) for a specified number of seconds. See [[Defining the user environment (CCAIN)#User environment control parameters|User environment control parameters]] for information on the TIMEOUT parameter.</li>
 
<li>Full server tables</li>
<li>Full server tables</li>
</ul>
</ul>
====Full server tables in transaction back out files====
====Full server tables in transaction back out files====
<p>If any server tables are full and the file is a transaction back out file, <var class="product">Model&nbsp;204</var> automatically backs out the incomplete transaction without a restart and informs the user through an error message that the transaction has been backed out. Otherwise, <var class="product">Model&nbsp;204</var> performs a soft restart.</p>
<p>
If any server tables are full and the file is a transaction back out file, <var class="product">Model&nbsp;204</var> automatically backs out the incomplete transaction without a restart and informs the user through an error message that the transaction has been backed out. Otherwise, <var class="product">Model&nbsp;204</var> performs a soft restart.</p>
====Effects of soft restarts====
====Effects of soft restarts====
<p>In a soft restart:</p>
<p>
In a soft restart:</p>
<ul>
<ul>
<li>User receives the USER RESTARTED SOFTLY message and is automatically logged out.</li>
<li>User receives the USER RESTARTED SOFTLY message and is automatically logged out.</li>
<li>File-physically-inconsistent flag is cleared (unless other users are updating the file) and the file-logically-inconsistent flag is set. </li>
<li>File-physically-inconsistent flag is cleared (unless other users are updating the file) and the file-logically-inconsistent flag is set. </li>
</ul>
</ul>
<p>The file is physically consistent (that is, file structural elements are in order: entries in the index correspond to entries in the data, and so on). However, there is a possibility that the file might be logically inconsistent. The restarted user might have been in the middle of an update transaction that would cause multiple updates to the file. Some updates might have been made before the soft restart occurred, while other updates were not made.  </p>
<p>
The file is physically consistent (that is, file structural elements are in order: entries in the index correspond to entries in the data, and so on). However, there is a possibility that the file might be logically inconsistent. The restarted user might have been in the middle of an update transaction that would cause multiple updates to the file. Some updates might have been made before the soft restart occurred, while other updates were not made.  </p>
 
===Hard restarts===
===Hard restarts===
<p>Hard restarts occur for severe errors during active updating operations. </p>
<p>
Hard restarts occur for severe errors during active updating operations. </p>
====Causes of hard restarts====
====Causes of hard restarts====
<p>Hard restarts can be caused by:</p>
<p>
Hard restarts can be caused by:</p>
<ul>
<ul>
<li>Disk I/O errors </li>
<li>Disk I/O errors </li>
<li>Table A, B, C, or D full conditions if transaction back out is not in effect</li>
<li>Table A, B, C, or D full conditions if transaction back out is not in effect</li>
</ul>
</ul>
<p>For a description of how these errors are handled when transaction back out is in effect, see the transaction backout chapter. If a severe error occurs, the user receives the USER RESTARTED message and is automatically logged out. The file-physically-inconsistent flag is set.    </p>
<p>
For a description of how these errors are handled when transaction back out is in effect, see [[Transaction back out]].
If a severe error occurs, the user receives the USER RESTARTED message and is automatically logged out. The file-physically-inconsistent flag is set.    </p>
====Effects of hard restarts====
====Effects of hard restarts====
<p>One hard restart can affect other users. For example:</p>
<p>
One hard restart can affect other users. For example:</p>
<ol>
<ol>
<li>User 1 and user 2 are each updating the same non-transaction-back out file.</li>
<li>User 1 and user 2 are each updating the same non-transaction-back out file.</li>
<li>User 1 updates KEY fields and gets a message that Table D is full.</li>
<li>User 1 updates KEY fields and gets a message that Table D is full.</li>
<li>File-physically-inconsistent flag (X'02') is set and user 1 is restarted. </li>
<li>File-physically-inconsistent flag (X'02') is set and user 1 is restarted. </li>
<li>User 1 now knows that there is a problem with the file.</li>
<li>User 1 now knows that there is a problem with the file.</li>
<li>User 2, however, continues updating NON-KEY fields and is not notified that Table D is full. </li>
<li>User 2, however, continues updating NON-KEY fields and is not notified that Table D is full. </li>
<li>User 2 finishes the request and closes the file without ever knowing that the file-physically-inconsistent flag was set. </li>
<li>User 2 finishes the request and closes the file without ever knowing that the file-physically-inconsistent flag was set. </li>
</ol>
</ol>
===Logically inconsistent files===
===Logically inconsistent files===
<p>A file is logically inconsistent when an incomplete update unit is left applied to the file. For example, consider an application that generates purchase orders. </p>
<p>
<p>Records are generated using the User Language STORE RECORD/END STORE construct and the PO number is the internal record number ($CURREC). The internal record number (PO number) is displayed on the screen along with the input items to be added to the record (through FOR RECORD NUMBER and ADD statements) when the transaction is committed.</p>
A file is logically inconsistent when an incomplete update unit is left applied to the file. For example, consider an application that generates purchase orders. </p>
<p>If you enter an EOJ command and <var class="product">Model&nbsp;204</var> terminates before the transaction is committed, the file is marked logically inconsistent (FISTAT X'40' is set), because an update is active and a user is waiting for terminal input.</p>
<p>
Records are generated using the User Language STORE RECORD/END STORE construct and the PO number is the internal record number ($CURREC). The internal record number (PO number) is displayed on the screen along with the input items to be added to the record (through FOR RECORD NUMBER and ADD statements) when the transaction is committed.</p>
<p>
If you enter an EOJ command and <var class="product">Model&nbsp;204</var> terminates before the transaction is committed, the file is marked logically inconsistent (FISTAT X'40' is set), because an update is active and a user is waiting for terminal input.</p>
 
===Physically inconsistent files===
===Physically inconsistent files===
<p>If the user is waiting for disk I/O during an ADD operation, and an EOJ is issued, it is possible that some, but not all tables were updated. In this case the file is marked physically inconsistent (FISTAT X'02' is set).</p>
<p>
If the user is waiting for disk I/O during an ADD operation, and an EOJ is issued, it is possible that some, but not all tables were updated. In this case the file is marked physically inconsistent (FISTAT X'02' is set).</p>
 
===Preventing inconsistent files===
===Preventing inconsistent files===
<p>In the previous examples, you could prevent the file from becoming logically or physically inconsistent by bumping all users before terminating <var class="product">Model&nbsp;204</var>.</p>
<p>
In the previous examples, you could prevent the file from becoming logically or physically inconsistent by bumping all users before terminating <var class="product">Model&nbsp;204</var>.</p>
 
===File manager responsibilities===
===File manager responsibilities===
<p>It is the file manager's responsibility to determine which users have been affected by a file integrity problem and notify them of the status of the file. You can use the BROADCAST FILE command described in [[ Field Display and Message Broadcast#BROADCAST command|BROADCAST command]] to do so. </p>
<p>
It is the file manager's responsibility to determine which users have been affected by a file integrity problem and notify them of the status of the file. You can use the BROADCAST FILE command described in [[ Field display and message broadcast#BROADCAST command|BROADCAST command]] to do so. </p>
 
==System failure==
==System failure==
<p>When the operating system or <var class="product">Model&nbsp;204</var> crashes during an updating request, the file-physically-inconsistent flag is set. The file might or might not actually be broken, depending on whether the modified file pages were written out before the crash. There is no way to predict whether or not this happens. Even if the pages were written out, the file might be logically inconsistent, depending on the point in the processing at which the crash occurred.  </p>
<p>
When the operating system or <var class="product">Model&nbsp;204</var> crashes during an updating request, the file-physically-inconsistent flag is set. The file might or might not actually be broken, depending on whether the modified file pages were written out before the crash. There is no way to predict whether or not this happens. Even if the pages were written out, the file might be logically inconsistent, depending on the point in the processing at which the crash occurred.  </p>
 
==Premature system termination==
==Premature system termination==
<p><var class="product">Model&nbsp;204</var> can be terminated prematurely (by operator cancellation or because of certain error conditions) while requests are still running. When <var class="product">Model&nbsp;204</var> is prematurely terminated, modified pages are not automatically written. This means that a user might have been updating and some or all updates might not appear on the file. In addition, if any other users were updating the same file shortly before termination, their updates might not appear either, even though their requests ran to completion.    </p>
<p>
<var class="product">Model&nbsp;204</var> can be terminated prematurely (by operator cancellation or because of certain error conditions) while requests are still running. When <var class="product">Model&nbsp;204</var> is prematurely terminated, modified pages are not automatically written. This means that a user might have been updating and some or all updates might not appear on the file. In addition, if any other users were updating the same file shortly before termination, their updates might not appear either, even though their requests ran to completion.    </p>
 
==Request cancellation==
==Request cancellation==
<p>If a serious user error occurs during evaluation of a User Language request, the request is canceled. Examples of serious user errors are:</p>
<p>
If a serious user error occurs during evaluation of a User Language request, the request is canceled. Examples of serious user errors are:</p>
<ul>
<ul>
<li>Incorrect use of a field name variable</li>
<li>Incorrect use of a field name variable</li>
Line 203: Line 265:
<li>Attempt to store too many values or too long a value for a preallocated field</li>
<li>Attempt to store too many values or too long a value for a preallocated field</li>
</ul>
</ul>
<p>Request cancellation functions in the same manner as a soft user restart. The user is notified that the request has been canceled, and the file is marked with the flag. If the file is a transaction back out file, <var class="product">Model&nbsp;204</var> cancels the request, backs out the incomplete transaction, and does not mark the file logically inconsistent. The user is notified that the transaction has been backed out.       </p>
<p>
Request cancellation functions in the same manner as a soft user restart. The user is notified that the request has been canceled, and the file is marked with the flag. If the file is a transaction back out file, <var class="product">Model&nbsp;204</var> cancels the request, backs out the incomplete transaction, and does not mark the file logically inconsistent. The user is notified that the transaction has been backed out. </p>
 
==Recovery methods==
==Recovery methods==
<p>Methods for recovering from file problems are presented in the following sections.</p>
<p>
Methods for recovering from file problems are presented in the following sections.</p>
 
===Taking the necessary precautions===
===Taking the necessary precautions===
<p>Take the following precautions to allow your site to recover from a file problem:</p>
<p>
Take the following precautions to allow your site to recover from a file problem:</p>
<ul>
<ul>
<li>Use the DUMP/RESTORE utility regularly to take regular backups. If a recent DUMP of the file is available, the file can be restored to its state at the time of the dump using the RESTORE command. See [[ File Dumping and Restoring#File Dumping and Restoring|File Dumping and Restoring]] for more information. </li>
<li>Use the DUMP/RESTORE utility regularly to take regular backups. If a recent DUMP of the file is available, the file can be restored to its state at the time of the dump using the RESTORE command. See [[File dumping and restoring]] for more information. </li>
<li>Dump the files. If journaling is ordinarily active, and all subsequent file updates are available, then you can use media recovery to restore file integrity. See the Rocket <var class="product">Model&nbsp;204</var> System Manager's Guide for information about using journals to recover files. </li>
 
<li>Activate checkpointing during Online processing. In the event of system crash, <var class="product">Model&nbsp;204</var> crash, or hard restart, you can use the RESTART command to roll back to the last valid checkpoint. If journaling is also active during the Online processing, you can use the roll forward feature to restore as many file changes as possible. These system recovery procedures are described in the Rocket <var class="product">Model&nbsp;204</var> System Manager's Guide.     </li>
<li>Dump the files. If journaling is ordinarily active, and all subsequent file updates are available, then you can use media recovery to restore file integrity. See [[System and media recovery]] for information about using journals to recover files. </li>
 
<li>Activate checkpointing during Online processing. In the event of system crash, <var class="product">Model&nbsp;204</var> crash, or hard restart, you can use the RESTART command to roll back to the last valid checkpoint. If journaling is also active during the Online processing, you can use the Roll Forward feature to restore as many file changes as possible. These system recovery procedures are described in [[System and media recovery]].</li>
</ul>
</ul>
<b>Warning</b>
<p class="warn"><b>Warning:</b>
<p>To ensure file integrity, Rocket Software strongly recommends that you <var class="term">never</var> reset the FISTAT (file status) parameter when it is set to the file-physically-inconsistent flag until <var class="term">just before</var> you reorganize the file. However, you must reset FISTAT before you reorganize a physically inconsistent file.       </p>
To ensure file integrity, Rocket Software strongly recommends that you <var class="term">never</var> reset the FISTAT (file status) parameter when it is set to the file-physically-inconsistent flag until <var class="term">just before</var> you reorganize the file. However, you must reset FISTAT before you reorganize a physically inconsistent file. </p>
 
===Reloading broken files===
===Reloading broken files===
<p>When the precautions recommended above have been neglected and the file is broken, recovery still might be possible. The safest method consists of resetting FISTAT temporarily and then running the following User Language request:</p>
<p>
When the precautions recommended above have been neglected and the file is broken, recovery still might be possible. The safest method consists of resetting FISTAT temporarily and then running the following User Language request:</p>
<p class="code">USE OUTFILE
<p class="code">USE OUTFILE
BEGIN
BEGIN
Line 225: Line 296:
   PRINT ALL INFORMATION
   PRINT ALL INFORMATION
END FOR
END FOR
END  
END
</p>
</p>
<p>You can then use a file load program with OUTFILE to reload the file (see the discussion of file reorganization and PAI FLOD in "Using PAI FLOD for files with varying record formats".  </p>
<p>
You can then use a file load program with OUTFILE to reload the file (see the discussion of file reorganization and PAI FLOD in "Using PAI FLOD for files with varying record formats".  </p>
 
==Reducing integrity problems==
==Reducing integrity problems==
<p>In addition to procedures used by the file and system managers for backup purposes, applications can be designed to reduce file integrity problems. </p>
<p>
In addition to procedures used by the file and system managers for backup purposes, applications can be designed to reduce file integrity problems. </p>
 
===Using COMMIT statements for manageable update units===
===Using COMMIT statements for manageable update units===
<p>Use a COMMIT statement between each logical update so that the system can set the file-physically-inconsistent flag off and write out updated file pages frequently. Also, <var class="product">Model&nbsp;204</var> can take checkpoints only between update units. Long update units can severely inhibit the taking of checkpoints. (Update units are discussed in detail in [[#Model 204 update units|Model 204 update units]].)    </p>
<p>
<p>To accomplish transaction back outs, <var class="product">Model&nbsp;204</var> maintains a transaction back out and constraint log for each active update unit, built in the system file CCATEMP. Sizable update units can greatly increase the amount of CCATEMP space used by the system. Because insufficient CCATEMP space terminates the run, commit update units frequently to minimize the CCATEMP space requirement. </p>
Use a COMMIT statement between each logical update so that the system can set the file-physically-inconsistent flag off and write out updated file pages frequently. Also, <var class="product">Model&nbsp;204</var> can take checkpoints only between update units. Long update units can severely inhibit the taking of checkpoints. (Update units are discussed in detail in [[#Model 204 update units|Model 204 update units]].)    </p>
<p>
To accomplish transaction back outs, <var class="product">Model&nbsp;204</var> maintains a transaction back out and constraint log for each active update unit, built in the system file CCATEMP. Sizable update units can greatly increase the amount of CCATEMP space used by the system. Because insufficient CCATEMP space terminates the run, commit update units frequently to minimize the CCATEMP space requirement. </p>
 
===Updates to TBO and non-TBO files in the same request===
===Updates to TBO and non-TBO files in the same request===
<p>You can update a non-TBO file, commit it, and then update a TBO file-or reversed file order-in the same request.</p>
<p>
<p>Requests that attempt to update TBO and non-TBO files without an intervening COMMIT will compile, but will fail during evaluation with the following message:</p>
You can update a non-TBO file, commit it, and then update a TBO file-or reversed file order-in the same request.</p>
<p>
Requests that attempt to update TBO and non-TBO files without an intervening COMMIT will compile, but will fail during evaluation with the following message:</p>
<p class="code"><b></b>***  1  CANCELLING REQUEST; M204.2771: ATTEMPT TO UPDATE TBO AND NON-TBO FILES IN THE SAME TRANSACTION
<p class="code"><b></b>***  1  CANCELLING REQUEST; M204.2771: ATTEMPT TO UPDATE TBO AND NON-TBO FILES IN THE SAME TRANSACTION
</p>
</p>
===Designing Host Language Interface jobs===
===Designing Host Language Interface jobs===
<p>For Host Language Interface jobs, set the update indicator in the IFSTRT function only when updating is really occurring, and issue the IFCHKPT call at various points during a long updating program.     </p>
<p>
<p>Retrieval-only Host Language Interface threads are not included in update units. Passing data from a retrieval-only thread to an update thread can result in logical inconsistencies to the updated file during Roll Forward. To prevent these inconsistencies, start the thread as an update thread and use a retrieval-only password to open the file, thus providing share-mode enqueuing and preventing updating from this thread. The file also is prevented from being marked physically inconsistent in the event of a hard restart or system crash. See the Rocket <var class="product">Model&nbsp;204</var> Host Language Interface Reference Manual for further description.</p>
For Host Language Interface jobs, set the update indicator in the IFSTRT function only when updating is really occurring, and issue the IFCHKPT call at various points during a long updating program. </p>
<p>
Retrieval-only Host Language Interface threads are not included in update units. Passing data from a retrieval-only thread to an update thread can result in logical inconsistencies to the updated file during Roll Forward.
To prevent these inconsistencies, start the thread as an update thread and use a retrieval-only password to open the file, thus providing share-mode enqueuing and preventing updating from this thread.
The file also is prevented from being marked physically inconsistent in the event of a hard restart or system crash. See [[HLI: Job design factors#Recovery considerations for single and multicursor IFAM2 threads|Recovery considerations for single and multicursor IFAM2 threads]] for further description.</p>
 
==Update units and transactions==
==Update units and transactions==
<p>In general data processing terms, a transaction is a sequence of operations that access a database. The order of these operations is defined by the application or the user. </p>
<p>
In general data processing terms, a transaction is a sequence of operations that access a database. The order of these operations is defined by the application or the user. </p>
 
===Model 204 transaction types===
===Model 204 transaction types===
<p><var class="product">Model&nbsp;204</var> recognizes the following types of transactions: </p>
<p>
<var class="product">Model&nbsp;204</var> recognizes the following types of transactions: </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 250: Line 339:
<th>Transactions that...</th>
<th>Transactions that...</th>
</tr>
</tr>
<tr>
<tr>
<td align="right">1</td>
<td>1</td>
<td>Cannot update the database</td>
<td>Cannot update the database</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">2</td>
<td>2</td>
<td>Can update the database but cannot be backed out</td>
<td>Can update the database but cannot be backed out</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">3 </td>
<td>3 </td>
<td>Can update the database and can be backed out</td>
<td>Can update the database and can be backed out</td>
</tr>
</tr>
</table>
</table>
===Model 204 update units===
===Model 204 update units===
<p>In the <var class="product">Model&nbsp;204</var> environment, the term update unit refers to any sequence of operations that is allowed to update the database. The two types of update transactions described above, types 2 and 3, are both update units in <var class="product">Model&nbsp;204</var>: </p>
<p>
In the <var class="product">Model&nbsp;204</var> environment, the term <b>update unit</b> refers to any sequence of operations that is allowed to update the database. The two types of update transactions described above, types 2 and 3, are both update units in <var class="product">Model&nbsp;204</var>: </p>
<ul>
<ul>
<li>Update units that cannot be backed out (type 2) are called <var class="term">non-backoutable update units</var>. </li>
<li>Update units that cannot be backed out (type 2) are called <b>non-backoutable update units</b>. </li>
<li>Update units that can be backed out (type 3), are called transactions or backoutable update units.</li>
 
<li>Update units that can be backed out (type 3), are called <b>transactions</b> or <b>backoutable update units</b>.</li>
</ul>
</ul>
====Non-backoutable update units====
====Non-backoutable update units====
<p>The following types of updates cannot be backed out and must be part of non-backoutable update units:</p>
<p>
The following types of updates cannot be backed out and must be part of non-backoutable update units:</p>
<ul>
<ul>
<li>Updates to non-transaction-back out files</li>
<li>Updates to non-transaction-back out files</li>
Line 278: Line 375:
<li>Procedure definitions </li>
<li>Procedure definitions </li>
</ul>
</ul>
====Backoutable update units====
====Backoutable update units====
<p>backoutable update units are User Language updates to a transaction back out file and their Host Language Interface counterparts (record or record set updating calls). These are the only types of update operations that can occur inside a <var class="product">Model&nbsp;204</var> transaction. A transaction can either be completed so that it persists in the file, or backed out so that the update is logically undone in the file.    </p>
<p>
<p>Detailed descriptions of the boundaries of User Language backoutable and non-backoutable update units are presented in the following sections, followed by a discussion of the Host Language Interface update unit boundaries.</p>
Backoutable update units are User Language updates to a transaction back out file and their Host Language Interface counterparts (record or record set updating calls). These are the only types of update operations that can occur inside a <var class="product">Model&nbsp;204</var> transaction. A transaction can either be completed so that it persists in the file, or backed out so that the update is logically undone in the file.    </p>
<p>
Detailed descriptions of the boundaries of User Language backoutable and non-backoutable update units are presented in the following sections, followed by a discussion of the Host Language Interface update unit boundaries.</p>
 
===Boundaries of non-backoutable update units===
===Boundaries of non-backoutable update units===
<p>Updating commands must be in non-backoutable update units. Some updating commands end any previous active update unit, whether backoutable or not. </p>
<p>
<p>The following updating commands always end active update units:</p>
Updating commands must be in non-backoutable update units. Some updating commands end any previous active update unit, whether backoutable or not. </p>
<p>
The following updating commands always end active update units:</p>
<table>
<table>
<tr>
<tr>
<td>INITALIZE </td>
<td><var>[[INITIALIZE command|INITIALIZE]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>TRANSFORM </td>
<td><var>TRANSFORM</var></td>
</tr>
</tr>
<tr>
<tr>
<td>REDEFINE field </td>
<td><var>[[REDEFINE command|REDEFINE FIELD]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>RENAME field </td>
<td><var>[[RENAME FIELD command|RENAME FIELD]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>DELETE field </td>
<td><var>[[DELETE command: Field|DELETE FIELD]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>CREATE file or permanent group </td>
<td><var>[[CREATE command: File|CREATE FILE]]</var> or <var>[[CREATE command: Permanent group|CREATE PERM GROUP]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>EDIT permanent procedure </td>
<td><var>[[EDIT command|EDIT]]</var> <i>permanent-procedure</i> </td>
</tr>
</tr>
<tr>
<tr>
<td>INCREASE +++ </td>
<td><var>[[INCREASE command|INCREASE]]</var> +++ </td>
</tr>
</tr>
<tr>
<tr>
<td>DECREASE +++ </td>
<td><var>[[DECREASE command|DECREASE]]</var> +++ </td>
</tr>
</tr>
<tr>
<tr>
<td>FLOD +++ </td>
<td><var>[[FLOD command|FLOD]]</var> +++ </td>
</tr>
</tr>
<tr>
<tr>
<td>FILELOAD +++ </td>
<td><var>[[FILELOAD command|FILELOAD]]</var> +++ </td>
</tr>
</tr>
<tr>
<tr>
<td>REGENERATE +++ </td>
<td><var>[[REGENERATE command|REGENERATE]]</var> +++ </td>
</tr>
</tr>
<tr>
<tr>
<td>REORGANIZE +++ </td>
<td><var>[[REORGANIZE command|REORGANIZE]]</var> +++ </td>
</tr>
</tr>
<tr>
<tr>
<td>RESTORE </td>
<td><var>[[RESTORE command|RESTORE]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>RESTOREG </td>
<td><var>[[RESTOREG command|RESTOREG]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>Z +++ </td>
<td><var>[[Z command|Z]]</var> +++ </td>
</tr>
</tr>
</table>
</table>
<p>The commands followed by +++ cannot be issued inside a procedure.</p>
<p>
The commands followed by +++ cannot be issued inside a procedure.</p>
====Updating commands that sometimes end active update units====
====Updating commands that sometimes end active update units====
<p>Other updating commands end the previous update unit only when that update unit is a User Language update. If a command non-backoutable update unit is in progress, the following commands are included in that non-backoutable update unit: </p>
<p>
Other updating commands end the previous update unit only when that update unit is a User Language update. If a command non-backoutable update unit is in progress, the following commands are included in that non-backoutable update unit: </p>
<table>
<table>
<tr>
<tr>
<td>SECURE </td>
<td><var>[[SECURE command: File|SECURE]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>BROADCAST FILE </td>
<td><var>[[BROADCAST command: Sending a file message|BROADCAST FILE]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>DEFINE </td>
<td><var>[[DEFINE command|DEFINE]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>PROCEDURE or PROC </td>
<td><var>[[PROCEDURE command|PROCEDURE or PROC]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>DELETE procedure or permanent group </td>
<td><var>[[DELETE command: Procedure|DELETE PROCEDURE]]</var> or <var>[[DELETE command: Permanent group|DELETE PERM GROUP]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>RESET file parameter   </td>
<td><var>[[RESET command|RESET]]</var>   </td>
</tr>
</tr>
<tr>
<tr>
<td>RENAME procedure +++ </td>
<td><var>[[RENAME PROCEDURE command|RENAME PROCEDURE]]</var> +++ </td>
</tr>
</tr>
<tr>
<tr>
<td>ASSIGN </td>
<td><var>[[ASSIGN command|ASSIGN]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>DEASSIGN </td>
<td><var>[[DEASSIGN command|DEASSIGN]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>DESECURE </td>
<td><var>[[DESECURE command: Overview of DESECURE|DESECURE]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>CREATEG +++  </td>
<td><var>[[CREATEG command|CREATEG]]</var> +++  </td>
</tr>
</tr>
</table>
</table>
====Nonupdating commands that end active update units====
====Nonupdating commands that end active update units====
<p>Nonupdating commands that end any previous update unit are:</p>
<p>
Nonupdating commands that end any previous update unit are:</p>
<table>
<table>
<tr>
<tr>
<td>CLOSE file </td>
<td><var>[[CLOSE command|CLOSE FILE]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>ALLOCATE </td>
<td><var>[[ALLOCATE command|ALLOCATE]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>FREE </td>
<td><var>[[FREE command|FREE]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>DUMP   </td>
<td><var>[[DUMP command|DUMP]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>DUMPG </td>
<td><var>[[DUMPG command|DUMPG]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>LOGOUT/LOGOFF   </td>
<td><var>[[LOGOUT or LOGOFF command|LOGOUT/LOGOFF]]</var>  </td>
</tr>
</tr>
<tr>
<tr>
<td>DISCONNECT </td>
<td><var>[[DISCONNECT command|DISCONNECT]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>EOJ +++  </td>
<td><var>[[EOJ command|EOJ]]</var> +++  </td>
</tr>
</tr>
</table>
</table>
<p>When a BEGIN or MORE command follows another command that does not automatically end its own update unit (for example, DEFINE), BEGIN or MORE ends the current update unit.  </p>
<p>
====User Language statements that end active update units or transactions====
When a BEGIN or MORE command follows another command that does not automatically end its own update unit (for example, DEFINE), BEGIN or MORE ends the current update unit.  </p>
<p>User Language statements that end the current update unit or transaction are:</p>
 
====SOUL statements that end active update units or transactions====
<p>
SOUL statements that end the current update unit or transaction are:</p>
<table>
<table>
<tr>
<tr>
<td>COMMIT</td>
<td><var>[[Record level locking and concurrency control#COMMIT statement|COMMIT]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>COMMIT RELEASE   </td>
<td><var>[[Record level locking and concurrency control#RELEASE option|COMMIT RELEASE]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>BACKOUT</td>
<td><var>[[Data recovery#Manual backout|BACKOUT]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>END  
<td><var>[[Basic request structure#Beginning and ending a request|END]]</var>
(only when END returns the user to include level 0 or terminal command level)</td>
(only when END returns the user to include level 0 or terminal command level)</td>
</tr>
</tr>
</table>
</table>
For information about the commit exits feature, which enables you to set up SOUL code to run at commit time, see [[Application_Subsystem_development#Commit_exits|Application Subsystem development]].
====Other ways to end active update units====
====Other ways to end active update units====
<p>Other situations that end the current update unit are:</p>
<p>
Other situations that end the current update unit are:</p>
<ul>
<ul>
<li>Return to terminal command level</li>
<li>Return to terminal command level</li>
<li>End of an application subsystem procedure, when control is transferred through the communications global variable, unless the Auto Commit option was turned off in the subsystem definition  </li>
<li>End of an application subsystem procedure, when control is transferred through the communications global variable, unless the Auto Commit option was turned off in the subsystem definition  </li>
<li>Request cancellation</li>
<li>Request cancellation</li>
<li>User restart    </li>
<li>User restart    </li>
</ul>
</ul>
====Starting non-backoutable update units====
====Starting non-backoutable update units====
<p>Non-backoutable update units in User Language start with the first FIND statement or the first User Language statement that performs an update operation on a file that is not a transaction back out file.</p>
<p>
<p>In a procedure, non-backoutable update units start with the first FIND statement, the first User Language statement that performs an update operation on a non-transaction back out file, or the first updating command. Each line of input to a procedure definition is treated as a separate update unit, but only one update ID is assigned to a single procedure definition. (For more information about update IDs, see the Rocket <var class="product">Model&nbsp;204</var> System Manager's Guide.)  </p>
Non-backoutable update units in User Language start with the first FIND statement or the first User Language statement that performs an update operation on a file that is not a transaction back out file.</p>
<p>Update units for the EDIT command start and end when the edited procedure is copied to the <var class="product">Model&nbsp;204</var> file during the END, GO, or SAVE subcommand. </p>
<p>
In a procedure, non-backoutable update units start with the first FIND statement, the first User Language statement that performs an update operation on a non-transaction back out file, or the first updating command.
Each line of input to a procedure definition is treated as a separate update unit, but only one [[System and media recovery#Understanding update units|update ID]] is assigned to a single procedure definition.</p>
<p>
Update units for the EDIT command start and end when the edited procedure is copied to the <var class="product">Model&nbsp;204</var> file during the END, GO, or SAVE subcommand. </p>
 
===Boundaries of transactions===
===Boundaries of transactions===
<p>A transaction (backoutable update unit) begins when the first User Language statement performing an update operation on a transaction back out file in a User Language request or a procedure is executed. </p>
<p>
====User Language statements that perform update operations====
A transaction (backoutable update unit) begins when the first SOUL statement performing an update operation on a transaction back out file in a User Language request or a procedure is executed. </p>
<p>The User Language statements that perform update operations are: </p>
====SOUL statements that perform update operations====
<p>
The SOUL statements that perform update operations are: </p>
<table>
<table>
<tr>
<tr>
<td>STORE RECORD </td>
<td><var>[[Data maintenance#STORE RECORD statement|STORE RECORD]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>DELETE RECORD </td>
<td><var>[[Data maintenance#DELETE RECORD statement|DELETE RECORD]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>DELETE RECORDS </td>
<td><var>[[Data maintenance#DELETE ALL RECORDS statement|DELETE RECORDS]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>FILE RECORDS </td>
<td><var>[[Data maintenance#FILE RECORDS statement|FILE RECORDS]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>ADD fieldname = value </td>
<td><var>[[Data maintenance#ADD statement|ADD]]</var> <i>fieldname</i> = <i>value</i> </td>
</tr>
</tr>
<tr>
<tr>
<td>DELETE fieldname = value </td>
<td><var>[[Data maintenance#DELETE statement|DELETE]]</var> <i>fieldname</i> = <i>value</i></td>
</tr>
</tr>
<tr>
<tr>
<td>DELETE EACH fieldname </td>
<td><var>[[Processing multiply occurring fields and field_groups#DELETE statement|DELETE EACH]]</var> <i>fieldname</i> </td>
</tr>
</tr>
<tr>
<tr>
<td>INSERT fieldname = value </td>
<td><var>[[Processing multiply occurring fields and field_groups#INSERT statement|INSERT]]</var> <i>fieldname</i> = <i>value</i> </td>
</tr>
</tr>
<tr>
<tr>
<td>CHANGE fieldname TO value</td>
<td><var>[[Processing multiply occurring fields and field_groups#CHANGE statement|CHANGE]]</var> <i>fieldname</i> <var>TO</var> <i>value</i></td>
</tr>
</tr>
</table>
</table>
<p>These are the only update operations that can occur inside transactions or can be backed out. A non-backoutable update unit must end before a transaction begins.</p>
<p>
These are the only update operations that can occur inside transactions or can be backed out. A non-backoutable update unit must end before a transaction begins.</p>
 
====Commands that end active transactions====
====Commands that end active transactions====
<p>Commands that end an active transaction are: </p>
<p>
Commands that end an active transaction are: </p>
<table>
<table>
<tr>
<tr>
<td>Any file updating command</td>
<td>Any file updating command</td>
</tr>
</tr>
<tr>
<tr>
<td>CHECKPOINT </td>
<td><var>[[CHECKPOINT command|CHECKPOINT]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>CLOSE file </td>
<td><var>[[CLOSE command|CLOSE FILE]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>RESET file parameter  </td>
<td><var>[[RESET command|RESET]]</var>  </td>
</tr>
</tr>
<tr>
<tr>
<td>ALLOCATE </td>
<td><var>[[ALLOCATE command|ALLOCATE]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>FREE </td>
<td><var>[[FREE command|FREE]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>LOGOUT/LOGOFF  </td>
<td><var>[[LOGOUT or LOGOFF command|LOGOUT/LOGOFF]]</var>   </td>
</tr>
</tr>
<tr>
<tr>
<td>DISCONNECT </td>
<td><var>[[DISCONNECT command|DISCONNECT]]</var> </td>
</tr>
</tr>
<tr>
<tr>
<td>DUMP   </td>
<td><var>[[DUMP command|DUMP]]</var></td>
</tr>
</tr>
<tr>
<tr>
<td>DUMPG   </td>
<td><var>[[DUMPG command|DUMPG]]</var></td>
</tr>
</tr>
</table>
</table>
====Other events that can end active transactions====
====Other events that can end active transactions====
<p>Other events that end a transaction are:</p>
<p>
Other events that end a transaction are:</p>
<ul>
<ul>
<li>Return to terminal command level</li>
<li>Return to terminal command level</li>
<li>End of an application subsystem procedure, when control is transferred through the communications global variable, unless the Auto Commit option was turned off in the subsystem definition  </li>
<li>End of an application subsystem procedure, when control is transferred through the communications global variable, unless the Auto Commit option was turned off in the subsystem definition  </li>
<li>Request cancellation</li>
<li>Request cancellation</li>
<li>User restart </li>
<li>User restart </li>
</ul>
</ul>
<p>In User Language, ending a transaction does not start a new transaction. A new transaction does not start until a User Language statement performs an update operation on a transaction back out file.  </p>
<p>
In User Language, ending a transaction does not start a new transaction. A new transaction does not start until a User Language statement performs an update operation on a transaction back out file.  </p>
 
===Host Language Interface update units===
===Host Language Interface update units===
<p>For details about update units in the Host Language Interface environment, see the Rocket <var class="product">Model&nbsp;204</var> Host Language Interface Programming Guide.   </p>
<p>
<p>&nbsp;</p>
For details about update units in the Host Language Interface environment, see [[HLI: Transactions]].</p>
</div> <!-- end of toc limit div -->


[[Category:File management]]
[[Category:Model 204 files]]
[[Category:Recovery]]

Latest revision as of 00:24, 1 January 2020

Overview

After files have been designed and loaded, one of the file manager's most important responsibilities is to maintain the integrity of the files. This topic describes some of the error conditions that threaten file structures and the steps that you can take to safeguard the files.

Error recovery features

Model 204 provides many features to ensure the data integrity, including:

  • Extensive command syntax checking and compiler diagnostics.
  • Double-checking of files and tape backups to ensure that files are correctly mounted.
  • SNA Communications Server (formerly VTAM) error recovery routines for data transmission from user terminals.
  • Trailers on each page with information such as file name, page number, and table number, which Model 204 checks every time the page is read or written to protect against loss of integrity due to a disk error.

In addition, Model 204 provides error recovery facilities as described in the following sections.

Transaction back out facility

Data integrity and logical consistency of the files are protected by the Model 204 Transaction back out facility, which can undo the effects of incomplete transactions on file data. Model 204 automatically backs out an incomplete transaction for a transaction back out file if a user's request is canceled, if Model 204 detects a file problem such as a table full condition, or if Model 204 is restarting the user. See Transaction back out for details.

RESTART recovery facility

The system manager must include a RESTART command as part of User 0's input if an installation is to use system recovery facilities. The RESTART command and System and media recovery pages discuss the syntax of this command and describe the Roll Back, Roll Forward, and Ignore features.

Media recovery

In the event of a media failure, such as a disk head crash, Model 204 allows you to recover files using the media recovery feature. Media recovery works by restoring files from a previously made backup copy, and then using the Roll Forward feature to reapply the updates that were made to the files since the time the copy was made.

Note: The REGENERATE command invokes the Restore and Roll Forward facilities automatically. In a media recovery run, the RESTORE and RESTART commands are not specified.

FRCVOPT and FOPT parameters

The FRCVOPT (file recovery options) parameter determines whether or not an installation logs checkpoint and/or Roll Forward information. The system manager also must include the RESTART command in a Model 204 job in order for recovery to run. If an installation uses the system recovery facilities, the file manager can control how files are affected.

The default setting of FRCVOPT is X'00'. The file participates in checkpointing, and batch Model 204 jobs that update the file can be run while the Online job is up. If your installation uses Roll Forward, the file participates. The back out mechanism of transaction back out is enabled.

If the FOPT parameter is also set to X'00' (enabling lock pending updates), the file is a transaction back out file. If the FOPT setting includes the X'02' option, disabling lock pending updates, Model 204 automatically disables transaction back out by turning on the X'08' bit of FRCVOPT.

FRCVOPT parameter

File recovery options are controlled by the FRCVOPT parameter. The possible FRCVOPT settings are:

Bit Meaning
X'80' File cannot be updated if Roll Forward logging is not active.
X'40' File cannot be updated if checkpoint logging is not active.
X'20' File does not participate in checkpoint logging.
X'10' Discontinuities not allowed (hold enqueuing while file is closed if the file has been updated in this run).
X'08' Transaction back out is disabled. If X'01' is specified, this option is automatically set.
X'04' File does not participate in Roll Forward logging.
X'02' File does not participate in Roll Forward logging.
X'01' All updates are reapplied to the file during Roll Forward, without regard to update unit boundaries. Because transactions are explicitly handled differently between transaction back out (X'08' off) and Roll Forward all the way (X'01' on), this option forces the X'08' option; that is, transaction back out is automatically turned off.

Eliminating checkpoints and Roll Forward logging

You can eliminate the overhead of checkpoint and Roll Forward logging if system crashes are infrequent and if manual backup facilities provide sufficient protection. To do this, turn on the X'24' bits of FRCVOPT. This strategy also works well for scratch files.

Logging all changes

At the other extreme, you might want to log all changes for recovery purposes. You can enforce this by setting the X'C0' bits of FRCVOPT. OPEN turns off all updating if logging is not active. The X'80' and X'40' bits are ignored if the OPEN command or statement is issued by User 0 and the file privileges include file manager. This override capability is designed to allow you to run batch update jobs, such as the File Load utility, without the overhead of logging.

Setting and clearing the X'10' bit

The FRCVOPT X'10' bit (discontinuities not allowed) is somewhat independent of the recovery facilities, although preventing discontinuities is less important when checkpointing is not being used. After the file has been updated, if the X'10' bit is set, Model 204 retains a share enqueue for the file, even if all users have closed the file. A separate retrieval job runs, but an updating job waits.

To allow a specific job to run, clear the X'10' bit of FRCVOPT and then close the file. If no other users have the file open, the batch job runs. After the batch job has finished, set the X'10' bit again.

Crash recovery features

In case of failure, Model 204 makes every effort to clean up files and shut down softly. If Model 204 or the operating system under which it is running crashes, any Model 204 file being updated is flagged by a special setting of the FISTAT parameter. The FILE PHYSICALLY INCONSISTENT message is issued whenever the file is opened thereafter until recovery procedures have been executed. In this case, or in the case of a hard crash, integrity can be recovered using the DUMP/RESTORE utility or restart/recovery facility.

FISTAT parameter

FISTAT is a flag parameter that provides control of update completion and other file status information. Generally, the meaning of the FISTAT setting and the actual state of the file determine any special action to be taken.

It is important to understand the different types of errors that can occur during processing, the effect each error has on the file and the setting of FISTAT, and the separation of updates into "update units."

The possible settings of FISTAT are:

Bit Meaning
X'40' File might be logically inconsistent. (Soft restart might have occurred.) Logical inconsistencies are described in more detail in Logically inconsistent files.
X'20' File is in deferred update mode. Either a file load program or an OPEN in deferred update mode was applied to the file, and the Z command has not yet been issued. See Deferred update feature for more information about deferred update mode.
X'10' File has been recovered. This notifies you that the file is intact but that some updates might have been undone. You might need to do some additional work to get the file to its most up-to-date state. Messages that describe the last updates applied are displayed when the file is opened.
X'08' File is full. One of the Tables A, B, C, or D has filled up. If Table A or C fills up, or if Table B fills up in a hashed file, a reorganization is required. Otherwise, the INCREASE command can be used to add more space.
X'02' File is physically inconsistent. The file was being updated when some form of severe error or a system crash occurred. This is described in detail in Hard restarts. This setting produces the FILE PHYSICALLY INCONSISTENT message. (A hard restart might have occurred.)
X'01' File is not initialized. After a file is created, it must be initialized before data can be added. See Initializing files for more information.

Restarts

Model 204 provides two kinds of restarts:

  • Soft
  • Hard

Soft restarts

Soft restarts occur when Model 204 recognizes a severe error that occurs between (as opposed to during) active update operations.

Causes of soft restarts

Severe errors include nonrecoverable terminal I/O errors such as:

  • Phone is hung up
  • No input is coming in on a thread (with the inactive thread timeout feature enabled) for a specified number of seconds. See User environment control parameters for information on the TIMEOUT parameter.
  • Full server tables

Full server tables in transaction back out files

If any server tables are full and the file is a transaction back out file, Model 204 automatically backs out the incomplete transaction without a restart and informs the user through an error message that the transaction has been backed out. Otherwise, Model 204 performs a soft restart.

Effects of soft restarts

In a soft restart:

  • User receives the USER RESTARTED SOFTLY message and is automatically logged out.
  • File-physically-inconsistent flag is cleared (unless other users are updating the file) and the file-logically-inconsistent flag is set.

The file is physically consistent (that is, file structural elements are in order: entries in the index correspond to entries in the data, and so on). However, there is a possibility that the file might be logically inconsistent. The restarted user might have been in the middle of an update transaction that would cause multiple updates to the file. Some updates might have been made before the soft restart occurred, while other updates were not made.

Hard restarts

Hard restarts occur for severe errors during active updating operations.

Causes of hard restarts

Hard restarts can be caused by:

  • Disk I/O errors
  • Table A, B, C, or D full conditions if transaction back out is not in effect

For a description of how these errors are handled when transaction back out is in effect, see Transaction back out. If a severe error occurs, the user receives the USER RESTARTED message and is automatically logged out. The file-physically-inconsistent flag is set.

Effects of hard restarts

One hard restart can affect other users. For example:

  1. User 1 and user 2 are each updating the same non-transaction-back out file.
  2. User 1 updates KEY fields and gets a message that Table D is full.
  3. File-physically-inconsistent flag (X'02') is set and user 1 is restarted.
  4. User 1 now knows that there is a problem with the file.
  5. User 2, however, continues updating NON-KEY fields and is not notified that Table D is full.
  6. User 2 finishes the request and closes the file without ever knowing that the file-physically-inconsistent flag was set.

Logically inconsistent files

A file is logically inconsistent when an incomplete update unit is left applied to the file. For example, consider an application that generates purchase orders.

Records are generated using the User Language STORE RECORD/END STORE construct and the PO number is the internal record number ($CURREC). The internal record number (PO number) is displayed on the screen along with the input items to be added to the record (through FOR RECORD NUMBER and ADD statements) when the transaction is committed.

If you enter an EOJ command and Model 204 terminates before the transaction is committed, the file is marked logically inconsistent (FISTAT X'40' is set), because an update is active and a user is waiting for terminal input.

Physically inconsistent files

If the user is waiting for disk I/O during an ADD operation, and an EOJ is issued, it is possible that some, but not all tables were updated. In this case the file is marked physically inconsistent (FISTAT X'02' is set).

Preventing inconsistent files

In the previous examples, you could prevent the file from becoming logically or physically inconsistent by bumping all users before terminating Model 204.

File manager responsibilities

It is the file manager's responsibility to determine which users have been affected by a file integrity problem and notify them of the status of the file. You can use the BROADCAST FILE command described in BROADCAST command to do so.

System failure

When the operating system or Model 204 crashes during an updating request, the file-physically-inconsistent flag is set. The file might or might not actually be broken, depending on whether the modified file pages were written out before the crash. There is no way to predict whether or not this happens. Even if the pages were written out, the file might be logically inconsistent, depending on the point in the processing at which the crash occurred.

Premature system termination

Model 204 can be terminated prematurely (by operator cancellation or because of certain error conditions) while requests are still running. When Model 204 is prematurely terminated, modified pages are not automatically written. This means that a user might have been updating and some or all updates might not appear on the file. In addition, if any other users were updating the same file shortly before termination, their updates might not appear either, even though their requests ran to completion.

Request cancellation

If a serious user error occurs during evaluation of a User Language request, the request is canceled. Examples of serious user errors are:

  • Incorrect use of a field name variable
  • Including field-level security violations
  • Attempt to store too many values or too long a value for a preallocated field

Request cancellation functions in the same manner as a soft user restart. The user is notified that the request has been canceled, and the file is marked with the flag. If the file is a transaction back out file, Model 204 cancels the request, backs out the incomplete transaction, and does not mark the file logically inconsistent. The user is notified that the transaction has been backed out.

Recovery methods

Methods for recovering from file problems are presented in the following sections.

Taking the necessary precautions

Take the following precautions to allow your site to recover from a file problem:

  • Use the DUMP/RESTORE utility regularly to take regular backups. If a recent DUMP of the file is available, the file can be restored to its state at the time of the dump using the RESTORE command. See File dumping and restoring for more information.
  • Dump the files. If journaling is ordinarily active, and all subsequent file updates are available, then you can use media recovery to restore file integrity. See System and media recovery for information about using journals to recover files.
  • Activate checkpointing during Online processing. In the event of system crash, Model 204 crash, or hard restart, you can use the RESTART command to roll back to the last valid checkpoint. If journaling is also active during the Online processing, you can use the Roll Forward feature to restore as many file changes as possible. These system recovery procedures are described in System and media recovery.

Warning: To ensure file integrity, Rocket Software strongly recommends that you never reset the FISTAT (file status) parameter when it is set to the file-physically-inconsistent flag until just before you reorganize the file. However, you must reset FISTAT before you reorganize a physically inconsistent file.

Reloading broken files

When the precautions recommended above have been neglected and the file is broken, recovery still might be possible. The safest method consists of resetting FISTAT temporarily and then running the following User Language request:

USE OUTFILE BEGIN ALL: FIND ALL RECORDS END FIND PRINT.LOOP: FOR EACH RECORD IN ALL PRINT '*' PRINT ALL INFORMATION END FOR END

You can then use a file load program with OUTFILE to reload the file (see the discussion of file reorganization and PAI FLOD in "Using PAI FLOD for files with varying record formats".

Reducing integrity problems

In addition to procedures used by the file and system managers for backup purposes, applications can be designed to reduce file integrity problems.

Using COMMIT statements for manageable update units

Use a COMMIT statement between each logical update so that the system can set the file-physically-inconsistent flag off and write out updated file pages frequently. Also, Model 204 can take checkpoints only between update units. Long update units can severely inhibit the taking of checkpoints. (Update units are discussed in detail in Model 204 update units.)

To accomplish transaction back outs, Model 204 maintains a transaction back out and constraint log for each active update unit, built in the system file CCATEMP. Sizable update units can greatly increase the amount of CCATEMP space used by the system. Because insufficient CCATEMP space terminates the run, commit update units frequently to minimize the CCATEMP space requirement.

Updates to TBO and non-TBO files in the same request

You can update a non-TBO file, commit it, and then update a TBO file-or reversed file order-in the same request.

Requests that attempt to update TBO and non-TBO files without an intervening COMMIT will compile, but will fail during evaluation with the following message:

*** 1 CANCELLING REQUEST; M204.2771: ATTEMPT TO UPDATE TBO AND NON-TBO FILES IN THE SAME TRANSACTION

Designing Host Language Interface jobs

For Host Language Interface jobs, set the update indicator in the IFSTRT function only when updating is really occurring, and issue the IFCHKPT call at various points during a long updating program.

Retrieval-only Host Language Interface threads are not included in update units. Passing data from a retrieval-only thread to an update thread can result in logical inconsistencies to the updated file during Roll Forward. To prevent these inconsistencies, start the thread as an update thread and use a retrieval-only password to open the file, thus providing share-mode enqueuing and preventing updating from this thread. The file also is prevented from being marked physically inconsistent in the event of a hard restart or system crash. See Recovery considerations for single and multicursor IFAM2 threads for further description.

Update units and transactions

In general data processing terms, a transaction is a sequence of operations that access a database. The order of these operations is defined by the application or the user.

Model 204 transaction types

Model 204 recognizes the following types of transactions:

Type Transactions that...
1 Cannot update the database
2 Can update the database but cannot be backed out
3 Can update the database and can be backed out

Model 204 update units

In the Model 204 environment, the term update unit refers to any sequence of operations that is allowed to update the database. The two types of update transactions described above, types 2 and 3, are both update units in Model 204:

  • Update units that cannot be backed out (type 2) are called non-backoutable update units.
  • Update units that can be backed out (type 3), are called transactions or backoutable update units.

Non-backoutable update units

The following types of updates cannot be backed out and must be part of non-backoutable update units:

  • Updates to non-transaction-back out files
  • Updates resulting from file updating commands (such as RENAME field)
  • Host Language functions that correspond to the updates in the previous two items
  • Updates resulting from the EDIT subcommands END and GO
  • Procedure definitions

Backoutable update units

Backoutable update units are User Language updates to a transaction back out file and their Host Language Interface counterparts (record or record set updating calls). These are the only types of update operations that can occur inside a Model 204 transaction. A transaction can either be completed so that it persists in the file, or backed out so that the update is logically undone in the file.

Detailed descriptions of the boundaries of User Language backoutable and non-backoutable update units are presented in the following sections, followed by a discussion of the Host Language Interface update unit boundaries.

Boundaries of non-backoutable update units

Updating commands must be in non-backoutable update units. Some updating commands end any previous active update unit, whether backoutable or not.

The following updating commands always end active update units:

INITIALIZE
TRANSFORM
REDEFINE FIELD
RENAME FIELD
DELETE FIELD
CREATE FILE or CREATE PERM GROUP
EDIT permanent-procedure
INCREASE +++
DECREASE +++
FLOD +++
FILELOAD +++
REGENERATE +++
REORGANIZE +++
RESTORE
RESTOREG
Z +++

The commands followed by +++ cannot be issued inside a procedure.

Updating commands that sometimes end active update units

Other updating commands end the previous update unit only when that update unit is a User Language update. If a command non-backoutable update unit is in progress, the following commands are included in that non-backoutable update unit:

SECURE
BROADCAST FILE
DEFINE
PROCEDURE or PROC
DELETE PROCEDURE or DELETE PERM GROUP
RESET
RENAME PROCEDURE +++
ASSIGN
DEASSIGN
DESECURE
CREATEG +++

Nonupdating commands that end active update units

Nonupdating commands that end any previous update unit are:

CLOSE FILE
ALLOCATE
FREE
DUMP
DUMPG
LOGOUT/LOGOFF
DISCONNECT
EOJ +++

When a BEGIN or MORE command follows another command that does not automatically end its own update unit (for example, DEFINE), BEGIN or MORE ends the current update unit.

SOUL statements that end active update units or transactions

SOUL statements that end the current update unit or transaction are:

COMMIT
COMMIT RELEASE
BACKOUT
END (only when END returns the user to include level 0 or terminal command level)

For information about the commit exits feature, which enables you to set up SOUL code to run at commit time, see Application Subsystem development.

Other ways to end active update units

Other situations that end the current update unit are:

  • Return to terminal command level
  • End of an application subsystem procedure, when control is transferred through the communications global variable, unless the Auto Commit option was turned off in the subsystem definition
  • Request cancellation
  • User restart

Starting non-backoutable update units

Non-backoutable update units in User Language start with the first FIND statement or the first User Language statement that performs an update operation on a file that is not a transaction back out file.

In a procedure, non-backoutable update units start with the first FIND statement, the first User Language statement that performs an update operation on a non-transaction back out file, or the first updating command. Each line of input to a procedure definition is treated as a separate update unit, but only one update ID is assigned to a single procedure definition.

Update units for the EDIT command start and end when the edited procedure is copied to the Model 204 file during the END, GO, or SAVE subcommand.

Boundaries of transactions

A transaction (backoutable update unit) begins when the first SOUL statement performing an update operation on a transaction back out file in a User Language request or a procedure is executed.

SOUL statements that perform update operations

The SOUL statements that perform update operations are:

STORE RECORD
DELETE RECORD
DELETE RECORDS
FILE RECORDS
ADD fieldname = value
DELETE fieldname = value
DELETE EACH fieldname
INSERT fieldname = value
CHANGE fieldname TO value

These are the only update operations that can occur inside transactions or can be backed out. A non-backoutable update unit must end before a transaction begins.

Commands that end active transactions

Commands that end an active transaction are:

Any file updating command
CHECKPOINT
CLOSE FILE
RESET
ALLOCATE
FREE
LOGOUT/LOGOFF
DISCONNECT
DUMP
DUMPG

Other events that can end active transactions

Other events that end a transaction are:

  • Return to terminal command level
  • End of an application subsystem procedure, when control is transferred through the communications global variable, unless the Auto Commit option was turned off in the subsystem definition
  • Request cancellation
  • User restart

In User Language, ending a transaction does not start a new transaction. A new transaction does not start until a User Language statement performs an update operation on a transaction back out file.

Host Language Interface update units

For details about update units in the Host Language Interface environment, see HLI: Transactions.