AddRecordsetNew (Recordset function)
Combine two RecordSets to produce a third (Recordset class)
AddRecordsetNew combines a Recordset object's records with the records in a second
Recordset object, producing a new Recordset object containing the combined
records.
It does the same processing as AddRecordset
but produces a new output Recordset and leaves the two input Recordsets unmodified.
Syntax
%outRecordset = recordset:AddRecordsetNew( inRecordset2)
Syntax terms
| %outRecordset | The Recordset object created by this method. |
|---|---|
| recordset | A non-null Recordset object, which must have the same file context as %outRecordset. |
| inRecordset2 | A non-null Recordset object, which must have the same file context as %outRecordset and recordset. |
Usage notes
- The AddRecordsetNew method is only available in Sirius Mods 7.1 and later.
- The LockStrength and LoopLockStrength of the output Recordset object (%outRecordset) is the same as that of the method object (recordset).
- The lock strength of inRecordset2 must be greater than or equal to the lock strength of the method object recordset.
Consequently, AddRecordset will not require any new locks —
all records being combined must already be locked by the user at an equal
or greater strength than lock strength of the resulting outRecordset.
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 method object recordset locked at exclusive level, you may combine only records that are locked at exclusive level.
- To a method object recordset locked at share level, you may combine records locked at exclusive level or share level.
- To an unlocked method object recordset you may combine records locked at any strength (exclusive, share, none).
- If the inRecordset2 argument of AddRecordset is null, the request is cancelled.
- The AddRecordsetNew method can be thought of as a Recordset OR operation; AndRecordsetNew can be thought of as an AND; and RemoveRecordsetNew as subtraction. No basic method is the analog of an exclusive OR operation, but you can use the basic methods to achieve an exclusive OR, as shown in the "Examples" section of RemoveRecordsetNew.
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 %both is object recordSet in file orders find records to %review status = 'REVIEW' end find find records to %pending status = 'PENDING' end find %both = %review:addRecordsetNew(%pending)
Of course, identical processing could be done with an Or in a Find statement.