AddRecordset (Recordset subroutine): Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
m (→Example) |
||
| (12 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Recordset:AddRecordset subtitle}} | |||
<var>AddRecordset</var> adds a <var>Recordset</var> object's records to the records in an existing | <var>AddRecordset</var> adds a <var>Recordset</var> object's records to the records in an existing | ||
| Line 11: | Line 7: | ||
but it does so for <var>Recordset</var> objects. | but it does so for <var>Recordset</var> objects. | ||
==Syntax== | ==Syntax== | ||
{{Template:Recordset:AddRecordset syntax}} | |||
===Syntax terms=== | |||
===Syntax | |||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th> | <tr><th>recordset</th> | ||
<td>A non-null <var>Recordset</var> object | <td>A non-null <var>Recordset</var> object. | ||
</td></tr> | </td></tr> | ||
<tr><th> | <tr><th>inRecordset</th> | ||
<td>A non-null <var>Recordset</var> object, which must have the same file context as | <td>A non-null <var>Recordset</var> object, which must have the same file context as the method object (<var class="term">recordset</var>). | ||
</td></tr></table> | </td></tr></table> | ||
==Usage | ==Usage notes== | ||
<ul> | <ul> | ||
<li>The lock strength of the <var> | <li>The lock strength of the <var class="term">inRecordset</var> object being added to the method object | ||
must be greater than or equal to the lock strength of the | must be greater than or equal to the lock strength of the method object. | ||
Consequently, <var>AddRecordset</var> will not require any new locks — | Consequently, <var>AddRecordset</var> will not require any new locks — | ||
any records being added must already be locked by the user at an equal | any records being added must already be locked by the user at an equal | ||
or greater strength than the | or greater strength than the method object. | ||
Therefore, this method will never cause a record locking conflict. | Therefore, this method will never cause a record locking conflict. | ||
Within a <var>Recordset</var>, all records are always locked at the same strength (the | Within a <var>Recordset</var>, all records are always locked at the same strength (the | ||
| Line 48: | Line 43: | ||
<li>The <var>AddRecordset</var> method can be thought of as a <var>Recordset</var> OR operation; | <li>The <var>AddRecordset</var> method can be thought of as a <var>Recordset</var> OR operation; | ||
<var>[[AndRecordset (Recordset subroutine)|AndRecordset]]</var> can be thought of | <var>[[AndRecordset (Recordset subroutine)|AndRecordset]]</var> can be thought of | ||
as an AND | as an AND, and <var>[[RemoveRecordset (Recordset subroutine)|RemoveRecordset]]</var> | ||
as | as subtraction. | ||
No basic method is the analog of an exclusive OR operation, but | No basic method is the analog of an exclusive OR operation, but | ||
you can use the basic methods to | you can use the basic methods to perform an exclusive OR, as shown | ||
in <var>[[RemoveRecordset (Recordset subroutine)#Examples|"Examples"]] | in the <var>RemoveRecordset</var> [[RemoveRecordset (Recordset subroutine)#Examples|"Examples"]] section. | ||
</ul> | </ul> | ||
==Example== | ==Example== | ||
In the following example, the result of one <var>Find</var> is combined with the | In the following example, the result of one <var>Find</var> is combined with the | ||
result of another: | result of another: | ||
<p class="code"> %review is object recordSet in file orders | <p class="code">%review is object recordSet in file orders | ||
%pending is object recordSet in file orders | |||
find records to %review | |||
status = 'REVIEW' | |||
end find | |||
find records to %pending | |||
status = 'PENDING' | |||
end find | |||
%review:addRecordset(%pending) | |||
</p> | </p> | ||
Of course, identical processing could be done with an | Of course, identical processing could be done with an <var>Or</var> in a <var>Find</var> statement. | ||
<var>Or</var> in a <var>Find</var> statement. | |||
==See also== | |||
<ul> | |||
<li><var>[[AddRecord (Recordset subroutine)|AddRecord]]</var> | |||
<li><var>[[AddRecordsetNew (Recordset function)|AddRecordsetNew]]</var> | |||
</ul> | |||
{{Template:Recordset:AddRecordset footer}} | |||
Latest revision as of 22:19, 6 November 2012
Add a Recordset's records to a Recordset (Recordset class)
AddRecordset adds a Recordset object's records to the records in an existing
Recordset object.
It provides functionality identical to the User Language
Place Records statement,
but it does so for Recordset objects.
Syntax
recordset:AddRecordset( inRecordset)
Syntax terms
| recordset | A non-null Recordset object. |
|---|---|
| inRecordset | A non-null Recordset object, which must have the same file context as the method object (recordset). |
Usage notes
- The lock strength of the inRecordset object being added to the method object
must be greater than or equal to the lock strength of the method object.
Consequently, AddRecordset will not require any new locks —
any records being added must already be locked by the user at an equal
or greater strength than the method object.
Therefore, this method will never cause a record locking conflict.
Within a Recordset, all records are always locked at the same strength (the
lock strength with which the object was created).
In summary, these locking rules are in effect.
Any violation of them results in request cancellation.
- To a Recordset locked at exclusive level, you may add only records that are locked at exclusive level.
- To a Recordset locked at share level, you may add records locked at exclusive level or share level.
- To an unlocked Recordset you may add records locked at any strength (exclusive, share, none).
- If the Recordset object parameter of AddRecordset is null, the request is cancelled.
- The AddRecordset method can be thought of as a Recordset OR operation; AndRecordset can be thought of as an AND, and RemoveRecordset as subtraction. No basic method is the analog of an exclusive OR operation, but you can use the basic methods to perform an exclusive OR, as shown in the RemoveRecordset "Examples" section.
Example
In the following example, the result of one Find is combined with the result of another:
%review is object recordSet in file orders %pending is object recordSet in file orders find records to %review status = 'REVIEW' end find find records to %pending status = 'PENDING' end find %review:addRecordset(%pending)
Of course, identical processing could be done with an Or in a Find statement.