New (Recordset constructor): Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(18 intermediate revisions by 3 users not shown)
Line 4: Line 4:
==Syntax==
==Syntax==
{{Template:Recordset:New syntax}}
{{Template:Recordset:New syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%newSet</th>
<tr><th>%recordSet</th>
<td>An empty <var>Recordset</var> object created by this method.
<td>An empty <var>Recordset</var> object created by this method.</td></tr>
</td></tr>
 
<tr><th><var>%(RecordSet)</var></th>
<tr><th nowrap="true"><var>[%(Recordset In </var>filOrGrp name<var>):]</var></th>
<td>Either a class name that includes a file context in parentheses, as in <code>%(Recordset in file sirLocal</code>), or a variable in the class, as in <code>%recSet</code>.
<td>The optional class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a <var>Recordset</var> <var>Constructor</var>.</td></tr>
</td></tr>
 
<div id="lockstrength"></div>
<tr><th>lockstrength</th>
<tr><th>lockstrength</th>
<td>The lock strength of the instantiated <var>Recordset</var> object. Options are <var>LockStrength</var> enumeration values (<var>None</var>, <var>Share</var>, or <var>Exclusive</var>), which correspond to standard <var class="product">Model 204</var> record-locking levels, as described below. This is an optional parameter, and it defaults to <var>Share</var>. <dl> <dt>None <dd><var>Recordset</var> is not locked. <br> No locks are held on the object, so there is no conflict with others holding <var>Share</var> or <var>Exclusive</var> locks (readers and updaters may proceed). <var>Find Without Locks</var> statements acquire this type of record lock. <dt>Share <dd><var>Recordset</var> is share locked. <br> This level allows other users to hold a Share lock, but not an Exclusive lock (allows readers but not updaters to proceed). <var>Find All Records</var> statements acquire this type of record lock. <dt>Exclusive <dd><var>Recordset</var> is exclusively locked. <br> This level prohibits others from holding either an <var>Exclusive</var> lock or a <var>Share</var> lock. It is generally used for update. <var>Find And Reserve</var> statements acquire this type of record lock. </dl>
<td>The strength of the lock to be used for the records referenced by the object. This value is a <var>[[LockStrength_enumeration|LockStrength enumeration]]</var> value: <var>None</var>, <var>Share</var>, or <var>Exclusive</var>.
</td></tr>
 
This is an optional parameter, and it defaults to <var>Share</var>. </td></tr>
 
<tr><th><var>LoopLockStrength</var></th>
<tr><th><var>LoopLockStrength</var></th>
<td>The lock strength to be used for loops on records in the <var>Recordset</var> object. This is an optional, [[Notation conventions for methods|name required]] parameter, available in <var class="product">Sirius Mods</var> 7.0 and later. It defaults to <var>None</var>. See [[Recordset class#LoopLockStrength for Recordsets|"LoopLockStrength for Recordsets"]].
<td>The lock strength to be used for loops on records in the <var>Recordset</var> object. This is an optional, [[Notation conventions for methods|name required]] parameter, available in <var class="product">Sirius Mods</var> 7.0 and later. It defaults to <var>None</var>. See [[Recordset class#LoopLockStrength for Recordsets|"LoopLockStrength for Recordsets"]].
</td></tr></table>
</td></tr></table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>As described in [[Object variables#Using New or other Constructors|"Using New or other Constructors"]], <var>New</var> can be invoked with no object, with an explicit class specification, or with an object variable in the class, even if that object is <var>Null</var>:
<p class="code">%recset = new
%recset = %(Recordset in file sirLocal):new
%recset = %recset:new
</p>
'''Note:'''
As shown above, when explicitly indicating the
class, both the class name and the file context must be
specified just as they are on the <var>Recordset</var> variable's declaration.
<li>Since the created <var>Recordset</var> object is empty, that is, contains no records,
<li>Since the created <var>Recordset</var> object is empty, that is, contains no records,
<var>New</var> needs to acquire no locks, so it cannot produce a record locking conflict.
<var>New</var> needs to acquire no locks, so it cannot produce a record locking conflict.
Line 31: Line 43:
the object created by <var>New</var> is empty and therefore fairly uninteresting.
the object created by <var>New</var> is empty and therefore fairly uninteresting.
</ul>
</ul>
==Examples==
==Examples==



Latest revision as of 23:43, 6 November 2012

Create a new Recordset object (Recordset class)


This function makes a new, empty instance of a Recordset object.

Syntax

%recordset = [%(Recordset In filOrGrp name):]New[( [lockStrength], - [LoopLockStrength= lockStrength])]

Syntax terms

%recordSet An empty Recordset object created by this method.
[%(Recordset In filOrGrp name):] The optional class name in parentheses denotes a Constructor. See "Usage notes", below, for more information about invoking a Recordset Constructor.
lockstrength The strength of the lock to be used for the records referenced by the object. This value is a LockStrength enumeration value: None, Share, or Exclusive. This is an optional parameter, and it defaults to Share.
LoopLockStrength The lock strength to be used for loops on records in the Recordset object. This is an optional, name required parameter, available in Sirius Mods 7.0 and later. It defaults to None. See "LoopLockStrength for Recordsets".

Usage notes

  • As described in "Using New or other Constructors", New can be invoked with no object, with an explicit class specification, or with an object variable in the class, even if that object is Null:

    %recset = new %recset = %(Recordset in file sirLocal):new %recset = %recset:new

    Note: As shown above, when explicitly indicating the class, both the class name and the file context must be specified just as they are on the Recordset variable's declaration.

  • Since the created Recordset object is empty, that is, contains no records, New needs to acquire no locks, so it cannot produce a record locking conflict.
  • New is typically used in conjunction with AddRecord or AddRecordset, since without these methods, the object created by New is empty and therefore fairly uninteresting.

Examples

Example New statements follow:

%rs is object recordSet in foo %rs = new %rs = new( none ) %rs = new( exclusive ) %rs = new( share )

See also