Skip to main content

%Library.IResultSet

Class %Library.IResultSet Extends %RegisteredObject [ Abstract, ClientDataType = HANDLE, ClientName = ResultSet, OdbcType = RESULTSET, System = 2 ]

Interface for result sets.

A result set is a type of result returned by executing either a SELECT statement or a CALL statement. Please refer to %SQL.Statement and %SQL.StatementResult for more information on how to prepare dynamic SQL statements and how to process the results the of executing them.

Parameters​

COLUMNCOUNT;​

Parameter COLUMNCOUNT;

Properties​

%Message​

Property %Message As %Library.String;

%Metadata​

Property %Metadata As %Library.String(MAXLEN = "") [ MultiDimensional ];

%Objects​

Property %Objects As %Library.String(MAXLEN = "") [ Internal ];

%Objects is a list of column/extent pairs

%Parameters​

Property %Parameters As %Library.String(MAXLEN = "") [ Internal ];

%Parameters is a parameter metadata string containing the parameter name and type.

%rsmd​

Property %rsmd As %ResultSet.MetaData [ Internal, Private ];

%NextColumn​

Property %NextColumn As %RawString [ Private ];

%ResultColumnCount​

Property %ResultColumnCount As %Library.Integer [ ReadOnly ];

%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. For more information on result set sequences and dynamic result set binding refer to <>.

%ROWCOUNT​

Property %ROWCOUNT As %Library.Integer;

%ROWID​

Property %ROWID As %String(MAXLEN = "");

%RuntimeMode​

Property %RuntimeMode As %Library.String [ Private ];

This property is set on instantiation to the current value of $zu(115,5). It cannot be set directly by the user. It is to be used by the result set object to format column and parameter values. SQL based result sets using SELECTMODE=RUNTIME will use this value. The user can indirectly set this value by setting $zu(115,5) prior to calling %Prepare() to instantiate the result set. Possible values are:

  • 0 for LOGICAL mode.
  • 1 for ODBC mode.
  • 2 for DISPLAY mode.

%SQLCODE​

Property %SQLCODE As %Library.Integer;

%PrivateTables​

Property %PrivateTables As array Of %XSQL.DS.TempTable;

%PrivateTables is an array of private temporary table orefs used by this result set subscripted by temp table name.

%LTT​

Property %LTT As %RawString [ Internal, MultiDimensional ];

%LTT is an array of temporary table storage indexes subscripted by temp table name.

Methods​

%ResultColumnCountGet​

Method %ResultColumnCountGet() As %Integer [ CodeMode = expression ]

%Prepare​

ClassMethod %Prepare(queryId As %String(MAXLEN=""), ByRef %returnError As %SYSTEM.Error, %importPackages As %RawString = "", %args...) As %Library.IResultSet [ ServerOnly = 1 ]

%Prepare()

This method is different for each type of result set class. This method has two tasks. First, instantiate the correct concrete result set class. Think of the first parameter, queryId, as being an "index key value" that is used to lookup the correct query implementation. For non-cached (static) queries this is simply the name of the class that implements the query, i.e. the %IResultSet interface. The second task is to prepare the resulting object for data retrieval by the caller.

queryId This can be the concrete subclass of %IResultSet that implements the desired query. For dynamic cached results this value is generally the query text that can be parsed, a hashed value computed and the cached result implementation class looked up in the query cache index.

queryId can also be a or . If it is a then the result set returned is an instance of %Library.ResultSet that is bound to that query. If it is the name of a method Then that method is called, passing %args... to the method, and the first result set found in the context object (%sqlcontext) is returned.

%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. %args... Argument values to be passed to the query/method/class %Execute() method. Zero, one or more argument values can be passed.

%PrepareMetaData​

ClassMethod %PrepareMetaData(queryId As %String(MAXLEN=""), ByRef returnError As %SYSTEM.Error = "", importPackages As %RawString = "") As %ResultSet.MetaData

%PrepareMetaData is similar to %Prepare except that no result set is instantiated. This method returns an instance of %ResultSet.MetaData. 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.

queryId This can be the concrete subclass of %IResultSet that implements the desired query. For dynamic cached results this value is generally the query text that can be parsed, a hashed value computed and the cached result implementation class looked up in the query cache index.

queryId can also be a or . If it is a then the metadata is retrieved from the compiled query. If it is the name of a method then no metadata can be prepared since it requires the method to be executed.

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.

%CreateSnapshot​

Method %CreateSnapshot(storageOffset As %Integer, ByRef lastRow As %Integer, ByRef pRuntimeMode As %Integer = "", pStatic As %ResultSet.Static = "") As %Status

%CreateSnapshot(storageOffset,lastRow) Copy all rows from the current position to the end of the cursor into a temporary global. Fetch rowCount rows into a temporary global. If the rowCount is -1 then all rows are fetched

%Get​

Method %Get(colname As %String = "") As %Library.String [ Abstract ]

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.

%GetData​

Method %GetData(colnbr As %Integer = 0) As %Library.String [ Abstract ]

Returns the value of column colnbr in the current row of the result set.

%Next​

Method %Next(ByRef sc As %Library.Status = {$$$OK}) As %Library.Integer [ Abstract ]

Advance the result set cursor to the next row. Returns 0 if the cursor is at the end of the result set.

%SendODBC​

Method %SendODBC() As %Library.Integer [ Abstract, Internal ]

Fetch and send a series of rows for the ODBC/JDBC server. For internal use only.

%SendDelimitedRows​

Method %SendDelimitedRows(pMaxRows As %Integer = 0, pDelimiter As %String = "", ByRef pReturnCount As %Integer = 0) As %Status [ Abstract ]

Fetch and send a series of rows for continuous query client. For internal use only.

%SendObjects​

Method %SendObjects(pObjectCount As %Integer = 0, pLock As %Integer = 0) As %Library.Integer [ Internal ]

%SendObjects iterates over the rows in the result set and calls object export (quick load) on each column that is present in ..%Objects. For internal use only.

%CloseCursor​

Method %CloseCursor() As %Status [ CodeMode = expression, Private ]

This method is expected to be overridden by concrete subclasses

%OnClose​

Method %OnClose() As %Status [ CodeMode = expression, Private ]

%DispatchGetProperty​

Method %DispatchGetProperty(pProperty As %String(MAXLEN=255))

%DispatchSetProperty​

Method %DispatchSetProperty(pProperty As %String, pValue As %String) [ Final, Internal ]

Property dispatch method to catch references to virtual properties.
This should not be called directly.

%DispatchMethod​

Method %DispatchMethod(pMethod As %String, Args...)

%GetMetadata​

Method %GetMetadata() As %ResultSet.MetaData

%Print​

Method %Print(pDelimiter As %String = " ") As %Status

%Print()

Write the current row to the current device. An optional column delimiter can be specified. No formatting is applied other than writing pDelimiter between column values. This can be useful for exporting result set data to tab delimited files.

For example:

set sql = "select name,home_street,home_city,home_state,home_zip from sample.person" set rset = ##class(%ResultSet.SQL).%Prepare(.sql,.err,"") if '$Isobject(err) { set file="c:\temp\names.asv" open file:"WNS" use file while rset.%Next() { do rset.%Print($char(9)) } close file }

Example data:

Cornell,Ezra M.340 Franklin CourtSarasotaNY12866
Huff,Stephen A.548 Washington BlvdBrownfield CenterMD53436
Sands,Jeep Q.7298 Washington DriveXavierWY23685

%Display​

Method %Display(pDelimiter As %String = " ") As %Status

alias for %Print, implement %Display for new result set interface

%DisplayFormatted​

Method %DisplayFormatted(pFormat As %String = -1, ByRef pFileName As %String(MAXLEN="") = "", ByRef pMessages As %SQL.Manager.Messages = "", ByRef pFilesUsed As %String(MAXLEN="") = 0, pTranslateTable As %String(MAXLEN="") = "", pDelimiter As %String = {$c(9)})

Display the contents of the result object. If formatted display is available then format the results using the requested format and, if appropriate, open the formatted results using the host OS. The output is directed to one or more files and messages are placed in a result set object. All file names used are returned in an array.

Parameters​

NameDescription
pFormatThe format applied to the result content. This parameter is also used to determine the file name extension. Supported formats are: -1%Display() format 0XML 1HTML 2PDF (requires a renderer such as FOP) 99TXT 100CSV If pFormat is specified as any number not listed above then it will default to TXT. pFormat can also be specified as XML, HTML, PDF, TXT or CSV. NOTE: pFormat of CSV/100 is not a true comma separated value, but instead uses TAB separated values.
pFileNameThe base file name to be used to generate actual file names used for output. If no value is specified then a file name will be generated, using the TEMP folder defined for the InterSystems IRIS instance. This value is not expected to include an extension. An extension is added to this value to form the actual file used. Also, if nested results exist then a number is appended to the file name specified to produce a unique name for each result.
pMessagesInstance of a system result set class. If no value is passed then the system message result class is instantiated. This parameter is passed by reference. It is up to the caller to process the result set oref that is returned. pMessages.Count() returns the number of messages contained in the result set. pMessages.%Display() will display the messages on the current device. pMessages.%DisplayFormatted() is also implemented and can be used to display the messages using the selected format.
pFilesUsedThis pass-by-reference parameter will contain the number of files used to display the result content and the name of each file. pFilesUsed is the number of files and pFilesUsed(file_number) is the name of the file. The sequence of the files is the same sequence as the results are processed. For simple result objects, there is a single file. For context objects that can contain result set sequences, the results are output in the order they are returned and the files used are present in pFilesUsed in that same order.
pTranslateTableThis is the translate table used for the output files when the format is CSV or TXT. This parameter is optional.
pDelimiterThe delimiter to use between columns in the export file. This parameter is optional and defaults to tab character if not specified.