# MTSQLRowset

The SQL rowset allows for the creation of a rowset from a query specified in a query file. The user needs to initialize the rowset by specifying the relative configuration path to the query file. Once initialized, the queries in the query file may be executed by setting the query tag, adding any parameters and executing the query.

## Program ID

MTSQLRowset.MTSQLRowset.1

## MTSQLRowset Methods

AddParam | The AddParam method adds the specified parameter to the query string. All instances of the parameter tag will be replaced by the parameter value that is passed.
AddInputParameterToStoredProc | The AddInputParameterToStoredProc method adds the specified parameter to the stored procedure.
AddOutputParameterToStoredProc | The AddOutputParameterToStoredProc method adds the specified parameter to the stored procedure.
BeginDistributedTransaction | The BeginDistributedTransaction method begins a distributed transaction.
BeginTransaction | The BeginTransaction method begins a local transaction.
Clear | The Clear method clears the current rowset and the current query.
ClearQuery | The ClearQuery method clears the currently set query.
CommitTransaction | The CommitTransaction method commits a previously started transaction.
Execute | The Execute method gets the query that has been created and executes it using the database access layer.
ExecuteStoredProc | The ExecuteStoredProc method executes the stored procedure.
GetDBType | The GetDBType method gets the database type that is being used.
GetParameterFromStoredProc | The GetParameterFromStoredProc method gets the specified parameter from the stored procedure.
HydrateFromFile | Loads a rowset from an XML file.
HydrateFromString | Loads a rowset from an XML string.
HydrateFromXML | Loads a rowset from an IXMLDOMDocument object.
Init | The Init method initializes the rowset by initializing the connection to the database and by reading the query file from the specified configuration path.
InitializeForStoredProc | The InitializeForStoredProc method initializes the rowset for the specified stored procedure.
JoinDistributedTransaction | The JoinDistributedTransaction method joins a distributed transaction specified by the transaction cookie.
MoveFirst | The MoveFirst method moves the cursor to the first row of the rowset.
MoveLast | The MoveLast method moves the cursor to the last row of the rowset.
MoveNext | The MoveNext method moves the cursor to the next row of the rowset.
RollbackTransaction | The RollbackTransaction method rolls back a transaction.
SaveToFile | Saves the rowset to an XML file in the ADO XML format.
SetQueryTag | The SetQueryTag method sets the query tag in the MTSQLRowset.
UpdateConfigPath | The UpdateConfigPath method reads the query file from the specified directory and uses that query file for future queries.

## MTSQLRowset Properties

Count | The Count property gets the number of columns in the rowset.
CurrentPage | The CurrentPage property gets/sets the current page of the cursor in the rowset.
EOF | The EOF property gets the status of the rowset cursor.
Name | The Name property gets the name of the specified column of the rowset.
PageCount | The PageCount property gets/sets the number of pages in the rowset.
PageSize | The PageSize property gets/sets the page size value.
RecordCount | The RecordCount property gets the number of rows in the rowset.
Type | The Type property gets the type of the specified column of the rowset.
Value | The Value property gets the value of the specified column of the rowset.

## Example

Example to be provided in a future release of this online help system.

# Method Detail

## AddParam

The AddParam method adds the specified parameter to the query string. All instances of the parameter tag will be replaced by the parameter value that is passed.

### Visual Basic Syntax

Sub AddParam(apParamTag As String, aParam)

### C++ Syntax

HRESULT AddParam([in] BSTR apParamTag, [in] VARIANT aParam);

### Arguments

apParamTag

The name of the parameter.

aParam

The value of the parameter.

### Errors Raised

80020009 - AddParam() failed. Unable to add parameter.

80020009 - AddParam() failed. MTSQLRowset not initialized.

## AddInputParameterToStoredProc

The AddInputParameterToStoredProc method adds the specified parameter to the stored procedure.

### Visual Basic Syntax

Sub AddInputParameterToStoredProc(apParamName As String, aType As Long, aDirection As Long, aValue)

### C++ Syntax

HRESULT AddInputParameterToStoredProc(
[in] BSTR apParamName,
[in] long aType,
[in] long aDirection,
[in] VARIANT aValue);

### Arguments

apParamName

The name of the parameter.

aType

The type of the parameter.

aDirection

The direction of the parameter.

aValue

The value of the parameter.

### Errors Raised

80020009 - AddInputParameterToStoredProc() failed. Unable to add parameter to stored procedure.

## AddOutputParameterToStoredProc

The AddOutputParameterToStoredProc method adds the specified parameter to the stored procedure.

### Visual Basic Syntax

Sub AddOutputParameterToStoredProc(apParamName As String, aType As Long, aDirection As Long)

### C++ Syntax

HRESULT AddOutputParameterToStoredProc(
[in] BSTR apParamName,
[in] long aType,
[in] long aDirection);

### Arguments

apParamName

The name of the parameter.

aType

The type of the parameter.

aDirection

The direction of the parameter.

### Errors Raised

80020009 - AddOutputParameterToStoredProc() failed. Unable to add parameter to stored procedure.

## Init

The Init method initializes the rowset by initializing the connection to the database and by reading the query file from the specified configuration path.

### Visual Basic Syntax

Sub Init(apConfigPath As String)

### C++ Syntax

HRESULT Init([in] BSTR apConfigPath);

### Arguments

apConfigPath

The relative configuration path to the query file.

### Errors Raised

80020009 - Init() failed. Unable to allocate rowset.

80020009 - Init() failed. Unable to initialize query adapter.

80020009 - Init() failed. Unable to initialize dbaccess layer.

## Clear

The Clear method clears the current rowset and the current query.

### Visual Basic Syntax

Sub Clear()

### C++ Syntax

HRESULT Clear();

### Errors Raised

80020009 - Clear() failed. Unable to allocate rowset.

80020009 - Clear() failed. Unable to clear query adapter.

## HydrateFromFile

Loads a rowset from an XML file.

### Visual Basic Syntax

HydrateFromString(xmlStr As String)

### C++ Syntax

HRESULT HydrateFromString([in] BSTR xmlStr);

## HydrateFromString

Loads a rowset from an XML string.

### Visual Basic Syntax

HydrateFromFile(filename As String)

### C++ Syntax

HRESULT HydrateFromFile([in] BSTR filename);

## HydrateFromXML

Loads a rowset from an IXMLDOMDocument object.

### Visual Basic Syntax

HydrateFromXML

### C++ Syntax

HRESULT HydrateFromXML([in] IDispatch* pDisp);

## SetQueryTag

The SetQueryTag method sets the query tag in the MTSQLRowset.

### Visual Basic Syntax

Sub SetQueryTag(apQueryTag As String)

### C++ Syntax

HRESULT SetQueryTag([in] BSTR apQueryTag);

### Arguments

apQueryTag

The query tag to set.

### Errors Raised

80020009 - SetQueryTag() failed. Unable to set the query tag.

80020009 - SetQueryTag() failed. MTSQLRowset not initialized.

## MoveNext

The MoveNext method moves the cursor to the next row of the rowset.

### Visual Basic Syntax

Sub MoveNext()

### C++ Syntax

HRESULT MoveNext();

### Errors Raised

0xE1500004L - No rows are present in the rowset.

## MoveFirst

The MoveFirst method moves the cursor to the first row of the rowset.

### Visual Basic Syntax

Sub MoveFirst()

### C++ Syntax

HRESULT MoveFirst();

### Errors Raised

0xE1500004L - No rows are present in the rowset.

## MoveLast

The MoveLast method moves the cursor to the last row of the rowset.

### Visual Basic Syntax

Sub MoveLast()

### C++ Syntax

HRESULT MoveLast();

### Errors Raised

0xE1500004L - No rows are present in the rowset.

## Execute

The Execute method gets the query that has been created and executes it using the database access layer.

### Visual Basic Syntax

Sub Execute()

### C++ Syntax

HRESULT Execute();

### Errors Raised

80020009 - Execute() failed. Unable to get query.

80020009 - Execute() failed. Unable to execute query.

80020009 - Execute() failed. MTSQLRowset not initialized.

## BeginTransaction

The BeginTransaction method begins a local transaction.

### Visual Basic Syntax

Sub BeginTransaction()

### C++ Syntax

HRESULT BeginTransaction();

### Arguments

apParamTag

The name of the parameter.

aParam

The value of the parameter.

### Errors Raised

80020009 - BeginTransaction() failed. Unable to begin transaction.

## CommitTransaction

The CommitTransaction method commits a previously started transaction.

### Visual Basic Syntax

Sub CommitTransaction()

### C++ Syntax

HRESULT CommitTransaction();

### Errors Raised

80020009 - CommitTransaction() failed. Unable to commit transaction.

## RollbackTransaction

The RollbackTransaction method rolls back a transaction.

### Visual Basic Syntax

Sub RollbackTransaction()

### C++ Syntax

HRESULT RollbackTransaction();

### Errors Raised

80020009 - RollbackTransaction() failed. Unable to rollback transaction.

## ClearQuery

The ClearQuery method clears the currently set query.

### Visual Basic Syntax

Sub ClearQuery()

### C++ Syntax

HRESULT ClearQuery();

### Errors Raised

80020009 - ClearQuery() failed. Unable to clear query adapter.

## UpdateConfigPath

The UpdateConfigPath method reads the query file from the specified directory and uses that query file for future queries.

### Visual Basic Syntax

Sub UpdateConfigPath(apConfigPath As String)

### C++ Syntax

HRESULT UpdateConfigPath([in] BSTR apConfigPath);

### Arguments

apConfigPath

The relative configuration path.

### Errors Raised

80020009 - UpdateConfigPath() failed. Unable to initialize query adapter.

## InitializeForStoredProc

The InitializeForStoredProc method initializes the rowset for the specified stored procedure.

### Visual Basic Syntax

Sub InitializeForStoredProc(apStoredProcName As String)

### C++ Syntax

HRESULT InitializeForStoredProc([in] BSTR apStoredProcName);

### Arguments

apStoredProc

The stored procedure name.

### Errors Raised

80020009 - InitializeForStoredProc() failed. Unable to initialize rowset for stored procedure.

## ExecuteStoredProc

The ExecuteStoredProc method executes the stored procedure.

### Visual Basic Syntax

Sub ExecuteStoredProc()

### C++ Syntax

HRESULT ExecuteStoredProc();

### Errors Raised

80020009 - ExecuteStoredProc() failed.

## GetParameterFromStoredProc

The GetParameterFromStoredProc method gets the specified parameter from the stored procedure.

### Visual Basic Syntax

Function GetParameterFromStoredProc(apParamName As String)

### C++ Syntax

HRESULT GetParameterFromStoredProc([in] BSTR apParamName, [out,retval] VARIANT *apValue);

### Arguments

apParamName

The parameter name.

### Return Value

apValue

The value of the parameter.

### Errors Raised

80020009 - GetParameterFromStoredProc() failed. Unable to get parameter from stored procedure.

## BeginDistributedTransaction

The BeginDistributedTransaction method begins a distributed transaction.

### Visual Basic Syntax

Sub BeginDistributedTransaction()

### C++ Syntax

HRESULT BeginDistributedTransaction();

### Errors Raised

80020009 - BeginDistributedTransaction() failed. Unable to begin distributed transaction.

## JoinDistributedTransaction

The JoinDistributedTransaction method joins a distributed transaction specified by the transaction cookie.

### Visual Basic Syntax

Sub JoinDistributedTransaction(transactioncookie As String)

### C++ Syntax

HRESULT JoinDistributedTransaction([in] BSTR transactioncookie);

### Arguments

transactioncookie

The transaction cookie of the transaction to join.

### Errors Raised

80020009 - JoinDistributedTransaction() failed. Unable to join Distributed transaction.

## GetDBType

The GetDBType method gets the database type that is being used.

### Visual Basic Syntax

Function GetDBType() As String

### C++ Syntax

HRESULT GetDBType([out,retval] BSTR *apDBType);

### Return Value

apDBType

The database type.

### Errors Raised

80020009 - JoinDistributedTransaction() failed. Unable to join Distributed transaction.

## SaveToFile

Saves the rowset to an XML file in the ADO XML format.

### Visual Basic Syntax

SaveToFile(aFilename As String)

### C++ Syntax

HRESULT SaveToFile([in] BSTR aFileName);

# Property Detail

## Count

The Count property gets the number of columns in the rowset.

This property is read-only.

### Visual Basic Syntax

Property Count As Long

### C++ Syntax

HRESULT Count([out, retval] long *pVal);

### Return Value

pVal

The number of columns in the rowset.

### Errors Raised

0xE1500004L - No rows are present in the rowset.

## Name

The Name property gets the name of the specified column of the rowset.

This is a read-only property.

### Visual Basic Syntax

Property Value (vtIndex As Variant) as String

### C++ Syntax

HRESULT Name([in] VARIANT vtIndex, [out, retval] BSTR *pVal);

### Arguments

vtIndex

The specified column of the rowset.

### Return Value

pVal

The name of the column.

### Errors Raised

0xE1500004L - No rows are present in the rowset.

## Value

The Value property gets the value of the specified column of the rowset.

This is a read-only property.

NOTE: Since VBScript supports Variants containing decimals but does not support any numeric computation on them, MetraTech provides the MTDecimalOps COM object that you can use with VBScript components to perform numerical operations and return numeric values that preserve the same high level of numerical precision as those returned with C++ and Visual Basic components.

### Visual Basic Syntax

Property Value (vtIndex As Variant) as Variant

### C++ Syntax

HRESULT Value([in] VARIANT vtIndex, [out, retval] VARIANT *pVal);

### Arguments

vtIndex

The specified column of the rowset.

### Return Value

pVal

The name of the column.

### Errors Raised

0xE1500004L - No rows are present in the rowset.

## Type

The Type property gets the type of the specified column of the rowset.

This is a read-only property.

### Visual Basic Syntax

Property Type(vtIndex) As String

### C++ Syntax

HRESULT Type([in] VARIANT vtIndex, [out, retval] BSTR *pVal);

### Arguments

vtIndex

The specified column of the rowset.

### Return Value

pVal

The name of the column.

### Errors Raised

0xE1500004L - Unable to get the type of a column in the rowset.

## RecordCount

The RecordCount property gets the number of rows in the rowset.

This is a read-only property.

### Visual Basic Syntax

Property RecordCount As Long

### C++ Syntax

HRESULT RecordCount([out, retval] long *pVal);

### Return Value

pVal

The number of rows.

### Errors Raised

0xE1500004L - No rows are present in the rowset.

## EOF

The EOF property gets the status of the rowset cursor.

This is a read-only property.

### Visual Basic Syntax

Property EOF As Variant

### C++ Syntax

HRESULT EOF([out, retval] VARIANT *pVal);

### Return Value

pVal

The status of the rowset cursor.

### Errors Raised

0xE1500004L - No rows are present in the rowset.

## PageSize

The PageSize property gets/sets the page size value.

This property is read/writeable.

### Visual Basic Syntax

Property PageSize As Long

### C++ Syntax

HRESULT PageSize([in] long newVal);

HRESULT PageSize([out, retval] long *pVal);

### Arguments

newVal

The page size to set for the rowset.

### Return Value

The current page size of the rowset.

## PageCount

The PageCount property gets/sets the number of pages in the rowset.

This is a read-only property.

### Visual Basic Syntax

Property PageCount As Long

### C++ Syntax

HRESULT PageCount([out, retval] long *pVal);

### Return Value

pVal

The number of pages in the rowset.

## CurrentPage

The CurrentPage property gets/sets the current page of the cursor in the rowset.

This property is read/writeable.

### Visual Basic Syntax

Property CurrentPage As Long

### C++ Syntax

HRESULT CurrentPage([in] long newVal);

HRESULT CurrentPage([out, retval] long *pVal);

### Arguments

newVal

The page to set.

pVal

The current page of the cursor in the rowset.

### Return Value

The current page of the cursor in the rowset.