This class has been superseded. It will remain for compatibility with existing code and samples. We recommend using %SQL.Statement.
Cached ResultSet based on an SQL statement. This class only supports the SELECT statement.
Note that even if deep=0 when you clone a parent object in a parent child relationship or a one object of a one to many relationship then it will construct clones of all the child/many objects. This is because a child/many object can only point at a single parent and so if we did not create a clone of these then you would have a relationship with zero items in it. If you really just want to clone the object without these child/many objects then pass deep=-1 to this method.
After the clone is constructed it will call %OnConstructClone(object,deep,.cloned) on the clone if it is defined so that you can perform any additional steps e.g. taking out a lock. This works just the same way as %OnNew() does.
The object is the oref of the original object that was cloned. The cloned array is just used internally when doing a deep clone to prevent recursive loops, do not pass anything in at all for this parameter on the initial call. If you write a %OnConstructClone and from here you wish to call %ConstructClone on another object pass in the cloned array, e.g. 'Do oref.%ConstructClone(1,.cloned)' so that it can prevent recursive loops.
The location is used internally to pass the new location for stream objects.
For %ResultSet.SQL, the arguments are:
|sqlStatement (byref)||the SQL Select statement, either as a counted array or as a $$$NL delimited string;|
|returnError (byref)||if an error occurs, this will be an oref of an instance of %SYSTEM.Error. That object has a Status property as well as methods to convert that status value into message id's and text from other error domains. If no error is detected during %Prepare then returnError is $$$NULLOREF;|
|%importPackages||this is a $list of package names to be used to resolve any unqualified names in the SELECT statement.|
For example, SELECT %ID from MyTable
If %importPackages contains "Sample" then the schema associated with the Sample package would be used to qualify MyTable.
|%args...||variable number of argument values that correspond to '?' parameters contained in the sqlStatement.|
This method returns an instance of %Library.IResultSet in the generic case. In the case of %ResultSet.SQL, an instance of %ResultSet.SQL is returned.
This method constructs a SaveSet containing objects that are part of the current %Save() for persistent classes or %GetSwizzleObject for serial classes. A queue of objects to be saved or serialized is also constructed. Only modified objects are included in the save queue. The value (OID or serial value in OID form) of each object is also placed in the SaveSet.
%PrepareMetaData is similar to %Prepare except that no result set is instantiated. This method returns a %ResultSet.MetaData object. Be aware that the implementation of this method might cause the result set to be instantiated but that is up to the result set class itself and no result set is actually returned by this method - only metadata.
|query||This is the SQL SELECT statement|
|returnError||If an error occurs this is returned by reference and is a %SYSTEM.Error object with properties set to describe information about the error. %returnError.Status contains the %Status value.|
|importPackages||This is a comma delimited list of packages to import. This is only relevant if the result set implementation is generated and the query source might include unqualified names. The import packages list is used to resolve package/schema names for unqualified names.|
This method is not meant to be called directly. It is called by %Save and by %GetSwizzleObject.
%ValidateObject() does the following:
- It tests if any required property values are missing.
- If the PROPERTYVALIDATION class parameter is set to ValidateOnSave, it validates each non-null property value by calling the property method IsValid on each literal property and the object's %ValidateObject method for object-valued properties.
- If present, it will call a user-supplied %OnValidateObject() method.
If any of these tests fail, %ValidateObject() immediately returns an error value. It is up to the caller of %ValidateObject to process the error value.unused is not used. checkserial will force the checking of any serial properties by calling their %ValidateObject methods after swizzling this property.
Returns a %Status value indicating success or failure.