Skip to main content

%XDBC.Gateway.ResultSet

abstract class %XDBC.Gateway.ResultSet extends %Library.RegisteredObject

FOR INTERNAL USE - do not invoke directly

Property Inventory

Method Inventory

Properties

property %CurrentResult as %RawString;
Holds oref of the most recently bound result set. This property is set automatically by %NextResult(). Note that %NextResult() is also invoked by %MoreResults(). Users should not ever set this property. This property is public for backward compatibility reasons.
Property methods: %CurrentResultGet(), %CurrentResultIsValid(), %CurrentResultSet()
property %Message as %Library.String (MAXLEN = 256);
%Message contains additional information about an error reported as a negative value in %SQLCODE. Additional information is not always available.
Property methods: %MessageDisplayToLogical(), %MessageGet(), %MessageIsValid(), %MessageLogicalToDisplay(), %MessageLogicalToOdbc(), %MessageNormalize(), %MessageSet()
property %OutputColumnCount as %Library.Integer [ InitialExpression = 0 ];
%OutputColumnCount is the number of columns defined as RETURNVALUE, INPUT-OUTPUT or OUTPUT (method return value, byref and output parameters) by an SQL invoked routine. This value is always zero unless the DYNAMIC_FUNCTION is CALL (%StatementType = 45).
Property methods: %OutputColumnCountDisplayToLogical(), %OutputColumnCountGet(), %OutputColumnCountIsValid(), %OutputColumnCountLogicalToDisplay(), %OutputColumnCountNormalize(), %OutputColumnCountSet()
property %ROWCOUNT as %Library.Integer;
Contains the number of rows affected by executing the statement.
It is the responsibility of the stored procedure author to explicitly set %ROWCOUNT.

For example:

&sql(UPDATE Person Set Name="Mo" WHERE Age > :number)
Set result.%SQLCODE=SQLCODE
Set result.%ROWCOUNT=%ROWCOUNT

Property methods: %ROWCOUNTDisplayToLogical(), %ROWCOUNTGet(), %ROWCOUNTIsValid(), %ROWCOUNTLogicalToDisplay(), %ROWCOUNTNormalize(), %ROWCOUNTSet()
property %ROWID as %Library.String);
The value of the %ROWID. This may or may not be relevant. It is primarily used when a dynamic INSERT statement has been executed. In that case, %ROWID contains the rowid of the last row inserted into the database by executing the statement.
Property methods: %ROWIDDisplayToLogical(), %ROWIDGet(), %ROWIDIsValid(), %ROWIDLogicalToDisplay(), %ROWIDLogicalToOdbc(), %ROWIDNormalize(), %ROWIDSet()
property %ResultColumnCount as %Library.Integer [ InitialExpression = 0 ];
%ResultColumnCount is the number of columns in the result set. This value is always zero unless the current result is a RESULTSET object (instance of %SQL.IResultSet) or a procedure context object (instance of %Library.IProcedureContext). For a CALL statement result, this value represents the column count of the result set currently bound using serial binding.
Property methods: %ResultColumnCountDisplayToLogical(), %ResultColumnCountGet(), %ResultColumnCountIsValid(), %ResultColumnCountLogicalToDisplay(), %ResultColumnCountNormalize(), %ResultColumnCountSet()
property %SQLCODE as %Library.Integer [ InitialExpression = 0 ];

%SQLCODE indicates whether or not the statement was executed successfully. If %SQLCODE is not negative (greater than or equal to zero) then the statement was successfully executed. Otherwise, the value of %SQLCODE contains the error code and the %Message property might contain more information about the error.

Property methods: %SQLCODEDisplayToLogical(), %SQLCODEGet(), %SQLCODEIsValid(), %SQLCODELogicalToDisplay(), %SQLCODENormalize(), %SQLCODESet()
property %StatementType as %Library.Integer;
%StatementType is the dynamic statement type number as assigned by SQL. Refer to %StatementTypeName for statement type values.
Property methods: %StatementTypeDisplayToLogical(), %StatementTypeGet(), %StatementTypeIsValid(), %StatementTypeLogicalToDisplay(), %StatementTypeNormalize(), %StatementTypeSet()
property %StatementTypeName as %Library.String [ Calculated ];

%StatementTypeName is the statement type name.

1SELECT
2INSERT (also 'INSERT OR UPDATE')
3UPDATE
4DELETE
5COMMIT
6ROLLBACK
7GRANT
8REVOKE
9CREATE TABLE
10ALTER TABLE
11DROP TABLE
12CREATE VIEW
13ALTER VIEW
14DROP VIEW
15CREATE INDEX
16ALTER INDEX (Not supported)
17DROP INDEX
18CREATE ROLE
19DROP ROLE
20SET TRANSACTION
21START TRANSACTION
22%INTRANSACTION
23%BEGTRANS (Alias for START TRANSACTION)
24%INTRANS (Alias for %INTRANSACTION)
25GET (Not supported)
26SET OPTION
27STATISTICS (UPDATE STATISTICS, not supported))
28%CHECKPRIV
29CREATE USER
30ALTER USER
31DROP USER
32%CHECKPRIV (SQL Admin Privilege)
33GRANT (SQL Admin Privilege)
34REVOKE (SQL Admin Privilege)
35CREATE FUNCTION
36CREATE METHOD
37CREATE PROCEDURE
38CREATE QUERY
39DROP FUNCTION
40DROP METHOD
41DROP PROCEDURE
42DROP QUERY
43CREATE TRIGGER
44DROP TRIGGER
45CALL
46SAVEPOINT
47LOCK TABLE
48UNLOCK TABLE
49CREATE DATABASE
50DROP DATABASE
51USE DATABASE
52TUNE TABLE
53DECLARE
54CREATE MODEL
55DROP MODEL
56TRAIN MODEL
57ALTER MODEL
58VALIDATE MODEL
59SET ML CONFIGURATION
60CREATE ML CONFIGURATION
61ALTER ML CONFIGURATION
62DROP ML CONFIGURATION
63FREEZE PLANS
64UNFREEZE PLANS
65PURGE
66BUILD INDEX
67LOAD
""Anything not list above
Property methods: %StatementTypeNameCompute(), %StatementTypeNameDisplayToLogical(), %StatementTypeNameGet(), %StatementTypeNameIsValid(), %StatementTypeNameLogicalToDisplay(), %StatementTypeNameLogicalToOdbc(), %StatementTypeNameNormalize(), %StatementTypeNameSQLCompute()

Methods

method %ConstructClone(deep As %Boolean = 0, ByRef cloned As %String, location As %String) as %RegisteredObject
Inherited description: Clone the current object to a new object. If deep is 1 then this does a deep copy which will also copy any subobjects and if deep is 0 then it will create another reference to any subobjects and increment the reference count appropriately. It returns the new cloned object.

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.

final method %GetClientMetadata(ByRef pMetadata As %RawString = "") as %Status
This method returns the rowtype metadata, serialized for transport to clients. Its structure is based on the value of the public variable '%protocol' at the time the result set is instantiated.
method %GetMetadata() as %SQL.StatementMetadata
Return metadata as a %SQL.StatementMetadata object
method %NormalizeObject() as %Status
Inherited description: Normalizes all of an object's property values by invoking the data type Normalize methods. Many data types may allow many different representations of the same value. Normalization converts a value to its cannonical, or normalized, form.
method %SerializeObject(ByRef serial As %Binary, partial As %Integer = 0) as %Status
Inherited description: This method retrieves all of the serial values for referenced objects and places them into the instance variables, Validates, Normalizes, and serializes the object (with a save of the persistent image if persistent).
This method is not meant to be called directly. It is called by %Save and by %GetSwizzleObject.
method %ValidateObject(force As %Library.Integer = 0, checkserial As %Library.Integer = 1) as %Status
Inherited description:

This method validates an object.

The %Save() method of a persistent class calls this method before filing any objects in the database. The %ValidateObject() of a referencing object can call it. You can also call it explicitly at any time.

%ValidateObject() does the following:

  1. If present, it will call a user-supplied %OnValidateObject() method.
  2. It checks if any required property values are missing.
  3. 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 %ValidateObject method for each object-valued embedded object property (properties whose type extend %SerialObject).
  4. If checkserial is 1, it forces the checking of any embedded object properties by calling their %ValidateObject method after swizzling this property.
  5. If checkserial is 2, it forces the checking of any collections of serial types by iterating over those collections and calling their %ValidateObject() method after swizzling this property, in addition to the validation that occurs when checkserial is 1.

%ValidateObject() returns a %Status indicating success or error. It is up to the caller to process the error value.

%ValidateObject() does not validate object-valued reference properties (properties whose type extends %Persistent) due to the possibility of circular dependencies between objects. The %Save() method of a persistent class automatically detects and handles circular references between objects. If you require the validation of reference properties, you can override this method in a subclass or call %Save() directly.

abstract method Close() as %Status
abstract method Get(colname As %RawString = "") as %Library.RawString
Returns the value of the column with the name colname in the current row of the result set.

If colname is not a valid column name, this method throws a error.

abstract method GetBuffer(ByRef moreBuffers As %Boolean) as %Library.List
Returns the current row buffer to the caller This method will refuse to return the buffer if there result set is already being iterated over by cursor (if the cursor is not before the start of the result set)
abstract method GetFetchSize() as %Integer
Retrieves the fetch size for this ResultSet object.
method GetMetaData() as %XDBC.Gateway.ResultSetMetaData
Return the result set metadata as a %XDBC.Gateway.ResultSetMetadata instance.
abstract method GetObject(columnIndex As %Integer) as %ObjectHandle
Gets the value of the designated column in the current row of this ResultSet object as %ObjectHandle
abstract method GetRow() as %Library.List
Advance to the next row in the result referenced by %ProcCursor. Returns 0 if the cursor is at the end of the result set. An optional argument contains a %Library.Status value on return. This %Status value indicates success or failure of the %GetRow() call. %SQLCODE is also set by %GetRow(). The row is returned in $List format by reference in the Row argument. If %SQLCODE'=0, Row will be null (""). This implementation is overridden by classes that implement the result set interface.
abstract method GetRows(rowCount As %Library.Integer) as %Library.Integer
Advance the next rowCount rows in the result referenced by %ProcCursor. Returns 0 if the cursor is at the end of the result set. Note, when 0 is returned, it is likely there are rows returned in the Rows array. An optional argument contains a %Library.Status value on return. This %Status value indicates success or failure of the %GetRows() call. %SQLCODE is also set by %GetRows. The rows are returned in an array of $List values in the Row array argument. If %SQLCODE'=0 for a row, that will be the end of the results.

For example, suppose rset.%GetRows(10,.tenrows,.sc) is called:
- If there are more then 10 rows remaining to be fetched from the result set, tenrows=10, tenrows(1)=$lb(first row's contents), ..., tenrows(10)=$lb(tenth row's contents), and %GetRows() will return 1.
- If there are 5 rows remaining to be fetched from the result set, tenrows=5, tenrows(1)=$lb(first row's contents), ..., tenrows(5)=$lb(fifth row's contents), and %GetRows() will return 0.
- If there are 0 rows remaining to be fetched from the result set, tenrows=0 and %GetRows() will return 0.

This implementation is overridden by classes that implement the result set interface.

Advance to the next row in the result referenced by %ProcCursor. Returns 0 if the cursor is at the end of the result set. An optional argument contains a %Library.Status value on return. This %Status value indicates success or failure of the %Next call. %SQLCODE is also set by %Next. This implementation is overridden by classes that implement the result set interface.
abstract method SetFetchSize(rows As %Integer)
Gives the driver a hint as to the number of rows that should be fetched from the database when more rows are needed for this ResultSet object.
abstract method WasNull() as %Boolean
Reports whether the last column read had a value of SQL NULL.

Inherited Members

Inherited Methods

Subclasses

FeedbackOpens in a new tab