Record class: Difference between revisions

From m204wiki
Jump to navigation Jump to search
Line 111: Line 111:


===Setting record locking for a new Record instance===
===Setting record locking for a new Record instance===
Whether a record object is instantiated with the New constructor or
Whether a <var>Record</var> object is instantiated with the <var>New</var> constructor or
the <var>CurrentRecord</var> constructor, the record object will hold a
the <var>CurrentRecord</var> constructor, the record object will hold a
share lock on the record with which it is associated.
share lock on the record with which it is associated.
This is consistent with the locking behaviour of the <var class="product">Model 204</var> For Record Number
This is consistent with the locking behaviour of the <var class="product">Model 204</var> <var>For Record Number</var>
construct.
construct.
   
   
You can change the default record locking by using the optional
You can change the default record locking by using the optional
<code>lockstrength</code> parameter when you instantiate the object.
<code>lockstrength</code> parameter when you instantiate the object.
The value you specify must be a LockStrength enumeration,
The value you specify must be a <var>[[LockStrength enumeration]]</var>,
which may take a variety of forms:
which may take a variety of forms:
<p class="code"> %filerec = new(17, share)
<p class="code">%filerec = new(17, share)
    ...
  ...
%filerec = new(17, %(LockStrength):exclusive)
%filerec = new(17, %(LockStrength):exclusive)
    ...
  ...
%grouprec = new(1, 'TESTPROC', exclusive)
%grouprec = new(1, 'TESTPROC', exclusive)
    ...
  ...
%rec = CurrentRecord(None)
%rec = CurrentRecord(None)
    ...
  ...
%e is enumeration lockstrength
%e is enumeration lockstrength
%e = exclusive
%e = exclusive
%grouprec = new(1, 'TESTPROC', %e)
%grouprec = new(1, 'TESTPROC', %e)
</p>
</p>
The following example shows how you can
The following example shows how you can
Line 137: Line 137:
a <var>Recordset</var> object.
a <var>Recordset</var> object.
Within a record loop against a <var>Recordset</var> object,
Within a record loop against a <var>Recordset</var> object,
you refer to the <var>LockStrength</var> property of the Recordset as an argument to
you refer to the <var>LockStrength</var> property of the <var>Recordset</var> as an argument to
the <var>CurrentRecord</var> constructor for the Record object:
the <var>CurrentRecord</var> constructor for the <var>Record</var> object:
<p class="code"> begin
<p class="code">begin
   
   
    %stooges is object recordSet in file glwproc
%stooges is object recordSet in file glwproc
    %stooge is object record in file glwproc
%stooge is object record in file glwproc
   
   
    fdr to %stooges
fdr to %stooges
    end find
end find
   
   
    for each record in %stooges
for each record in %stooges
      %stooge = CurrentRecord(%stooges:LockStrength)
  %stooge = CurrentRecord(%stooges:LockStrength)
    end for
end for
   
   
    print %stooge:LockStrength:toString
print %stooge:LockStrength:toString
   
   
end
end
</p>
</p>
   
   
Since the Fdr statement instantiates a record set with Exclusive locking,
Since the <code>Fdr</code> statement instantiates a record set with <var>Exclusive</var> locking,
The Print statement result here is <code>Exclusive</code>.
the <code>Print</code> statement result here is <code>Exclusive</code>.
For more information about Recordset instantiation,
For more information about <var>Recordset</var> instantiation,
see [[Recordset class#Creating Recordset objects|"Creating Recordset objects"]].
see [[Recordset class#Creating Recordset objects|Creating Recordset objects]].


==Using Record objects in a For Record loop==
==Using Record objects in a For Record loop==

Revision as of 15:52, 26 August 2013

It is quite common for an instance of a class to be associated with a specific record in a specific file. It is therefore quite useful to be able to hold a lock on the record over the life of an object, or at least over several method invocations. The Record class makes this possible.

The Record class is a file class that references a specific record in a file or group.

Instantiating Record objects

As discussed in this section, there are two ways to instantiate a Record object:

  • With the New function
  • With the CurrentRecord function

You can also set the record locking for a newly instantiated Record object.

Using New to instantiate a Record object

The New function takes as input a record number for file context Record objects, or it takes a filename and record number for group context Record objects. For example:

%fileRec is object record in file foo %groupRec is object record in group bar ... %fileRec = new(%recno) ... %groupRec = new(%recno, %filename)

The returned record object references the indicated record number in the indicated file.

Using CurrentRecord to instantiate a Record object

The CurrentRecord constructor, a shared method in the Record class, must be in the appropriate record context:

  • Inside a record loop (For Each Record, For Record Number, For Record, etc.) that has the same file/group context as the Record object. For example:

    %recSet is object recordSet in file music %rec is object record in file music ... find records to %recSet composer = 'Mozart' end find for each record in %recSet %rec = currentRecord ... end for

    It is not valid to issue the CurrentRecord method for a record in one file or group context when the record loop has a different file or group context.

  • Inside a user method that is declared with the CurrentRecord attribute and with the same file or group as the Record object. Available as of Sirius Mods version 7.7, a CurrentRecord In File name or CurrentRecord In Group name clause on a method declaration indicates that:
    • The method may only be invoked in a record context (established by a For Each Record loop, for example) for the declared file or group. For example, the printField method, defined with the CurrentRecord attribute, is successfully invoked within an FR loop:

      local subroutine (Record in file myproc):printField - currentRecord in file myproc for record currentRecord print NAME end for end subroutine for each record in %recset %rec = CurrentRecord %rec:printField end for

    • Statements within the method definition, even a CurrentRecord method call, may reference the record without having to be wrapped inside a record For loop. For example, the XmlDoc class LoadFromRecord method, which normally requires a containing record loop, is valid as specified in the following method:

      local function getDoc is object xmlDoc - currentRecord in file parents %doc is object xmlDoc %doc = new %doc:loadFromRecord return %doc end function

      Note: Under Sirius Mods 7.7, field references are an exception to this rule. You may not reference a record field from within a method declared with CurrentRecord without being inside a record For loop, unless you are running under Sirius Mods version 7.8 or higher.

      For example, the For Record currentRecord and End For statements within the printField method in the preceding bullet item are not necessary in Sirius Mods version 7.8 or higher. In those versions, the print NAME statement succeeds by itself.

Setting record locking for a new Record instance

Whether a Record object is instantiated with the New constructor or the CurrentRecord constructor, the record object will hold a share lock on the record with which it is associated. This is consistent with the locking behaviour of the Model 204 For Record Number construct.

You can change the default record locking by using the optional lockstrength parameter when you instantiate the object. The value you specify must be a LockStrength enumeration, which may take a variety of forms:

%filerec = new(17, share) ... %filerec = new(17, %(LockStrength):exclusive) ... %grouprec = new(1, 'TESTPROC', exclusive) ... %rec = CurrentRecord(None) ... %e is enumeration lockstrength %e = exclusive %grouprec = new(1, 'TESTPROC', %e)

The following example shows how you can instantiate a Record object of the same lock strength as a Recordset object. Within a record loop against a Recordset object, you refer to the LockStrength property of the Recordset as an argument to the CurrentRecord constructor for the Record object:

begin %stooges is object recordSet in file glwproc %stooge is object record in file glwproc fdr to %stooges end find for each record in %stooges %stooge = CurrentRecord(%stooges:LockStrength) end for print %stooge:LockStrength:toString end

Since the Fdr statement instantiates a record set with Exclusive locking, the Print statement result here is Exclusive. For more information about Recordset instantiation, see Creating Recordset objects.

Using Record objects in a For Record loop

A Record object can be used to drive a single record For loop much like a For Record Number loop:

%rec is object record in file music ... for record %rec ... end for

A For Record loop using a locked Record object has these advantages over a For Record Number loop:

  • The Record object already holds a share lock so no share lock has to be obtained, and the record does not need to be validated against the existence bitmap. Both these actions have to be done for each For Record Number loop, and they have non-trivial overhead.
  • The record lock on the Record object is not lost between loops on the same record, or after a commit within a loop, so there are no worries about the record changing between For Record loops. With multiple For Record Number loops, a record can change between loops unless a lock is held on the record in some other way.

LoopLockStrength for Records

In addition to the LockStrength property, in Sirius Mods 7.0 and later, all Record objects also have a LoopLockStrength property. Like the LockStrength property, the LoopLockStrength property's values are of the LockStrength enumeration. The LoopLockStrength property indicates the minimum lock strength for the record being processed in an iteration of a For Record loop on a Record object.

If the LoopLockStrength is the same as or weaker than the LockStrength of a Record object, no action is required at the start of each loop — the record in the iteration is known to be locked at the strength of the Record which is greater than the LoopLockStrength. If, however, the LoopLockStrength is stronger than the LockStrength, each execution of a For Record loop on a Record object tries to obtain a LoopLockStrength level lock on the record in the iteration. If successful, the iteration is processed and the lock is released at the end of the loop execution.

The default value of LoopLockStrength is None, which means that no additional locking is performed for the record at the start of a For Record loop.

LoopLockStrength locking behavior is identical to the locking behavior of the For Record Number (FRN) statement. The meanings of certain statements in an On Record Locking conflict unit are identical to their meaning for a For Record Number statement conflict:

Bypass
Causes processing of the record to be skipped, which means that the For Record loop is not processed.
Retry
Causes the For Record statement to be re-executed and to try again to lock the record at the LoopLockStrength level.

There are many similarities in LoopLockStrength processing for Record and Recordset objects. For more information about the use of LoopLockStrength with Recordset objects see "LoopLockStrength for Recordsets".

List of Record methods

The "List of Record methods" shows all the class methods.