CustomResultSet Class Reference

Inheritance diagram for CustomResultSet:

Collaboration diagram for CustomResultSet:

Public Member Functions
_.Library.Status	CloseCursor ()
	Implement CloseCursor to clean up any temporary structures that are used by the custom. More...
_.Library.Status	OnClose ()
	This callback method is invoked by the <METHOD>Close</METHOD> method to. More...
_.Library.Status	OpenCursor ()
	Implement code to open the cursor here. More...
Public Member Functions inherited from RegisteredObject
_.Library.Status	OnAddToSaveSet (_.Library.Integer depth, _.Library.Integer insert, _.Library.Integer callcount)
	This callback method is invoked when the current object is added to the SaveSet,. More...
_.Library.Status	OnConstructClone (_.Library.RegisteredObject object, _.Library.Boolean deep, _.Library.String cloned)
	This callback method is invoked by the <METHOD>ConstructClone</METHOD> method to. More...
_.Library.Status	OnNew ()
	This callback method is invoked by the <METHOD>New</METHOD> method to. More...
_.Library.Status	OnValidateObject ()
	This callback method is invoked by the <METHOD>ValidateObject</METHOD> method to. More...

Static Public Attributes
	statementactual
Static Public Attributes inherited from IResultSet
	StatementIndexHash
	Hash of associated statement index entry.
Static Public Attributes inherited from RegisteredObject
	CAPTION = None
	Optional name used by the Form Wizard for a class when generating forms. More...
	JAVATYPE = None
	The Java type to be used when exported.
	PROPERTYVALIDATION = None
	This parameter controls the default validation behavior for the object. More...

Private Member Functions
_.Library.String	Get (_.Library.String colname)
	Returns the value of the column with the name colname in the current row of the result set. More...
_.Library.String	GetData (_.Library.Integer colnbr)
	GetData(<column number>) More...
_.Library.Status	OnNew (_.Library.Integer pSelectMode)
	OnNew is called by the constructor. More...
_.Library.Integer	SendODBC ()
	Fetch and send a series of rows for the ODBC/JDBC server. More...

Static Private Member Functions
_.Library.Status	GetSerializedMetadata (_.Library.RawString pMetadata)
	Get the serialized Metadata property value.

Detailed Description

SQL.CustomResultSet is the root class for custom result sets. You can extend this class to implement custom result sets that can be instantiated and returned as dynamic result sets by a stored procedure. Custom result sets are similar to queries with TYPE = Library.Query. Subclassing SQL.CustomResultSet has a few advantages over custom queries. Result sets are more efficient when interacting with the server. The metadata for a result set is constructed from the class definition so there is never a need for ROWSPEC. Also, SQL.CustomResultSet defines a more object-oriented interface.

You can make custom result sets available to dynamic SQL by implementing a class method projected as a stored procedure. An example of a custom result set is available in the SAMPLES database. There is also an example of creating a stored procedure that returns an instance of a custom result set to the caller. Such a procedure can be invoked using the embedded or dynamic CALL statement.

When subclassing SQL.CustomResultSet, there are a few steps that you must follow in order to produce a working result set.

1. Define properties that correspond to each column in the result row. If the property type is swizzleable then any direct access to the property will trigger swizzling. Get, GetData and the various Send methods will not swizzle the object.
   
   Note: Properties inherited from a system superclass are not considered to be part of the row.

1. Define any private properties needed to maintain the current state of the result set.

1. Override and implement OpenCursor. Code in this method initializes the result iterator and prepares the data for return. It also reports any errors encountered during execution by setting SQLCODE and Message.

1. Override and implement Next. Code in this method retrieves the next row and sets the properties corresponding to columns in the row to the appropriate value. If no row is found this method returns 0, otherwise it returns 1. This method must also set value of the ROWCOUNT property.

1. Override and implement CloseCursor. This is only necessary if you need to perform some clean up. CloseCursor is called when the object is destructed.

Member Function Documentation

CloseCursor()

_.Library.Status CloseCursor

(

)

Implement CloseCursor to clean up any temporary structures that are used by the custom.

result such as temporary globals, etc. This method is invoked by the object destructor.

            method CloseCursor() as Library.Status [ private ]
            {
                &sql(close myCursor)
                    kill ^||mytempglobal
                quit $$$OK
            }
    

Reimplemented in ResultSet.

Get()

_.Library.String Get ( _.Library.String  colname )

private

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 <PROPERTY DOES NOT EXIST> error.

Reimplemented from StatementResult.

GetData()

_.Library.String GetData ( _.Library.Integer  colnbr )

private

GetData(<column number>)

        Returns the value of the column referenced by <var>colnbr</var>. Object values are not swizzled automatically.

Reimplemented from StatementResult.

OnClose()

_.Library.Status OnClose

(

)

This callback method is invoked by the <METHOD>Close</METHOD> method to.

provide notification that the current object is being closed.

The return value of this method is ignored.

Reimplemented from RegisteredObject.

OnNew()

_.Library.Status OnNew ( _.Library.Integer  pSelectMode )

private

OnNew is called by the constructor.

It supports a variable number of arguments passed by value. The first argument

is the runtime SELECTMODE value and it defaults to $system.SQL.GetSelectMode(). This method is generated as final. It invokes the user implemented OpenCursor method. Any formal arguments defined by the OpenCursor method will be added to the formal spec of OnNew. Actual values for these arguments can be specified when calling New(). Errors are reported by setting ..SQLCODE, ..Message.

OpenCursor()

_.Library.Status OpenCursor

(

)

Implement code to open the cursor here.

You may also define new formal arguments. Any arguments defined

will be automatically added to the constructor interface and callers can specify actual arguments in the call to New().

            method OpenCursor(pBeginDate as Date = "", pEndDate as Date = "") as Library.Status [ private ]
            {
                set ..BeginDate = pBeginDate
                set ..EndDate = $Select(pEndDate'="":pEndDate,1:$H)
                quit $$$OK
            }
    

Given the above example implementation of OpenCursor, the following is a valid call to instantiate a new instance.

            set tResult = ##class(MyCustom.ResultSet).New(,$H-30,$H-10)
    

To report an error from OpenCursor just set ..SQLCODE and Message to appropriate values. To report no rows found, set SQLCODE to 100. Errors are indicated by negative ..SQLCODE values.

Reimplemented in Messages.

SendODBC()

_.Library.Integer SendODBC ( )

private

Fetch and send a series of rows for the ODBC/JDBC server.

For internal use only.

Member Data Documentation

statementactual

statementactual

static

SQL.CustomResultSet is the root class for custom result sets. You can extend this class to implement custom result sets that can be instantiated and returned as dynamic result sets by a stored procedure. Custom result sets are similar to queries with TYPE = Library.Query. Subclassing SQL.CustomResultSet has a few advantages over custom queries. Result sets are more efficient when interacting with the server. The metadata for a result set is constructed from the class definition so there is never a need for ROWSPEC. Also, SQL.CustomResultSet defines a more object-oriented interface.

You can make custom result sets available to dynamic SQL by implementing a class method projected as a stored procedure. An example of a custom result set is available in the SAMPLES database. There is also an example of creating a stored procedure that returns an instance of a custom result set to the caller. Such a procedure can be invoked using the embedded or dynamic CALL statement.

When subclassing SQL.CustomResultSet, there are a few steps that you must follow in order to produce a working result set.

1. Define properties that correspond to each column in the result row. If the property type is swizzleable then any direct access to the property will trigger swizzling. Get, GetData and the various Send methods will not swizzle the object.
   
   Note: Properties inherited from a system superclass are not considered to be part of the row.

1. Define any private properties needed to maintain the current state of the result set.

1. Override and implement OpenCursor. Code in this method initializes the result iterator and prepares the data for return. It also reports any errors encountered during execution by setting SQLCODE and Message.

1. Override and implement Next. Code in this method retrieves the next row and sets the properties corresponding to columns in the row to the appropriate value. If no row is found this method returns 0, otherwise it returns 1. This method must also set value of the ROWCOUNT property.

1. Override and implement CloseCursor. This is only necessary if you need to perform some clean up. CloseCursor is called when the object is destructed.