Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

%Library.RemoteResultSet

class %Library.RemoteResultSet extends %Library.AbstractResultSet

The %RemoteResultSet class provides a way to use class queries from a different namespace from within a Caché ObjectScript application. It is similar in operation to the ResultSet objects provides with the ActiveX and Java bindings. It uses C++ binding and therefore the C++ binding library must be installed.

You can use a %RemoteResultSet object as follows: 

  ; Display the results of the Person class' ByName query to the console.
  Set rs=##class(%RemoteResultSet).%New("Sample.Person:ByName")
  s rs.UserName="_system"
  s rs.Password="sys"
  s rs.ConnectionString="localhost[1972]:SAMPLES"
  w rs.Prepare()
  w rs.Execute("S")
  While rs.Next() {
  	Write rs.GetDataByName("Name"),!
  }

Note you can bind a %ResultSet object to a query by either a) setting the ClassName and QueryName properties or b) passing a string containing the class name and query name (separated by a :) to the %New method: 

  Set result=##class(%ResultSet).%New("Person:ByName")

Dynamic SQL

You can use the %ResultSet class to execute dynamic SQL queries using the system-provided %DynamicQuery:SQL query. In this case, use the Prepare() method to supply the text of the query. For example: 
  Set result=##class(%ResultSet).%New("%DynamicQuery:SQL")
  
  Do result.Prepare("SELECT ID, Name, Salary FROM Employee WHERE Salary > ?")
  Do result.Execute(10000)
  While result.Next() {
  	Write result.Data("Name"),result.Data("Salary"),!
  }
Dynamic SQL queries are cached in the same query cache as used by Caché ODBC and JDBC. This means that repeated calls to the same dynamic SQL query do not incur any additional query preparation and optimization overhead. You can view and manage this cache using the Caché SQL Manager.

Property Inventory

Method Inventory

Properties

property ClassName as %CacheString;
The name of the class containing the query to run.
Property methods: ClassNameGet(), ClassNameIsValid()
property ConnectionString as %String;
Property methods: ConnectionStringDisplayToLogical(), ConnectionStringGet(), ConnectionStringIsValid(), ConnectionStringLogicalToDisplay(), ConnectionStringLogicalToOdbc(), ConnectionStringNormalize(), ConnectionStringSet()
property Data as %String [ MultiDimensional ];
Used to store the data returned from the resultset by column name. This can be accessed directly for more performance than the Get() and GetDataByName() as it avoids a method call. For example code that said: 
  While result.Next() {
  	Write result.Get("Name"),result.Get("Salary"),!
  }
  
  ; Becomes this faster code
  
  While result.Next() {
  	Write $get(result.Data("Name")),$get(result.Data("Salary")),!
  }
Note that as this 'Data' property is multidimensional if there is no such column name as 'Salary' you will get an UNDEFINED error without the $get around it. If there are two columns with the same name in the result set then the second one will be the one referenced by the 'Data' property. If you need to refer to both of them use the GetData() and give the position of the column you want.
Property methods: DataDisplayToLogical(), DataGet(), DataIsValid(), DataLogicalToDisplay(), DataLogicalToOdbc(), DataNormalize(), DataSet()
property ErrorMsg as %String;
Property methods: ErrorMsgDisplayToLogical(), ErrorMsgGet(), ErrorMsgIsValid(), ErrorMsgLogicalToDisplay(), ErrorMsgLogicalToOdbc(), ErrorMsgNormalize(), ErrorMsgSet()
property Password as %String;
Property methods: PasswordDisplayToLogical(), PasswordGet(), PasswordIsValid(), PasswordLogicalToDisplay(), PasswordLogicalToOdbc(), PasswordNormalize(), PasswordSet()
property QueryName as %CacheString;
The name of the query to run.
Property methods: QueryNameGet(), QueryNameIsValid(), QueryNameSet()
property RuntimeMode as %String;
Inherited description: Use this method to set the SQL runtime mode for the query to be executed. Setting the runtime mode for this ResultSet does not permanently change the $zu(115,5) value. Possible values mode are:
  • 0 for LOGICAL mode.
  • 1 for ODBC mode.
  • 2 for DISPLAY mode.
  • "" to use the process wide $zu(115,5) value.
Property methods: RuntimeModeDisplayToLogical(), RuntimeModeGet(), RuntimeModeIsValid(), RuntimeModeLogicalToDisplay(), RuntimeModeLogicalToOdbc(), RuntimeModeNormalize(), RuntimeModeSet()
property UserName as %String;
Property methods: UserNameDisplayToLogical(), UserNameGet(), UserNameIsValid(), UserNameLogicalToDisplay(), UserNameLogicalToOdbc(), UserNameNormalize(), UserNameSet()

Methods

method %Next(ByRef sc As %Status) as %Integer
Inherited description: Advance the result set cursor to the next row. Returns 0 if the cursor is at the end of the result set.
method %ResultColumnCountGet() as %Integer
method ClassNameSet(class As %String) as %Status
method Close() as %Status
Inherited description: Closes the current result set cursor.
method ContainsId() as %Integer
Inherited description: If the current query contains an object Id (based on the CONTAINSID parameter being set), return the column position of the object Id. Otherwise return 0.
method Execute(p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11, p12, p13, p14, p15, p16) as %Status
Inherited description: Executes the current query.

The arguments p1... supply the value of any parameters the query may have.

method Get(name As %String) as %String
Inherited description: Returns the value of the column with the name name in the current row of the result set.

If name is not a valid column name, this method returns an empty string. Look at updating the code to use the Data multidimensional property to access the fields faster than using this method call.

method GetColumnCount() as %Integer
Inherited description: Returns the number of columns in the result set.
method GetColumnDisplaySize(n As %Integer) as %String
method GetColumnHeader(n As %Integer) as %String
Inherited description: Returns the column header for column n in the result set.
method GetColumnIsMoney(n As %Integer) as %String
method GetColumnName(n As %Integer) as %String
Inherited description: Returns the name of column n in the result set.
method GetColumnPrecision(n As %Integer) as %String
method GetColumnScale(n As %Integer) as %String
method GetData(n As %Integer) as %String
Inherited description: Returns the value of column n in the current row of the result set.
method GetDataByName(name As %String) as %String
Inherited description: Returns the value of the column with the name name in the current row of the result set.

If name is not a valid column name, this method returns an empty string.

Note: this method has been superceded by the equivalent Get() method.

method GetExtent() as %String
Inherited description: The name of the extent that this query will return Id values from (based on the EXTENT parameter being set). Only returns a value if the query contains Id values.
method GetObject() as %RegisteredObject
Inherited description: If this query returns the object Id then return the oref you get from opening an object with this id.
method GetParamCount() as %Integer
Inherited description: Returns the number of input parameters for the current query.
method GetParamName(n As %Integer) as %String
Inherited description: Returns the name of input parameter n for the current query.
Inherited description: Advance the result set cursor to the next row. Returns 0 if the cursor is at the end of the result set.
method Prepare(p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11, p12, p13, p14, p15, p16) as %Status
Inherited description: Use this method with dynamic queries to provide the query to be executed. In the case of the %DynamicQuery:SQL query, p1 is a string containing an SQL query. The query may contain parameters represented by ? characters within the query. The values of any parameters are supplied via the Execute() method. For example: 
  Set result=##class(%ResultSet).%New("%DynamicQuery:SQL")
  
  Do result.Prepare("SELECT Name,City FROM Person WHERE Name %STARTSWITH ? AND City = ?")
  
  Do result.Execute("A","Boston")
  While result.Next() {
  Write result.Data("Name"),result.Data("City"),!
  }
method QueryIsValid() as %Integer
Inherited description: Returns true (1) if the ClassName and QueryName properties of this %ResultSet object refer to a valid class query. Otherwise it returns false (0).
classmethod UnloadDLL()
method WasError() as %Integer

Inherited Members

Inherited Properties

Inherited Methods

FeedbackOpens in a new tab