Difference between revisions of "RecordLockingConflict class"

From m204wiki
Jump to navigation Jump to search
m
m (misc formatting)
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
<!-- RecordLockingConflict class -->
 
<!-- RecordLockingConflict class -->
The <var>RecordLockingConflict</var> exception class catches record locking conflict errors thrown by file object operations: that is, from methods in the <var>[[File_classes|file]]</var> classes (that is, <var>[[Record_class|Record]]</var>, <var>[[Recordset_class|Recordset]]</var>, <var>[[SortedRecordset_class|SortedRecordset]]</var>, and <var>[[RecordsetCursor_class|RecordsetCursor]]</var>).
+
The <var>RecordLockingConflict</var> exception class catches record locking conflict errors thrown by file object operations, that is, from methods in the <var>[[File_classes|file]]</var> classes (<var>[[Record_class|Record]]</var>, <var>[[Recordset_class|Recordset]]</var>, <var>[[SortedRecordset_class|SortedRecordset]]</var>, and <var>[[RecordsetCursor_class|RecordsetCursor]]</var>).
<div class="toclimit-3">__TOC__</div>
+
<div class="toclimit-2">__TOC__</div>
  
<h1 style="font-size:150%">Summary</h1>
+
==Summary==
A RecordLockingConflict exception is thrown only if there is a Catcher for the exception. This allows <code>On record Locking Conflict</code> and <code>On Find Conflict</code> units to trap record locking conflicts if there is no Catch block for the exception.
+
A <var>RecordLockingConflict</var> exception is thrown only if there is a Catcher for the exception. This allows <code>On Record Locking Conflict</code> and <code>On Find Conflict</code> units to trap record locking conflicts if there is no <var>[[Exceptions#Try and Catch|Catch]]</var> block for the exception.
 
   
 
   
There is no distinction between a <var>Find</var> conflict and a record locking conflict. For example, you can use the following:
+
There is no distinction between a <var>Find</var> conflict and a <var>Record Locking</var> conflict. For example, you can use the following:
 
   
 
   
 
<p class="code">[[Exceptions#Try and Catch|try]]
 
<p class="code">[[Exceptions#Try and Catch|try]]
Line 64: Line 64:
 
</p>
 
</p>
 
   
 
   
In the latter example, note that any iteration of the For loop can <var>throw</var> an exception, and there is no way of picking up where you left off (at the next record, say) if you get a <var>RecordLockingConflict</var> exception in such a case.  So, unless you always want to lose the whole loop on a record locking conflict, such a case is almost always better structured with a cursor on the recordset and with <var>Try</var> around the <var>For Record At Cursor</var> loop:
+
In the latter example, note that any iteration of the <var>For</var> loop can [[Exceptions#Throwing exceptions|throw]] an exception, and there is no way of picking up where you left off (at the next record, say) if you get a <var>RecordLockingConflict</var> exception in such a case.  So, unless you always want to lose the whole loop on a record locking conflict, such a case is almost always better structured with a cursor on the recordset and with <var>Try</var> around the <var>For Record At Cursor</var> loop:
 
<p class="code">fdwol to %recset = new(loopLockStrength=exclusive)
 
<p class="code">fdwol to %recset = new(loopLockStrength=exclusive)
 
   ...
 
   ...
Line 81: Line 81:
 
</p>
 
</p>
 
   
 
   
<b>Note:</b> The <var>For</var> statement can be on the same line as the <var>Try</var>, or it can be inside the <var>Try</var> block.
+
<p class="note"><b>Note:</b> The <var>For</var> statement can be on the same line as the <var>Try</var>, or it can be inside the <var>Try</var> block. </p>
  
 
==The RecordLockingConflict methods==
 
==The RecordLockingConflict methods==
Line 88: Line 88:
 
The methods in the class are described in the subsections that follow. In addition:
 
The methods in the class are described in the subsections that follow. In addition:
 
<ul>
 
<ul>
<li>[[Notation conventions for methods|"Notation conventions for methods"]] has information
+
<li>[[Notation conventions for methods]] has information about the conventions followed. </li>
about the conventions followed.  
+
<li>[[RecordLockingConflict methods syntax]] is a single page that contains the syntax diagrams of all the methods in the class. </li>
<li>[[RecordLockingConflict methods syntax|"RecordLockingConflict methods syntax"]] is a single page that contains the syntax diagrams of all the methods in the class.
 
 
</ul>
 
</ul>
  
Line 98: Line 97:
 
{{Template:RecordLockingConflict:ConflictingLockStrength subtitle}}
 
{{Template:RecordLockingConflict:ConflictingLockStrength subtitle}}
  
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> returns a [[LockStrength_enumeration|LockStrength enumeration]] value indicating the strength of the lock held by another user that caused the conflict.
+
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> method returns a <var>[[LockStrength_enumeration|LockStrength]]</var> enumeration value indicating the strength of the lock held by another user that caused the conflict.
  
 
====Syntax====
 
====Syntax====
Line 104: Line 103:
  
 
====Syntax terms====
 
====Syntax terms====
<table class="syntaxTable">
+
<table>
 
<tr><th>%lockStrength</th>
 
<tr><th>%lockStrength</th>
<td>A variable to receive the output value, a LockStrength enumeration value.
+
<td>A variable to receive the output value, a <var>LockStrength</var> enumeration value.</td></tr>
</td></tr>
+
 
 
<tr><th>recordLockingConflict</th>
 
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
+
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.
 
</td></tr></table>
 
</td></tr></table>
  
 
====Usage notes====
 
====Usage notes====
 
<ul>
 
<ul>
<li>If the [[RECLOCKO_parameter|RECLOCKO parameter]] X'04' bit isn't set, this property will return a <var>Null</var> value.
+
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <var>Null</var> value.
<li>Since an unlocked record (LockStrength None) cannot cause an record locking conflict, a non-<var>Null</var> return value should always be either <var>Share</var> or <var>Exclusive</var>.
+
 
 +
<li>Since an unlocked record (<var>LockStrength</var> <code>None</code>) cannot cause a record locking conflict, a non-<var>Null</var> return value should always be either <var>Share</var> or <var>Exclusive</var>.
 
</ul>
 
</ul>
  
Line 123: Line 123:
 
{{Template:RecordLockingConflict:ConflictingRecordLockType subtitle}}
 
{{Template:RecordLockingConflict:ConflictingRecordLockType subtitle}}
  
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> returns a [[RecordLockType_enumeration|RecordLockType enumeration]] value indicating the type of the lock held by another user that caused the conflict.
+
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> method returns a <var>[[RecordLockType_enumeration|RecordLockType]]</var> enumeration value indicating the type of the lock held by another user that caused the conflict.
  
 
====Syntax====
 
====Syntax====
Line 129: Line 129:
  
 
====Syntax terms====
 
====Syntax terms====
<table class="syntaxTable">
+
<table>
 
<tr><th>%recordLockType</th>
 
<tr><th>%recordLockType</th>
<td>A variable to receive the output value, a RecordLockType enumeration value.
+
<td>A variable to receive the output value, a <var>RecordLockType</var> enumeration value.</td></tr>
</td></tr>
+
 
 
<tr><th>recordLockingConflict</th>
 
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
+
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr>
</td></tr></table>
+
</table>
  
 
====Usage notes====
 
====Usage notes====
 
<ul>
 
<ul>
<li>If the [[RECLOCKO_parameter|RECLOCKO parameter]] X'04' bit isn't set, this property will return a <var>Null</var> value.
+
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit isn't set, this property will return a <var>Null</var> value.
 
</ul>
 
</ul>
  
Line 146: Line 146:
 
{{Template:RecordLockingConflict:ConflictTimeMilliseconds subtitle}}
 
{{Template:RecordLockingConflict:ConflictTimeMilliseconds subtitle}}
  
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns a number that is the number of milliseconds since 1900 that the record locking conflict occurred.
+
This <var>ReadOnly</var> property returns a number that is the number of milliseconds since 1900 that the record locking conflict occurred.
  
 
====Syntax====
 
====Syntax====
Line 152: Line 152:
  
 
====Syntax terms====
 
====Syntax terms====
<table class="syntaxTable">
+
<table>
 
<tr><th>%number</th>
 
<tr><th>%number</th>
 
<td>A variable to receive the output value.
 
<td>A variable to receive the output value.
 
</td></tr>
 
</td></tr>
 
<tr><th>recordLockingConflict</th>
 
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
+
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.
 
</td></tr></table>
 
</td></tr></table>
  
 
====Usage notes====
 
====Usage notes====
 
<ul>
 
<ul>
<li>The [[MillisecondsToString (Float function)|MillisecondsToString method]] can be used to convert this value to a more human-friendly format.
+
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <code>0</code> value.
 +
<li>The <var>[[MillisecondsToString (Float function)|MillisecondsToString]]</var> method can be used to convert this value to a more human-friendly format.
 
</ul>
 
</ul>
 
  
 
==Copy and DeepCopy functions==
 
==Copy and DeepCopy functions==
Line 171: Line 171:
 
{{Template:RecordLockingConflict:DeepCopy subtitle}}
 
{{Template:RecordLockingConflict:DeepCopy subtitle}}
  
Th functions return a copy of the method object, that is the RecordLockingConflict object to which they are applied.
+
These functions return a copy of the method object, that is the <var>RecordLockingConflict</var> object to which they are applied.
  
 
====Syntax====
 
====Syntax====
Line 178: Line 178:
  
 
====Syntax terms====
 
====Syntax terms====
<table class="syntaxTable">
+
<table>
 
<tr><th>%outRecordLockingConflict</th>
 
<tr><th>%outRecordLockingConflict</th>
 
<td>A RecordLockingConflict object variable to receive the output value.
 
<td>A RecordLockingConflict object variable to receive the output value.
 
</td></tr>
 
</td></tr>
 
<tr><th>recordLockingConflict</th>
 
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
+
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.
 
</td></tr></table>
 
</td></tr></table>
  
 
====Usage notes====
 
====Usage notes====
 
<ul>
 
<ul>
 +
<li>Since <var>RecordLockingConflict</var> objects contain no references to other objects, there is no difference between a <var>Copy</var> and <var>DeepCopy</var> method for these objects. </li>
  
<li>Since RecordLockingConflict objects contain no references to other objects, there is no difference between a Copy and DeepCopy method for these objects.
+
<li>The presence of a <var>DeepCopy</var> method for the <var>RecordLockingConflict</var> class means that classes that contain references to <var>RecordLockingConflict</var> objects can also be <var>DeepCopy</var>-able. </li>
<li>The presence of a DeepCopy method for the RecordLockingConflict class means that classes that contain references to RecordLockingConflict objects can also be DeepCopy-able.
 
 
</ul>
 
</ul>
  
Line 197: Line 197:
 
{{Template:RecordLockingConflict:Filename subtitle}}
 
{{Template:RecordLockingConflict:Filename subtitle}}
  
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns a <var>[[Longstrings|Longstring]]</var> that contains the name of the file in which the last record locking conflict occurred.
+
This <var>ReadOnly</var> property returns a <var>Longstring</var> that contains the name of the file in which the last record locking conflict occurred.
  
 
====Syntax====
 
====Syntax====
Line 203: Line 203:
  
 
====Syntax terms====
 
====Syntax terms====
<table class="syntaxTable">
+
<table>
 
<tr><th>%string</th>
 
<tr><th>%string</th>
 
<td>A <var>longstring</var> to receive the file name.
 
<td>A <var>longstring</var> to receive the file name.
 
</td></tr>
 
</td></tr>
 
<tr><th>recordLockingConflict</th>
 
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
+
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.
 
</td></tr></table>
 
</td></tr></table>
  
Line 215: Line 215:
 
{{Template:RecordLockingConflict:LockTimeMilliseconds subtitle}}
 
{{Template:RecordLockingConflict:LockTimeMilliseconds subtitle}}
  
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns a number that is the number of milliseconds since 1900 that the record that caused the record locking conflict was locked.
+
This <var>ReadOnly</var> property returns a number that is the number of milliseconds since 1900 that the record that caused the record locking conflict was locked.
  
 
====Syntax====
 
====Syntax====
Line 221: Line 221:
  
 
====Syntax terms====
 
====Syntax terms====
<table class="syntaxTable">
+
<table>
 
<tr><th>%number</th>
 
<tr><th>%number</th>
<td>A variable to receive the output value.
+
<td>A variable to receive the output value.</td></tr>
</td></tr>
+
 
 
<tr><th>recordLockingConflict</th>
 
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
+
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr>
</td></tr></table>
+
</table>
  
 
====Usage notes====
 
====Usage notes====
 
<ul>
 
<ul>
<li>The [[MillisecondsToString (Float function)|MillisecondsToString method]] can be used to convert this value to a more human-friendly format.
+
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <code>0</code> value. </li>
<li>LockingTimeMilliseconds, along with the [[#LockingUserNumber property|LockingUserNumber property]] should make it relatively easy to locate the request that locked the record that caused the record lock in the audit trail.
+
 
<li>Strictly speaking, the returned lock time is the time the finding and locking process began for the locked record, not when it was actually locked. Since the primary purpose this value is to locate audit trail information for the request that locked the conficting record, and since the entire locking process always happens within a single request, this distinction should be relatively unimportant.  
+
<li>The <var>[[MillisecondsToString (Float function)|MillisecondsToString]]</var> method can be used to convert this value to a more human-friendly format. </li>
 +
 
 +
<li>LockingTimeMilliseconds, along with the <var>[[#LockingUserNumber property|LockingUserNumber]]</var> property should make it relatively easy to locate the request that locked the record that caused the record lock in the audit trail. </li>
 +
 
 +
<li>Strictly speaking, the returned lock time is the time the finding and locking process began for the locked record, not when it was actually locked. Since the primary purpose this value is to locate audit trail information for the request that locked the conflicting record, and since the entire locking process always happens within a single request, this distinction should be relatively unimportant. </li>
 
</ul>
 
</ul>
 
  
 
==LockingUserNumber property==
 
==LockingUserNumber property==
 
{{Template:RecordLockingConflict:LockingUserNumber subtitle}}
 
{{Template:RecordLockingConflict:LockingUserNumber subtitle}}
  
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns the user number of the user that originally locked the conflicting record. This might be different from the value returned by the [[#UserNumber property|UserNumber property]] if a file object is passed between threads as a session object. In fact, a record lock caused by a file object in a closed session would return the session PST's user number for UserNumber but would return the user number that originally locked the record that caused the conflict.  
+
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns the user number of the user that originally locked the conflicting record. This might be different from the value returned by the <var>[[#UserNumber property|UserNumber]]</var> property if a file object is passed between threads as a session object. In fact, a record lock caused by a file object in a closed session would return the session PST's user number for <var>UserNumber</var> but would return the user number that originally locked the record that caused the conflict.  
  
 
====Syntax====
 
====Syntax====
Line 246: Line 249:
  
 
====Syntax terms====
 
====Syntax terms====
<table class="syntaxTable">
+
<table>
 
<tr><th>%number</th>
 
<tr><th>%number</th>
<td>A variable to receive the output value.
+
<td>A variable to receive the output value.</td></tr>
</td></tr>
+
 
 
<tr><th>recordLockingConflict</th>
 
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
+
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr>
</td></tr></table>
+
</table>
  
 
====Usage notes====
 
====Usage notes====
 
<ul>
 
<ul>
<li>LockingUserNumber, along with the [[#LockTimeMilliseconds property|LockTimeMilliseconds property]] should make it relatively easy to locate the request that locked the record that caused the record lock in the audit trail.
+
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <var>-1</var> value. </li>
</ul>
+
<li><var>LockingUserNumber</var>, along with the <var>LockTimeMilliseconds</var> property should make it relatively easy to locate the request that locked the record that caused the record lock in the audit trail.
 
+
</li></ul>
  
 
==New constructor==
 
==New constructor==
 
{{Template:RecordLockingConflict:New subtitle}}
 
{{Template:RecordLockingConflict:New subtitle}}
  
This <var>Constructor</var> generates an instance of an <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> exception. As shown in the syntax that follows, the <var>New</var> method arguments set the values of the class properties having the corresponding names. Each argument to <var>New</var> sets the value of the corresponding property of the newly constructed <var>RecordLockingConflict</var> object.
+
This <var>Constructor</var> generates an instance of a <var>RecordLockingConflict</var> exception. As shown in the syntax that follows, the <var>New</var> method arguments set the values of the class properties having the corresponding names. Each argument to <var>New</var> sets the value of the corresponding property of the newly constructed <var>RecordLockingConflict</var> object.
  
 
====Syntax====
 
====Syntax====
Line 269: Line 272:
  
 
====Syntax terms====
 
====Syntax terms====
<table class="syntaxTable">
+
<table>
 
<tr><th>%recordLockingConflict</th>
 
<tr><th>%recordLockingConflict</th>
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.
+
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr>
</td></tr>
+
 
 
<tr><th><var>[%(RecordLockingConflict):]</var></th>
 
<tr><th><var>[%(RecordLockingConflict):]</var></th>
 
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr>
 
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr>
 +
 
<tr><th><var>Filename</var></th>
 
<tr><th><var>Filename</var></th>
<td>This [[Methods#Named parameters|name required]] parameter specifies the <var>[[Longstrings|Longstring]]</var> value (<var class="term">string</var>) to be assigned to the object's <var>[[Filename_(RecordLockingConflict_property)|Filename]]</var> property. Its default value is a null string.
+
<td>This [[Methods#Named parameters|name required]] parameter specifies the <var>[[Longstrings|Longstring]]</var> value (<var class="term">string</var>) to be assigned to the object's <var>[[Filename_(RecordLockingConflict_property)|Filename]]</var> property. Its default value is a null string.</td></tr>
</td></tr>
+
 
 
<tr><th><var>RecordNumber</var></th>
 
<tr><th><var>RecordNumber</var></th>
<td>This name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[RecordNumber_(RecordLockingConflict_property)|RecordNumber]]</var> property. Its default value is 0.
+
<td>This name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[RecordNumber_(RecordLockingConflict_property)|RecordNumber]]</var> property. Its default value is 0.</td></tr>
</td></tr>
+
 
 
<tr><th><var>UserNumber</var></th>
 
<tr><th><var>UserNumber</var></th>
<td>This name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the exception object's <var>[[UserID_(RecordLockingConflict_property)|UserNumber]]</var> property. Its default value is 0.
+
<td>This name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the exception object's <var>[[UserID_(RecordLockingConflict_property)|UserNumber]]</var> property. Its default value is 0.</td></tr>
</td></tr>
 
  
 
<tr><th><var>UserID</var></th>
 
<tr><th><var>UserID</var></th>
<td>This name required parameter specifies the longstring value (<var class="term">string</var>) to be assigned to the object's <var>[[UserNumber_(RecordLockingConflict_property)|UserID]]</var> property. Its default value is a null string.
+
<td>This name required parameter specifies the longstring value (<var class="term">string</var>) to be assigned to the object's <var>[[UserNumber_(RecordLockingConflict_property)|UserID]]</var> property. Its default value is a null string.</td></tr>
</td></tr>
 
  
 
<tr><th><var>LockingUserNumber</var></th>
 
<tr><th><var>LockingUserNumber</var></th>
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[LockingUserNumber_(RecordLockingConflict_property)|LockingUserNumber]]</var> property. Its default value is <var>-1</var>, which is not a valid user number, and is the value set for the LockingUserNumber property by the system when the [[RECLOCKO parameter]] X'04' bit is not set and a RecordLockingConflict exception is thrown.  
+
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[LockingUserNumber_(RecordLockingConflict_property)|LockingUserNumber]]</var> property. Its default value is <var>-1</var>, which is not a valid user number, and is the value set for the <var>LockingUserNumber</var> property by the system when the <var>[[RECLOCKO parameter|RECLOCKO]]</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown.  
 
</td></tr>
 
</td></tr>
  
 
<tr><th><var>LockTimeMilliseconds</var></th>
 
<tr><th><var>LockTimeMilliseconds</var></th>
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[LockTimeMilliseconds_(RecordLockingConflict_property)|LockTimeMilliseconds]]</var> property. Its default value is a <var>0</var>, which is the value set for the LockTimeMilliseconds property by the system when the [[RECLOCKO parameter]] X'04' bit is not set and a RecordLockingConflict exception is thrown.  
+
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[LockTimeMilliseconds_(RecordLockingConflict_property)|LockTimeMilliseconds]]</var> property. Its default value is a <code>0</code>, which is the value set for the LockTimeMilliseconds property by the system when the <var>RECLOCKO</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. </td></tr>
</td></tr>
 
  
 
<tr><th><var>ConflictTimeMilliseconds</var></th>
 
<tr><th><var>ConflictTimeMilliseconds</var></th>
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[ConflictTimeMilliseconds_(RecordLockingConflict_property)|ConflictTimeMilliseconds]]</var> property. Its default value is a <var>0</var>, which is the value set for the ConflictTimeMilliseconds property by the system when the[[RECLOCKO parameter]] X'04' bit is not set and a RecordLockingConflict exception is thrown.  
+
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[ConflictTimeMilliseconds_(RecordLockingConflict_property)|ConflictTimeMilliseconds]]</var> property. Its default value is a <code>0</code>, which is the value set for the <var>ConflictTimeMilliseconds</var> property by the system when the <var>RECLOCKO</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. </td></tr>
</td></tr>
 
  
 
<tr><th><var>ConflictingLockStrength</var></th>
 
<tr><th><var>ConflictingLockStrength</var></th>
<td>This optional, name required parameter specifies the [[LockStrength enumeration]] value to be assigned to the object's <var>[[ConflictingLockStrength_(RecordLockingConflict_property)|ConflictingLockStrength]]</var> property. Its default value is a <var>Null</var>, which is the value set for the ConflictingLockStrength property by the system when the[[RECLOCKO parameter]] X'04' bit is not set and a RecordLockingConflict exception is thrown. Since a record locking conflict cannot be caused by an unlocked record, setting this value to <var>None</var> is equivalent to setting it to <var>Null</var>.
+
<td>This optional, name required parameter specifies the <var>[[LockStrength enumeration|LockStrength]]</var> enumeration value to be assigned to the object's <var>[[ConflictingLockStrength_(RecordLockingConflict property)|ConflictingLockStrength]]</var> property. Its default value is a <var>Null</var>, which is the value set for the <var>ConflictingLockStrength</var> property by the system when the <var>RECLOCKO</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. Since a record locking conflict cannot be caused by an unlocked record, setting this value to <var>None</var> is equivalent to setting it to <var>Null</var>.</td></tr>
</td></tr>
 
  
 
<tr><th><var>ConflictingRecordLockType</var></th>
 
<tr><th><var>ConflictingRecordLockType</var></th>
<td>This optional, name required parameter specifies the [[RecordLockType enumeration]] value to be assigned to the object's <var>[[ConflictingRecordLockType_(RecordLockingConflict_property)|ConflictingRecordLockType]]</var> property. Its default value is a <var>Null</var>, which is the value set for the ConflictingRecordLockType property by the system when the[[RECLOCKO parameter]] X'04' bit is not set and a RecordLockingConflict exception is thrown.
+
<td>This optional, name required parameter specifies the <var>[[RecordLockType enumeration]]</var> enumeration value to be assigned to the object's <var>[[ConflictingRecordLockType (RecordLockingConflict_property)|ConflictingRecordLockType]]</var> property. Its default value is a <var>Null</var>, which is the value set for the <var>ConflictingRecordLockType</var> property by the system when the <var>RECLOCKO parameter</var> X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown.</td></tr>
</td></tr>
 
 
</table>
 
</table>
 
  
 
==NewFromLastConflict constructor==
 
==NewFromLastConflict constructor==
 
{{Template:RecordLockingConflict:NewFromLastConflict subtitle}}
 
{{Template:RecordLockingConflict:NewFromLastConflict subtitle}}
  
This <var>Constructor</var> generates an instance of an <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> exception. Unlike the New method, this method obtains the values of the object properties from the last record locking conflict that occurred, whether or not it was trapped (caught or handled by an On unit). In fact, the greatest utility of this method would be to create a RecordLockingConflict instance that contains all record locking information in an <var>On Record Locking Conflict</var> or <var>On Find Conflict</var> unit. This is especially useful for accessing the properties set by the [[RECLOCKO parameter]] X'04' bit in an On unit. These properties are LockingUserNumber, LockTimeMilliseconds, ConflictTimeMilliseconds, ConflictingLockStrength, and ConflictingRecordLockType.
+
This <var>Constructor</var> generates an instance of an <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> exception. Unlike the New method, this method obtains the values of the object properties from the last record locking conflict that occurred, whether or not it was trapped (caught or handled by an On unit). In fact, the greatest utility of this method would be to create a <var>RecordLockingConflict</var> instance that contains all record locking information in an <var>On Record Locking Conflict</var> or <var>On Find Conflict</var> unit. This is especially useful for accessing the properties set by the <var>[[RECLOCKO parameter|RECLOCKO]]</var> parameter X'04' bit in an <var>On</var> unit. These properties are <var>LockingUserNumber</var>, <var>LockTimeMilliseconds</var>, <var>ConflictTimeMilliseconds</var>, <var>ConflictingLockStrength</var>, and <var>ConflictingRecordLockType</var>.
  
 
====Syntax====
 
====Syntax====
Line 321: Line 318:
 
====Syntax terms====
 
====Syntax terms====
 
<table class="syntaxTable">
 
<table class="syntaxTable">
<tr><th>%recordLockingConflict</th>
+
<tr><th>%reclockInfo</th>
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.
+
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr>
</td></tr>
+
 
 
<tr><th><var>[%(RecordLockingConflict):]</var></th>
 
<tr><th><var>[%(RecordLockingConflict):]</var></th>
 
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr>
 
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr>
Line 330: Line 327:
 
====Usage notes====
 
====Usage notes====
 
<ul>
 
<ul>
<li>If there have been no record locking conflicts in the current request, this method returns a <var>Null</var>.
+
<li>If there have been no record locking conflicts in the current request, this method returns a <var>Null</var>. </li>
<li>Since <var class="product">Model 204</var> clears the record locking conflict information at the start of each request, this method cannot be used to retrieve information from a previous request.
+
 
 +
<li>Since <var class="product">Model 204</var> clears the record locking conflict information at the start of each request, this method cannot be used to retrieve information from a previous request. </li>
 
</ul>
 
</ul>
 
  
 
==RecordNumber property==
 
==RecordNumber property==
 
{{Template:RecordLockingConflict:RecordNumber subtitle}}
 
{{Template:RecordLockingConflict:RecordNumber subtitle}}
  
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns the numeric value of the <var class="product">Model 204</var> internal record number of the record that has the conflict.
+
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns the numeric value of the <var class="product">Model&nbsp;204</var> internal record number of the record that has the conflict.
  
 
====Syntax====
 
====Syntax====
Line 350: Line 347:
  
 
<tr><th>recordLockingConflict</th>
 
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
+
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.
 
</td></tr></table>
 
</td></tr></table>
  
 
====Example====
 
====Example====
The following example shows all the properties of the <var>RecordLockingConflict</var> class. While the standard record locking conflict information is available for retrieval via the <var class="Product">User Language</var> functions $rlcfile, $rlcrec, $rlcuid, and $rlcusr, that information is also set in the exception object and retrievable via that object:
+
The following example shows all the properties of the <var>RecordLockingConflict</var> class. While the standard record locking conflict information is available for retrieval via the <var class="product">SOUL</var> functions <var>$RlcFile</var>, <var>$RlcRec</var>, <var>$RlcUid</var>, and <var>$RlcUsr</var>, that information is also set in the exception object and retrievable via that object:
 
<p class="code">%rlc  is object RecordLockingConflict
 
<p class="code">%rlc  is object RecordLockingConflict
 
  ...
 
  ...
Line 374: Line 371:
 
{{Template:RecordLockingConflict:UserID subtitle}}
 
{{Template:RecordLockingConflict:UserID subtitle}}
  
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns the <var class="product">Model 204</var> userid (login name) of the user that has the conflict.
+
This <var>ReadOnly</var> property returns the <var class="product">Model&nbsp;204</var> userid (login name) of the user that has the conflict.
  
 
====Syntax====
 
====Syntax====
Line 382: Line 379:
 
<table class="syntaxTable">
 
<table class="syntaxTable">
 
<tr><th>%string</th>
 
<tr><th>%string</th>
<td>A <var>[[Longstrings|longstring]]</var> to receive the userid value.
+
<td>A <var>[[Longstrings|longstring]]</var> to receive the userid value.</td></tr>
</td></tr>
+
 
 
<tr><th>recordLockingConflict</th>
 
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
+
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr>
</td></tr></table>
+
</table>
  
  
Line 392: Line 389:
 
{{Template:RecordLockingConflict:UserNumber subtitle}}
 
{{Template:RecordLockingConflict:UserNumber subtitle}}
  
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns the user number (unique per session) of the user that has the conflict.
+
This <var>ReadOnly</var> property returns the user number (unique per session) of the user that has the conflict.
  
 
====Syntax====
 
====Syntax====
Line 400: Line 397:
 
<table class="syntaxTable">
 
<table class="syntaxTable">
 
<tr><th>%number</th>
 
<tr><th>%number</th>
<td>A numeric variable to receive the user number.
+
<td>A numeric variable to receive the user number.</td></tr>
</td></tr>
+
 
 
<tr><th>recordLockingConflict</th>
 
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
+
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr>
</td></tr></table>
+
</table>
  
  
 
[[Category:System exception classes]]
 
[[Category:System exception classes]]

Latest revision as of 20:29, 1 April 2016

The RecordLockingConflict exception class catches record locking conflict errors thrown by file object operations, that is, from methods in the file classes (Record, Recordset, SortedRecordset, and RecordsetCursor).

Summary

A RecordLockingConflict exception is thrown only if there is a Catcher for the exception. This allows On Record Locking Conflict and On Find Conflict units to trap record locking conflicts if there is no Catch block for the exception.

There is no distinction between a Find conflict and a Record Locking conflict. For example, you can use the following:

try fd to %foo ... end find catch recordLockingConflict ... end try

And you can also use:

try %rec = new(%recnum, exclusive) for record %rec ... end for catch recordLockingConflict ... end try

You can even catch record locking conflicts caused by LoopLockStrength promotions during a loop:

%rec = new(%recnum, none, loopLockStrength=share) ... try for record %rec ... end for catch recordLockingConflict ... end try

Or as in the following:

%curser = new(%recset, loopLockStrength=none) ... try for record at cursor %curser ... end for catch recordLockingConflict .. end try

Or as in this example:

fdwol to %recset = new(loopLockStrength=exclusive) ... end find ... try for each record in %recset ... end for catch recordLockingConflict ... end try

In the latter example, note that any iteration of the For loop can throw an exception, and there is no way of picking up where you left off (at the next record, say) if you get a RecordLockingConflict exception in such a case. So, unless you always want to lose the whole loop on a record locking conflict, such a case is almost always better structured with a cursor on the recordset and with Try around the For Record At Cursor loop:

fdwol to %recset = new(loopLockStrength=exclusive) ... end find ... %curser = new(%recset, loopLockStrength=exclusive) repeat while %curser:state eq hasRecord try for record at cursor %curser ... end for catch recordLockingConflict ... end try %curser:next end repeat

Note: The For statement can be on the same line as the Try, or it can be inside the Try block.

The RecordLockingConflict methods

The following are the available RecordLockingConflict class methods.

MethodDescription
ConflictTimeMillisecondsTime that the conflict occurred
ConflictingLockStrengthLock strength of conflicting lock
ConflictingRecordLockTypeLock type of conflicting lock
CopyCopy the RecordLockingConflict object
DeepCopyDeep copy the RecordLockingConflict object
FilenameName of the file in which last record locking conflict occurred
LockTimeMillisecondsTime that the conflicting record was locked
LockingUserNumberUser number of the user that locked the conflicting record
NewCreate a new RecordLockingConflict object
NewFromLastConflictCreate object from current conflict information
RecordNumberRecord number of the record that has the conflict
UserIDUser ID (login name) of the user that has the conflict
UserNumberUser number of the user that has the conflict

The methods in the class are described in the subsections that follow. In addition:


ConflictingLockStrength property

Lock strength of conflicting lock (RecordLockingConflict class)

This ReadOnly method returns a LockStrength enumeration value indicating the strength of the lock held by another user that caused the conflict.

Syntax

%lockStrength = recordLockingConflict:ConflictingLockStrength

Syntax terms

%lockStrength A variable to receive the output value, a LockStrength enumeration value.
recordLockingConflict A reference to an instance of a RecordLockingConflict object.

Usage notes

  • If the RECLOCKO parameter X'04' bit is not set, this property returns a Null value.
  • Since an unlocked record (LockStrength None) cannot cause a record locking conflict, a non-Null return value should always be either Share or Exclusive.


ConflictingRecordLockType property

Lock type of conflicting lock (RecordLockingConflict class)

This ReadOnly method returns a RecordLockType enumeration value indicating the type of the lock held by another user that caused the conflict.

Syntax

%recordLockType = recordLockingConflict:ConflictingRecordLockType

Syntax terms

%recordLockType A variable to receive the output value, a RecordLockType enumeration value.
recordLockingConflict A reference to an instance of a RecordLockingConflict object.

Usage notes

  • If the RECLOCKO parameter X'04' bit isn't set, this property will return a Null value.


ConflictTimeMilliseconds property

Time that the conflict occurred (RecordLockingConflict class)

This ReadOnly property returns a number that is the number of milliseconds since 1900 that the record locking conflict occurred.

Syntax

%number = recordLockingConflict:ConflictTimeMilliseconds

Syntax terms

%number A variable to receive the output value.
recordLockingConflict A reference to an instance of a RecordLockingConflict object.

Usage notes

  • If the RECLOCKO parameter X'04' bit is not set, this property returns a 0 value.
  • The MillisecondsToString method can be used to convert this value to a more human-friendly format.

Copy and DeepCopy functions

Copy the RecordLockingConflict object (RecordLockingConflict class)

Deep copy the RecordLockingConflict object (RecordLockingConflict class)

These functions return a copy of the method object, that is the RecordLockingConflict object to which they are applied.

Syntax

%outRecordLockingConflict = recordLockingConflict:Copy

%outRecordLockingConflict = recordLockingConflict:DeepCopy

Syntax terms

%outRecordLockingConflict A RecordLockingConflict object variable to receive the output value.
recordLockingConflict A reference to an instance of a RecordLockingConflict object.

Usage notes

  • Since RecordLockingConflict objects contain no references to other objects, there is no difference between a Copy and DeepCopy method for these objects.
  • The presence of a DeepCopy method for the RecordLockingConflict class means that classes that contain references to RecordLockingConflict objects can also be DeepCopy-able.


Filename property

Name of the file in which last record locking conflict occurred (RecordLockingConflict class)

This ReadOnly property returns a Longstring that contains the name of the file in which the last record locking conflict occurred.

Syntax

%string = recordLockingConflict:Filename

Syntax terms

%string A longstring to receive the file name.
recordLockingConflict A reference to an instance of a RecordLockingConflict object.


LockTimeMilliseconds property

Time that the conflicting record was locked (RecordLockingConflict class)

This ReadOnly property returns a number that is the number of milliseconds since 1900 that the record that caused the record locking conflict was locked.

Syntax

%number = recordLockingConflict:LockTimeMilliseconds

Syntax terms

%number A variable to receive the output value.
recordLockingConflict A reference to an instance of a RecordLockingConflict object.

Usage notes

  • If the RECLOCKO parameter X'04' bit is not set, this property returns a 0 value.
  • The MillisecondsToString method can be used to convert this value to a more human-friendly format.
  • LockingTimeMilliseconds, along with the LockingUserNumber property should make it relatively easy to locate the request that locked the record that caused the record lock in the audit trail.
  • Strictly speaking, the returned lock time is the time the finding and locking process began for the locked record, not when it was actually locked. Since the primary purpose this value is to locate audit trail information for the request that locked the conflicting record, and since the entire locking process always happens within a single request, this distinction should be relatively unimportant.

LockingUserNumber property

User number of the user that locked the conflicting record (RecordLockingConflict class)

This ReadOnly property returns the user number of the user that originally locked the conflicting record. This might be different from the value returned by the UserNumber property if a file object is passed between threads as a session object. In fact, a record lock caused by a file object in a closed session would return the session PST's user number for UserNumber but would return the user number that originally locked the record that caused the conflict.

Syntax

%number = recordLockingConflict:LockingUserNumber

Syntax terms

%number A variable to receive the output value.
recordLockingConflict A reference to an instance of a RecordLockingConflict object.

Usage notes

  • If the RECLOCKO parameter X'04' bit is not set, this property returns a -1 value.
  • LockingUserNumber, along with the LockTimeMilliseconds property should make it relatively easy to locate the request that locked the record that caused the record lock in the audit trail.

New constructor

Create a new RecordLockingConflict object (RecordLockingConflict class)

This Constructor generates an instance of a RecordLockingConflict exception. As shown in the syntax that follows, the New method arguments set the values of the class properties having the corresponding names. Each argument to New sets the value of the corresponding property of the newly constructed RecordLockingConflict object.

Syntax

%recordLockingConflict = [%(RecordLockingConflict):]New( Filename= string, - RecordNumber= number, - UserNumber= number, - UserID= string, - [LockingUserNumber= number], - [LockTimeMilliseconds= number], - [ConflictTimeMilliseconds= number], - [ConflictingLockStrength= lockStrength], - [ConflictingRecordLockType= recordLockType])

Syntax terms

%recordLockingConflict A reference to an instance of a RecordLockingConflict object.
[%(RecordLockingConflict):] The class name in parentheses denotes a Constructor.
Filename This name required parameter specifies the Longstring value (string) to be assigned to the object's Filename property. Its default value is a null string.
RecordNumber This name required parameter specifies the numeric value (number) to be assigned to the object's RecordNumber property. Its default value is 0.
UserNumber This name required parameter specifies the numeric value (number) to be assigned to the exception object's UserNumber property. Its default value is 0.
UserID This name required parameter specifies the longstring value (string) to be assigned to the object's UserID property. Its default value is a null string.
LockingUserNumber This optional, name required parameter specifies the numeric value (number) to be assigned to the object's LockingUserNumber property. Its default value is -1, which is not a valid user number, and is the value set for the LockingUserNumber property by the system when the RECLOCKO parameter X'04' bit is not set and a RecordLockingConflict exception is thrown.
LockTimeMilliseconds This optional, name required parameter specifies the numeric value (number) to be assigned to the object's LockTimeMilliseconds property. Its default value is a 0, which is the value set for the LockTimeMilliseconds property by the system when the RECLOCKO parameter X'04' bit is not set and a RecordLockingConflict exception is thrown.
ConflictTimeMilliseconds This optional, name required parameter specifies the numeric value (number) to be assigned to the object's ConflictTimeMilliseconds property. Its default value is a 0, which is the value set for the ConflictTimeMilliseconds property by the system when the RECLOCKO parameter X'04' bit is not set and a RecordLockingConflict exception is thrown.
ConflictingLockStrength This optional, name required parameter specifies the LockStrength enumeration value to be assigned to the object's ConflictingLockStrength property. Its default value is a Null, which is the value set for the ConflictingLockStrength property by the system when the RECLOCKO parameter X'04' bit is not set and a RecordLockingConflict exception is thrown. Since a record locking conflict cannot be caused by an unlocked record, setting this value to None is equivalent to setting it to Null.
ConflictingRecordLockType This optional, name required parameter specifies the RecordLockType enumeration enumeration value to be assigned to the object's ConflictingRecordLockType property. Its default value is a Null, which is the value set for the ConflictingRecordLockType property by the system when the RECLOCKO parameter X'04' bit is not set and a RecordLockingConflict exception is thrown.

NewFromLastConflict constructor

Create object from current conflict information (RecordLockingConflict class)

This Constructor generates an instance of an RecordLockingConflict exception. Unlike the New method, this method obtains the values of the object properties from the last record locking conflict that occurred, whether or not it was trapped (caught or handled by an On unit). In fact, the greatest utility of this method would be to create a RecordLockingConflict instance that contains all record locking information in an On Record Locking Conflict or On Find Conflict unit. This is especially useful for accessing the properties set by the RECLOCKO parameter X'04' bit in an On unit. These properties are LockingUserNumber, LockTimeMilliseconds, ConflictTimeMilliseconds, ConflictingLockStrength, and ConflictingRecordLockType.

Syntax

%reclockInfo = [%(RecordLockingConflict):]NewFromLastConflict

Syntax terms

%reclockInfo A reference to an instance of a RecordLockingConflict object.
[%(RecordLockingConflict):] The class name in parentheses denotes a Constructor.

Usage notes

  • If there have been no record locking conflicts in the current request, this method returns a Null.
  • Since Model 204 clears the record locking conflict information at the start of each request, this method cannot be used to retrieve information from a previous request.

RecordNumber property

Record number of the record that has the conflict (RecordLockingConflict class)

This ReadOnly property returns the numeric value of the Model 204 internal record number of the record that has the conflict.

Syntax

%number = recordLockingConflict:RecordNumber

Syntax terms

%number A numeric variable to receive the record number.
recordLockingConflict A reference to an instance of a RecordLockingConflict object.

Example

The following example shows all the properties of the RecordLockingConflict class. While the standard record locking conflict information is available for retrieval via the SOUL functions $RlcFile, $RlcRec, $RlcUid, and $RlcUsr, that information is also set in the exception object and retrievable via that object:

%rlc is object RecordLockingConflict ... %rec = new(%recnum, none, loopLockStrength=share) ... try for record %rec ... end for catch recordLockingConflict to %rlc auditText Conflict on record {%rlc:recordNumber} - in file {%rlc:filename} auditText Conflicting user was userid {%rlc:userid}, - with user number:{%rlc:userNumber} end try


UserID property

User ID (login name) of the user that has the conflict (RecordLockingConflict class)

This ReadOnly property returns the Model 204 userid (login name) of the user that has the conflict.

Syntax

%string = recordLockingConflict:UserID

Syntax terms

%string A longstring to receive the userid value.
recordLockingConflict A reference to an instance of a RecordLockingConflict object.


UserNumber property

User number of the user that has the conflict (RecordLockingConflict class)

This ReadOnly property returns the user number (unique per session) of the user that has the conflict.

Syntax

%number = recordLockingConflict:UserNumber

Syntax terms

%number A numeric variable to receive the user number.
recordLockingConflict A reference to an instance of a RecordLockingConflict object.