View source for 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> (that is: <var>[[Record_class|Record]]</var>, <var>[[Recordset_class|Recordset]]</var>, <var>[[SortedRecordset_class|SortedRecordset]]</var>, and <var>[[RecordsetCursor_class|RecordsetCursor]]</var>) classes.
<div class="toclimit-3">__TOC__</div>
==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.
 
There is no distinction between a <var>Find</var> conflict and a record locking conflict.  For example, you can use the following:
 
<p class="code"> [[Exceptions#Try and Catch|try]]
    fd to %foo
       ...
    end find
 [[Exceptions#Try and Catch|catch]] recordLockingConflict
    ...
 end try
</p>
 
And you can also use:
<p class="code"> try
    %rec = [[New_(Record_constructor)|new]](%recnum, exclusive)
    for record %rec
        ...
    end for
 catch recordLockingConflict
    ...
 end try
</p>
 
You can even catch record locking conflicts caused by <var>[[LoopLockStrength_(Record_property)|LoopLockStrength]]</var> promotions during a loop:
<p class="code"> %rec = new(%recnum, none, loopLockStrength=share)
  ...
 try for record %rec
     ...
     end for
 catch recordLockingConflict
    ...
 end try
</p>
 
Or as in the following:
<p class="code"> %curser = new(%recset, loopLockStrength=none)
  ...
 try
    for record at cursor %curser
       ...
    end for
 catch recordLockingConflict
    ..
 end try
</p>
 
Or as in this example:
<p class="code"> fdwol to %recset = new(loopLockStrength=exclusive)
    ...
 end find
  ...
 try for each record in %recset
       ...
     end for
 catch recordLockingConflict
    ...
 end try
</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:
<p class="code"> 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
</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.


==The RecordLockingConflict methods==
{{Template:List of RecordLockingConflict methods}}

The methods in the class are described in the subsections that follow. In addition:
<ul>
<li>[[Notation conventions for methods|"Notation conventions for methods"]] has information
about the conventions followed. 
<li>[[RecordLockingConflict methods syntax|"RecordLockingConflict methods syntax"]] is a single page that contains the syntax diagrams of all the methods in the class.
</ul>
<br/><br/>
===ConflictingLockStrength property===

{{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.

====Syntax====
{{Template:RecordLockingConflict:ConflictingLockStrength syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%lockStrength</th>
<td>A variable to receive the output value, a LockStrength enumeration value.
</td></tr>
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
</td></tr></table>
====Usage notes====
<ul>
<li>If the [[RECLOCKO_parameter|RECLOCKO parameter]] X'04' bit isn't set, this property will return 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>.
</ul>
<br/><br/>
===ConflictingRecordLockType property===

{{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.

====Syntax====
{{Template:RecordLockingConflict:ConflictingRecordLockType syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%recordLockType</th>
<td>A variable to receive the output value, a RecordLockType enumeration value.
</td></tr>
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
</td></tr></table>
====Usage notes====
<ul>
<li>If the [[RECLOCKO_parameter|RECLOCKO parameter]] X'04' bit isn't set, this property will return a <var>Null</var> value.
</ul>
<br/><br/>

===ConflictTimeMilliseconds property===
{{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.

====Syntax====
{{Template:RecordLockingConflict:ConflictTimeMilliseconds syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%number</th>
<td>A variable to receive the output value.
</td></tr>
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
</td></tr></table>
====Usage notes====
<ul>
<li>The [[MillisecondsToString (Float function)|MillisecondsToString method]] can be used to convert this value to a more human-friendly format.
</ul>
<br/><br/>
===Copy and DeepCopy functions===
{{Template:RecordLockingConflict:Copy subtitle}}

{{Template:RecordLockingConflict:DeepCopy subtitle}}

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

====Syntax====
{{Template:RecordLockingConflict:Copy syntax}}
{{Template:RecordLockingConflict:DeepCopy syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%outRecordLockingConflict</th>
<td>A RecordLockingConflict object variable to receive the output value.
</td></tr>
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
</td></tr></table>
====Usage notes====
<ul>

<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 DeepCopy method for the RecordLockingConflict class means that classes that contain references to RecordLockingConflict objects can also be DeepCopy-able.

</ul>
<br/><br/>

===Filename property===
{{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.

====Syntax====
{{Template:RecordLockingConflict:Filename syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%string</th>
<td>A <var>longstring</var> to receive the file name.
</td></tr>
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
</td></tr></table>
<br/><br/>
===LockTimeMilliseconds property===
{{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.

====Syntax====
{{Template:RecordLockingConflict:LockTimeMilliseconds syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%number</th>
<td>A variable to receive the output value.
</td></tr>
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
</td></tr></table>
====Usage notes====
<ul>
<li>The [[MillisecondsToString (Float function)|MillisecondsToString method]] can be used to convert this value to a more human-friendly format.

<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. 

</ul>
<br/><br/>

===New constructor===
{{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.

====Syntax====
{{Template:RecordLockingConflict:New syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%recordLockingConflict</th>
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.
</td></tr>
<tr><th><var>[%(RecordLockingConflict):]</var></th>
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr>
<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></tr>
<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></tr>
<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></tr>
<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></tr>
</table>
<br/><br/>
===RecordNumber property===
{{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.

====Syntax====
{{Template:RecordLockingConflict:RecordNumber syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%number</th>
<td>A numeric variable to receive the record number.
</td></tr>

<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
</td></tr></table>

====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:
<p class="code"> %rlc  is object RecordLockingConflict
  ...
 %rec = new(%recnum, none, loopLockStrength=share)
  ...
 try for record %rec
     ...
     end for
 catch recordLockingConflict to %rlc
    [[Audittext|auditText]] Conflict on record {%rlc:recordNumber}     -
       in file {%rlc:filename}
    auditText Conflicting user was userid {%rlc:userid}, -
       with user number:{%rlc:userNumber}
 end try
</p>
<br/><br/>
===UserID property===
{{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.

====Syntax====
{{Template:RecordLockingConflict:UserID syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%string</th>
<td>A <var>[[Longstrings|longstring]]</var> to receive the userid value.
</td></tr>
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.

</td></tr></table>
<br/><br/>
===UserNumber property===
{{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.

====Syntax====
{{Template:RecordLockingConflict:UserNumber syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%number</th>
<td>A numeric variable to receive the user number.
</td></tr>
<tr><th>recordLockingConflict</th>
<td>A reference to an instance of a <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> object.
</td></tr></table>


[[Category:System exception classes]]