ArchestrA

SQLData Script
Library User’s Guide

12/1/15
All rights reserved. No part of this documentation shall be reproduced, stored in a retrieval system, or
transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without the
prior written permission of Schneider Electric Software, LLC. No copyright or patent liability is assumed
with respect to the use of the information contained herein. Although every precaution has been taken in
the preparation of this documentation, the publisher and the author assume no responsibility for errors or
omissions. Neither is any liability assumed for damages resulting from the use of the information
contained herein.
The information in this documentation is subject to change without notice and does not represent a
commitment on the part of Schneider Electric Software, LLC. The software described in this
documentation is furnished under a license agreement. This software may be used or copied only in
accordance with such license agreement.

© 2015 Schneider Electric Software, LLC. All rights reserved.

Schneider Electric Software, LLC

26561 Rancho Parkway South
Lake Forest, CA 92630 U.S.A.
(949) 727-3200
http://software.schneider-electric.com
For comments or suggestions about the product documentation, send an e-mail message to
ProductDocumentationComments@schneider-electric.com.

ArchestrA, Avantis, DYNSIM, EYESIM, Foxboro, Foxboro Evo, I/A Series, InBatch, InduSoft, IntelaTrac,
InTouch, PIPEPHASE, PRO/II, PROVISION, ROMeo, Schneider Electric, SIM4ME, SimCentral, SimSci,
Skelta, SmartGlance, Spiral Software, VISUAL FLARE, WindowMaker, WindowViewer, and
Wonderware are trademarks of Schneider Electric SE, its subsidiaries, and affiliated companies. An
extensive listing of Schneider Electric Software, LLC trademarks can be found at:
http://software.schneider-electric.com/legal/trademarks/. All other brands may be trademarks of their
respective owners.
 3

Contents

Welcome .................................................... 9
Documentation Conventions .......................................................... 9
Technical Support .......................................................................... 10

Chapter 1 Using the SQLData Script Library ................. 11

Importing and Accessing the SQLData
Script Library .............................................................................. 12
SQLData Script Library Interface ................................................ 12
SQLData Script Library Architecture ...................................... 13
SQLData Script Library Work Flow ............................................ 15
Creating a Connection Object with a Command ...................... 15
Creating a Connection Object with a Transaction .................... 15
Specifying Connection Strings .................................................... 16
Connecting to a SQL Server Data Source ............................. 16
Connecting to an Oracle Data Source .................................... 17
Connecting to Microsoft Access through
OLEDB ................................................................................. 17
Connecting to Microsoft Excel through OLEDB ................... 17
Example Scripts ............................................................................. 17
Overview of Sample Scripts ....................................................... 17
Detailed Description of Sample Scripts ..................................... 18
Asynchronous Command Script ................................................ 19
Query Script Configuration ................................................... 20

SQLData Script Library User’s Guide

4 Contents

Process Script Configuration ................................................. 20

Query Script Code .................................................................. 20
Process Script Code ................................................................ 21
Synchronous Transaction Script ............................................... 22
QueryandProcess Script Code ............................................... 23

Chapter 2 aaDBAccess Object..................................... 27

aaDBAccess Object ........................................................................ 27
Creating a Reusable Connection Object ................................... 27
Creating a Unique Connection Object ...................................... 28
Differences Between CreateConnection()
and GetConnection() .............................................................. 28
Working with Connections ........................................................ 28
Windows Integrated Security ................................................ 29
Windows Account ................................................................... 29
SQL Server Authentication .................................................... 30
Methods .......................................................................................... 30
CreateConnection() ..................................................................... 30
Connecting to Databases Other Than
SQL Server ............................................................................ 31
GetCommand() ............................................................................ 31
GetConnection() ........................................................................... 31
Authentication ......................................................................... 33
Connecting to Databases Other Than
SQL Server ............................................................................ 33
GetDiagnostics() .......................................................................... 34
GetTransaction() ......................................................................... 34
LogDiagnostics() .......................................................................... 34
RemoveCommand() ..................................................................... 35
RemoveTransaction() .................................................................. 35
ResetDiagnostics ........................................................................ 36
Shutdown() .................................................................................. 36

Chapter 3 aaDBCommand Object ................................ 37

aaDBCommand Object ................................................................... 37
Methods .......................................................................................... 38
AddRow() ..................................................................................... 38
DeleteCurrentRow() .................................................................... 39
Dispose() ...................................................................................... 39
ExecuteAsync() ............................................................................ 40
ExecuteAsyncCancel() ................................................................. 40
ExecuteSync() .............................................................................. 40

SQLData Script Library User’s Guide

 5

GetCurrentRowColumnByIndex() .............................................. 41
GetCurrentRowColumnByName() ............................................. 41
GetDataSet() ................................................................................ 42
GetId() .......................................................................................... 42
GetParameterByIndex() .............................................................. 43
GetParameterByName() ............................................................. 43
GetRow() ...................................................................................... 44
SaveChangesAsync() ................................................................... 45
SaveChangesSync() ..................................................................... 45
SelectRow() .................................................................................. 45
SelectTable() ................................................................................ 46
SetCurrentRow() ......................................................................... 46
SetCurrentRowColumnByIndex() .............................................. 48
SetCurrentRowColumnByName() .............................................. 49
SetParam Type Methods for SQL Server
and Oracle ............................................................................... 50
Output Parameters ................................................................. 51
SetBitParameterByName() ................................................... 51
SetCharParameterByName() ................................................ 52
SetDecimalParameterByName() ............................................ 53
SetDateTimeParameterByName() ........................................ 54
SetDoubleParameterByName() ............................................. 55
SetFloatParameterByName() ................................................ 56
SetIntParameterByName() .................................................... 57
SetLongParameterByName() ................................................. 58
SetParam Type Methods for OLEDB ......................................... 59
SetBitParameterByIndex() ..................................................... 60
SetCharParameterByIndex() .................................................. 61
SetDateTimeParameterByIndex() .......................................... 62
SetDecimalParameterByIndex() ............................................ 63
SetDoubleParameterByIndex() .............................................. 64
SetFloatParameterByIndex() ................................................. 65
SetIntParameterByIndex() ..................................................... 65
SetLongParameterByIndex() .................................................. 66
Properties ....................................................................................... 67
CommandTimeout ...................................................................... 67
CurrentRowNumber ................................................................... 67
CurrentTableNumber ................................................................. 68
Disposed ...................................................................................... 68
ExecutionState ............................................................................ 68
LastExecutionError .................................................................... 68
RowCount .................................................................................... 69
Public Enumerations ..................................................................... 69

SQLData Script Library User’s Guide

6 Contents

aaDBCommandState ................................................................. 69
Created ................................................................................... 69
Queued .................................................................................... 69
Failed ...................................................................................... 70
Completed ............................................................................... 70
Canceled .................................................................................. 70
Disposed .................................................................................. 70
aaDBCommandType .................................................................. 70
sqlStatement .......................................................................... 70
storedProcedure ...................................................................... 70
aaDBParameterDirection .......................................................... 70
Input ....................................................................................... 71
InputOutput ........................................................................... 71
Output..................................................................................... 71
ReturnValue ........................................................................... 71

Chapter 4 aaDBConnection Object .............................. 73

aaDBConnection Object ................................................................. 73
Connection Pooling ...................................................................... 74
Methods .......................................................................................... 74
CreateCommand() ....................................................................... 74
CreateCommand for Oracle .................................................... 75
CreateCommand for OLEDB .................................................. 75
CreateTransaction() .................................................................... 76
Dispose() ...................................................................................... 76
GetDiagnostics() .......................................................................... 77
LogDiagnostics() .......................................................................... 77
ResetDiagnostics ........................................................................ 77
Properties ....................................................................................... 77
ConnectionName ........................................................................ 77
ConnectionState ......................................................................... 78
Disposed ...................................................................................... 78
LastError .................................................................................... 78
Public Enumerations ..................................................................... 79
aaDBConnectionState ................................................................ 79
Disconnected ........................................................................... 79
Connecting .............................................................................. 79
Connected ............................................................................... 79
Created ................................................................................... 80
Disposed.................................................................................. 80
aaDBConnectionType ................................................................ 80
Sql ........................................................................................... 80

SQLData Script Library User’s Guide

 7

OleDb ...................................................................................... 80
Oracle ...................................................................................... 80

Chapter 5 aaDBRow Object ........................................ 81

aaDBRow Object ............................................................................ 81
aaDBRow —Public Constructor ................................................. 82
Methods .......................................................................................... 82
aaDBRow —Public Constructor ................................................. 82
GetColumnName() ...................................................................... 83
GetColumnValue() ..................................................................... 83
Properties ....................................................................................... 83
ColumnCount ............................................................................. 83
ColumnNames ............................................................................ 84
ColumnValues ............................................................................ 84

Chapter 6 aaDBTransaction Object .............................. 85

aaDBTransaction .......................................................................... 85
Methods .......................................................................................... 86
CreateCommand() ....................................................................... 86
Dispose() ...................................................................................... 86
ExecuteAsync() ............................................................................ 87
ExecuteAsyncCancel() ................................................................. 88
ExecuteSync() .............................................................................. 88
GetID() ........................................................................................ 89
Properties ....................................................................................... 89
Disposed ...................................................................................... 89
ExecutionState ........................................................................... 90
FailedCommandID ...................................................................... 90
LastExecutionError ................................................................... 90
Public Enumeration ....................................................................... 91
aaDBTransactionState .............................................................. 91
Created ................................................................................... 91
Queued .................................................................................... 91
Failed ...................................................................................... 91
Completed ............................................................................... 91
Canceled .................................................................................. 91
Disposed .................................................................................. 91

Appendix A Error Codes .............................................. 93

SQLData Script Library User’s Guide

8 Contents

Index....................................................... 97

SQLData Script Library User’s Guide

 9

Welcome

This guide describes using the ArchestrA SQLData Script

Library and provides practical examples of its use.
You can view this document online or you can print it, in part
or whole, by using the print feature in Adobe Acrobat Reader.
This guide assumes you know how to use Microsoft Windows,
including navigating menus, moving from application to
application, and moving objects on the screen. If you need
help with these tasks, see the Microsoft online help.
This guide also assumes that you know how to use Microsoft
SQL Server. For help with SQL Server, see the Microsoft
online help.
In some areas of the Application Server, you can also right-
click to open a menu. The items listed on this menu change,
depending on where you are in the product. All items listed
on this menu are available as items on the main menus.

Documentation Conventions
This documentation uses the following conventions:

Convention Used for

Initial Capitals Paths and file names.

Bold Menus, commands, dialog box names, and
dialog box options.
Monospace Code samples and display text.

SQLData Script Library User’s Guide

10 

Technical Support
Wonderware Technical Support offers a variety of support
options to answer any questions on Wonderware products
and their implementation.
Before you contact Technical Support, refer to the relevant
section(s) in this documentation for a possible solution to the
problem. If you need to contact technical support for help,
have the following information ready:
• The type and version of the operating system you are
using.
• Details of how to recreate the problem.
• The exact wording of the error messages you saw.
• Any relevant output listing from the Log Viewer or any
other diagnostic applications.
• Details of what you did to try to solve the problem(s) and
your results.
• If known, the Wonderware Technical Support case
number assigned to your problem, if this is an ongoing
problem.

SQLData Script Library User’s Guide

 11

Chapter 1

Using the SQLData Script

Library

The SQLData Script Library provides database integration

using ArchestrA scripting. The SQLData Script Library
provides the following benefits:
• Your resources are managed more efficiently because the
connection manager reduces the number of open
connections to the database provider. This activity is
known as connection pooling.
• You can process scripts asynchronously, which reduces
impact on the hosting engine during the following
activities:
• Opening a connection to a data source
• Running SQL queries
• Running SQL transactions
Note: It is recommended, to avoid returning excessive
amount of data using script library commands, for example
executing 15,000 SQL commands which each select 200
records from the Person.Contact table in the AdventureWorks
sample database. This can lead to a crash of the host engine.
To avoid this problem, consider using the TOP command to
limit the number of records returned.

SQLData Script Library User’s Guide

12  Chapter 1 Using the SQLData Script Library

Importing and Accessing the SQLData

Script Library
The SQLData Script Library is contained in the file named
aaDBIntegration.aaSLIB. Copy the file to your ArchestrA
development computer.

To access the SQLData Script Library

1 Open the ArchestrA IDE.
2 On the main menu, click Galaxy/Import/Script Library.
After you import the SQLData Script Library, you can access
the library functions from the Script Function Browser in
the Script tab of any object. The functions are visible in the
Types section.

For more information about working with function libraries,

see the Wonderware Application Server User’s Guide.

SQLData Script Library Interface

This section provides an overview of the SQLData Script
Library interface.

SQLData Script Library User’s Guide

 SQLData Script Library Interface13

SQLData Script Library Architecture

You can integrate the SQLData Script Library into
ArchestrA by using synchronous or asynchronous scripting.
The SQLData Script Library contains the following public
objects:
• aaDBAccess
• aaDBConnection
• aaDBTransaction
• aaDBCommand
• aaDBRow
You can find details about these objects as well as their
methods, properties, and enumerations in the remaining
chapters in this guide.
The following figure shows connection pooling in the
SQLData Script Library. Although each script generates its
own connection object in the script library, scripts with
identical connection strings are allocated to the same
connection pool. The result is fewer connections to the
database.

Synchronous
Asynchronous
scripts on all
script on
objects on
AppEngine X
AppEngine X

Connection 1 Connection 2 Connection 3

“Database=A; “Database=A; “Database=A;

User=Y” User=B” User=B”

Connection Pool 1 Connection Pool 2

“Database=A; “Database=A;
User=Y” User=B”

Database A

SQLData Script Library User’s Guide

14  Chapter 1 Using the SQLData Script Library

The following figure shows a conceptual diagram of the

relationships among the various components of the SQLData
script library.

aaDBRow

GetRow() aaDBCommand

ExecuteAsync()
ExecuteSync()

CreateCommand()

aaDBCommand aaDBTransaction

CreateCommand() CreateTransaction()

aaDBConnection

CreateConnection()
GetConnection()

aaDBIntegration

Note that aaDBRow is one mechanism provided by

aaDBCommand to read and modify data returned from the
SQL query. The other mechanisms are implemented as
methods of aaDBCommand.

SQLData Script Library User’s Guide

 SQLData Script Library Work Flow15

SQLData Script Library Work Flow

This section shows the work flow to create a connection object
with a command and a transaction. This section also provides
connection string examples.

Creating a Connection Object with a

Command
SQLData scripts follow a typical flow when they are written
without transactions:
1 Create a connection object.
2 Create one or more command objects using the
CreateCommand() method of the connection object.

3 For each command object whose SQL statement contains

parameters, initialize each parameter by using either the
Set<Type>ParameterByName() method or the
Set<Type>ParameterByIndex() method of the
command object.
4 Run the command object either synchronously or
asynchronously.
When command processing is complete, you can retrieve and
modify the returned dataset. If you modify the dataset, you
can save it back to the database either synchronously or
asynchronously.
You can reuse command objects indefinitely. When finished,
clean up the command objects by calling their Dispose()
methods.

Creating a Connection Object with a

Transaction
SQLData scripts follow a typical flow written with
transactions:
1 Create a connection object.
2 Create a transaction object by using the
CreateTransaction() method of the connection object.
3 Add one or more command objects to the transaction by
using the CreateCommand() method of the transaction
object.

SQLData Script Library User’s Guide

16  Chapter 1 Using the SQLData Script Library

4 For each command object whose SQL statement contains

parameters, initialize each parameter by using either the
Set<Type>ParameterByName() method or the
Set<Type>ParameterByIndex() method of the
command object.
5 Run the transaction object either synchronously or
asynchronously.
If any of the commands fails or returns an error, the
transaction and any commands that ran within the
transaction are rolled back. The transaction is returned with
the appropriate indicator
When transaction processing is complete, you can retrieve
and modify the returned dataset for each command in the
transaction that returns data. If you modify a dataset, you
can save it back to the database either synchronously or
asynchronously.
You can reuse transaction objects indefinitely. When
finished, clean up the transaction object and command
objects by calling their Dispose() methods.

Specifying Connection Strings

The SQLData Script Library uses a connection string to
specify the parameters for a database connection. The
connection string is specified by Microsoft in their ADO.NET
implementation. You can find details about the connection
string and its parameters in the following locations:
http://msdn2.microsoft.com/en-us/library/
ms254978(VS.85).aspx
http://msdn2.microsoft.com/en-us/library/
ms254499.aspx
If you are using a non-default port for the SQL Server
database, see the SQLData Object help file for configuration
information.
The following examples show how to write connection strings
for the most commonly used data providers.

Connecting to a SQL Server Data Source

The following script shows an example connection for SQL
Server:
Connection=aaDBAccess.GetConnection(
me.ConnectionString,
aaDBConnectionType.Sql);

SQLData Script Library User’s Guide

 Example Scripts17

Using aaDBConnectionType.Sql is synonymous with the

form of GetConnection() that takes only a connection string.
Use the connection string example shown in Connecting to a
SQL Server Data Source in place of me.ConnectionString.

Connecting to an Oracle Data Source

The following script shows an example connection for Oracle:
Connection=aaDBAccess.GetConnection("Provider=MSDAORA;
Data Source=myOracleServer;User ID=<name>;
Password=<password>.",aaDBConnectionType.Oracle);

Connecting to Microsoft Access through

OLEDB
The following script shows an example connection for
Microsoft Access through OLEDB:
Connection=aaDBAccess.GetConnection(
"Provider=Microsoft.Jet.OLEDB 4.0;
Data Source=C:\myAccessDb.mdb",
aaDBConnectionType.OleDb);

Connecting to Microsoft Excel through OLEDB

The following script shows an example connection for
Microsoft Excel through OLEDB:
Connection=aaDBAccess.GetConnection(
"Provider=Microsoft.Jet.OLEDB 4.0;
Data Source=C:\NameAndAddress.xls;
Extended Properties=Excel 8.0;",
aaDBConnectionType.OleDb);

Note: Microsoft Excel does not support transactions (commit

or rollback).

Example Scripts
The following two examples illustrate the use of the
SQLData Script Library to access a database.

Note: These scripts are provided only as a reference.

Overview of Sample Scripts

The sample scripts have the following purpose in a larger,
ArchestrA context:

SQLData Script Library User’s Guide

18  Chapter 1 Using the SQLData Script Library

• The script provides an object that other requesting

objects can use to read the specified column of a row
whose part number is given and then return the column
value to the requesting object.
• The requesting object provides the row name, part
number, and start signal in UDAs.
• The sample object returns the requested row value and
done signal in UDAs.

Detailed Description of Sample Scripts

This section is a detailed step-by-step description of what is
happening in the sample scripts that follow. For more
information about using application objects, see the
Wonderware Application Server User’s Guide.
1 Create a connection object and supply the connection
string. The connection string in this example is a literal
string, but you can use a connection string supplied by
another ArchestrA object through a UDA.
2 If you are using transactions, create a transaction object
on the connection object that you created.
3 Create a command object. This example supplies a literal
string for the SQL statement, but it could be supplied by
another ArchestrA object through a UDA. Note that the
SQL statement is a query with a parameter, which allows
the requesting object to specify the column to read:
a If you are not using transactions, create the command
object on the connection object.
b If you are using transactions, create the command
object on the transaction object.
4 Because the SQL statement of the command object
contains a parameter, you must initialize that parameter
object (or the transaction that contains it).
5 Run the transaction or command using either the
ExecuteAsync() or ExecuteSync() methods.
6 If the command or transaction is processed
synchronously, the SQLData Script Library does not
return from the ExecuteSync() method until the
command is complete. Because processing can take an
extended period of time, you should use an asynchronous
script (that is, a script that is not synchronized with the
scan of the ArchestrA AppEngine).
If the command or transaction is executed
asynchronously, poll for completion as follows:

SQLData Script Library User’s Guide

 Example Scripts19

• If your script runs synchronously with the scan of the

ArchestrA AppEngine, you must signal polling to
occur by a script once per scan cycle of the engine.
This example script starts a second polling script, but
you can write a single script with a state variable that
starts processing in one state and polls in the other
state.
• If your script runs asynchronously with the
ArchestrA AppEngine, you can poll in the following
lines of the same script that starts processing using a
while loop, which can take an extended period of time
to finish.
7 When the command or transaction completes without an
error, the result can be read from the command object
using the parameter that was initialized before the
command object was run.
8 Check for errors at each of the major script processing
steps.

Asynchronous Command Script

The scripts in this object show how to use asynchronous SQL
processing in the SQLData Script Library. This script is
written to use a command object directly on the connection,
without using a transaction object. For comparison, see
Synchronous Transaction Script on page 22 where the
example uses the synchronous SQL processing for a
command object on a transaction object.
This object is written with two scripts. One script starts
asynchronous command processing (the Query script) and
the other script polls for asynchronous command completion
and results manipulation (the Process script). Both scripts
run synchronously with the ArchestrA AppEngine scan. To
use the scripts, set the number to search for in the
PartNumber User Defined Attribute (UDA) and column
whose value is to be read in the ColumnToRead UDA.
Signal the script to run by setting the ReadCommand UDA
to True. When the script finishes processing, the
ColumnReadDone UDA becomes True, and the results are
in the ColumnValue UDA.

SQLData Script Library User’s Guide

20  Chapter 1 Using the SQLData Script Library

Query Script Configuration

On the Script tab of the SQLData Object Editor, configure
the Query script with the following attributes.

Attribute Value
Execution Type Execute
Expression me.ReadCommand
Trigger Type OnTrue
Runs Asynchronously Selected

Process Script Configuration

On the Script tab of the SQLData Object Editor, configure
the Process script with the following attributes.

Attribute Value
Execution Type Execute
Expression me.ProcessCommand
Trigger Type WhileTrue
Runs Asynchronously Selected

Query Script Code

Use the following sample code for the Query script.
DIM Connection as aaDBClient.aaDBConnection;

DIM Command as aaDBClient.aaDBCommand;

'Create a connection object with the connection string.

LogMessage("Creating connection");

Connection = aaDBAccess.CreateConnection("Data
Source=localhost;Initial
Catalog=AdventureWorks;Integrated Security=true");

'Create a command object, with a SQL statement.

LogMessage("Creating a command object");

Command = Connection.CreateCommand("Select * from

Production.Product WHERE ProductNumber =
@ProductNumber", aaDBCommandType.SqlStatement, true);

'We used a parameter to specify the value for the

ProductNumber field, so initialize it.

SQLData Script Library User’s Guide

 Example Scripts21

Command.SetCharParameterByName("ProductNumber",
me.PartNumber, aaDBParameterDirection.Input, 50);

'Everything is ready, let's execute the command async.

LogMessage("Executing command async");

DIM ResultCode as integer;

ResultCode = Command.ExecuteAsync();

if ResultCode <> 0 then

'Failed to start async execution, report the

reason.

LogMessage("Got error " + ResultCode + " executing

command async");

else

'Execution started, identify the command by ID, for

use later.

LogMessage("Command async execution started

successfully");

me.CommandID = Command.GetID();

'Allow the Process script to run.

me.ProcessCommand = true;

endif;

'Reset for next time

me.ReadCommand = false;

Process Script Code

Use the following sample code for the Process script.
DIM Command as aaDBClient.aaDBCommand;

'Retrieve the command object using its ID.

Command = aaDBAccess.GetCommand(me.CommandID);

if Command <> null then

'Poll for command complete

if Command.ExecutionState <> aaDBCommandState.Queued

then

LogMessage("Command execution state is " +

Command.ExecutionState);

SQLData Script Library User’s Guide

22  Chapter 1 Using the SQLData Script Library

if Command.ExecutionState == aaDBCommandState.Completed
then

DIM Rows as integer;

Rows = Command.RowCount;

LogMessage("Row count returned from command is "

+ Rows);

'We expect one row, use the first one, if we have any.

if Rows > 0 then

LogMessage("Getting column '" + me.ColumnToRead

+ "' from row 0");

Command.SelectRow(0);

'Return the requested column value from this row,

signal done.

me.ColumnValue =
Command.GetCurrentRowColumnByName(me.ColumnToRead);

me.ColumnReadDone = true;

endif;

endif;

'When done, dispose the command.

Command.Dispose();

'Reset for next time

me.ProcessCommand = false;

endif;

else

LogMessage("Cannot find command " + me.CommandID);

me.ProcessCommand = false;

endif;

Synchronous Transaction Script

The single script for this SQLData object shows how to use
the synchronous SQL processing in the SQLData Script
Library. This script is uses a transaction object with the
command object on the transaction. For comparison, see
Asynchronous Command Script on page 19 where the
example uses the command object directly on the connection,
without a transaction.

SQLData Script Library User’s Guide

 Example Scripts23

This transaction object is written with a single script called

QueryandProcess, which performs the SQL processing
synchronously and then manipulates the results. This script
runs without synchronizing with the ArchestrA AppEngine
scan (asynchronous script). To use the script, set the part
number to search for in the PartNumber UDA and the
column whose value is to be read in the ColumnToRead
UDA. Signal the script to run by setting the
ReadTransaction UDA to True. When the script finishes
processing, the ColumnReadDone UDA becomes True and
the results are in the ColumnValue UDA.
QueryandProcess Script Configuration
On the Script tab of the SQLData Object Editor, configure
the QueryandProcess script with the following attributes.

Attribute Value
Execution Type Execute
Expression me.ReadTransaction
Trigger Type OnTrue
Runs Asynchronously Selected

QueryandProcess Script Code

Use the following sample code for the QueryandProcess
script.
DIM Connection as aaDBClient.aaDBConnection;

DIM Command1 as aaDBClient.aaDBCommand;

DIM Transaction as aaDBClient.aaDBTransaction;

'Create a connection object with the connection string.

LogMessage("Creating connection");

Connection = aaDBAccess.CreateConnection("Data
Source=localhost;Initial
Catalog=AdventureWorks;Integrated Security=true");

'Create a transaction object within the connection

object.

LogMessage("Creating transaction object");

Transaction = Connection.CreateTransaction();

'Create a command object for the transaction object,

with a SQL statement.

SQLData Script Library User’s Guide

24  Chapter 1 Using the SQLData Script Library

LogMessage("Creating a command object");

Command1 = Transaction.CreateCommand("Select * from

Production.Product WHERE ProductNumber =
@ProductNumber", aaDBCommandType.SqlStatement, true);

'We used a parameter to specify the value for the

ProductNumber field, so initialize it.

Command1.SetCharParameterByName("ProductNumber",
me.PartNumber, aaDBParameterDirection.Input, 50);

'Everything is ready, let's execute the transaction

sync.

LogMessage("Executing transaction sync");

DIM ResultCode as integer;

ResultCode = Transaction.ExecuteSync();

if ResultCode <> 0 then

'Failed to execute transaction sync, report the

reason.

LogMessage("Got error " + ResultCode + " executing

transaction sync");

else

if Transaction.ExecutionState ==
aaDBTransactionState.Completed then

DIM Rows as integer;

Rows = Command1.RowCount;

LogMessage("Row count returned from command is

" + Rows);

'Use other methods of script library to read data

and assign to UDAs, etc.

if Rows > 0 then

LogMessage("Getting column '" +

me.ColumnToRead + "' from row 0");

Command1.SelectRow(0);

'Return the requested column value from this

row, signal done.

SQLData Script Library User’s Guide

 Example Scripts25

me.ColumnValue =
Command1.GetCurrentRowColumnByName(me.ColumnToRead);

me.ColumnReadDone = true;

endif;

'When done, dispose the command.

Command1.Dispose();

endif;

'When done, dispose the transaction.

Transaction.Dispose();

endif;

'Reset for next time

me.ReadTransaction = false;

SQLData Script Library User’s Guide

26  Chapter 1 Using the SQLData Script Library

SQLData Script Library User’s Guide

 27

Chapter 2

aaDBAccess Object

aaDBAccess Object
The aaDBAccess object exposes only static methods. Use
static methods with the aaDBAccess object to request a
connection to the data source by providing a connection
string. You can use two categories of methods to create a
database connection:
• A reusable connection object: GetConnection()
• A unique connection object: CreateConnection()
By default, the SQLData Script Library assumes that a
connection to a SQL Server database is requested and
establishes a physical connection by using the
System.Data.SqlClient namespace.
For details about methods that you can use with this object,
see Methods on page 30.

Creating a Reusable Connection Object

To create a reusable connection object, use the following
method:
aaDBAccess.GetConnection (<ConnectionString>,
<ProviderType>)

For more information, see Connecting to Databases Other

Than SQL Server on page 31.

SQLData Script Library User’s Guide

28  Chapter 2 aaDBAccess Object

Creating a Unique Connection Object

To create a unique connection object for a specific purpose,
use the following method:
aaDBAccess.CreateConnection(<ConnectionString>,
<ProviderType>)

Differences Between CreateConnection()

and GetConnection()
The CreateConnection() method always creates a new
connection object, even for calls with identical connection
strings and even if GetConnection() has already been called
with the same connection string.
Multiple calls to GetConnection() with identical—not
similar— connection strings return the same connection
object, over and over. If the connection string has never been
used in a call to GetConnection(), a new connection object is
created, but subsequent calls with the same connection
string return the same connection object.
A call to CreateConnection() followed by a call to
GetConnection() with the same connection string returns
two different connection objects. That is, the connection
object returned by GetConnection() is never the same as the
connection object that has been returned by
CreateConnection().

Note: Because GetConnection() shares the same

connection object across multiple scripts, connection pooling
is effectively disabled for a specific connection string. All
commands or transactions that run on a shared connection
are routed through a single queue. Therefore, multiple
physical connections for a single unique connection string
cannot occur. If you want to use connection pooling, use the
CreateConnection() method.

For more information, see Connecting to Databases Other

Than SQL Server on page 31.

Working with Connections

Supply all connection settings in a single parameter named
ConnectionString that follows the documented Microsoft
syntax. For details about Microsoft syntax, follow this link:
http://msdn2.microsoft.com/en-us/library/ms254499.aspx

Note: The parsing of the ConnectionString is not case

sensitive.

SQLData Script Library User’s Guide

 aaDBAccess Object29

For authentication, you can use one of the following security

modes:
• Windows Integrated Security
• Windows Account
• SQL Server Authentication

Windows Integrated Security

Internally, IntegratedSecurity provides the connection by
using the credentials of the currently logged on ArchestrA
user.
Specify the following syntax in the connection string:
Integrated Security=True

The keyword Integrated Security=True in the connection

string overrides any other authentication control. If the
Integrated Security=True keyword is present, you get
Windows User Authentication for the user who is currently
logged on, even if you also include credentials for a different
user.
If you want to impersonate another Windows user’s
credentials, Integrated Security=True must be omitted
from the connection string.

Windows Account
In the ConnectionString parameter, you must provide the
following information: domain, user name and password. The
domain and user name must be specified using the following
syntax:
User ID=<Domain>\<UserName>; Password=<pasword>;

The SQLData Script Library takes the following actions:

1 Removes domain, user name, and password from
<ConnectionString>.
2 Sets Integrated Security=True in
<ConnectionString>.
3 Configures the connection manager with the specified
domain, user name, and password and then requests
impersonation of this user.
The SQLData Script Library impersonates the user based on
the properties that were provided in the connection string.

SQLData Script Library User’s Guide

30  Chapter 2 aaDBAccess Object

SQL Server Authentication

Provide the following information in the ConnectionString;
User ID=<UserName>; Password=<password>;

The SQLData Script Library directly passes

<ConnectionString> through to the SQL Server database.
The aaDCM object uses <ConnectionString> as is. There is
no need for impersonation.

Methods
You can use the following methods with the aaDBAccess
object.

CreateConnection()
Use the CreateConnection() method to request a connection
to a SQL Server data source.

Syntax
aaDBConnection.CreateConnection(
string ConnectionString)

Parameters
ConnectionString
A previously formatted connection string or a reference to
an attribute in any ArchestrA object.

Remarks
The CreateConnection() method returns a connection object
to be used for subsequent SQL requests. Each call to
CreateConnection() returns a unique and different
connection object. Each connection object represents a
separate connection that uses the same connection string.
This method is best used to provide different connections for
different purposes. For example, when one connection is used
to query and another is used to update the database.
You can check the status of a connection by using the
ConnectionState read-only property.

Example
The following example shows a connection string for use with
SQL Server. The connection string can also be stored in an
attribute in an Archestra object:
me.ExampleConnectionString

SQLData Script Library User’s Guide

 Methods31

Connecting to Databases Other Than

SQL Server
Use the overloaded CreateConnection() method to provide
access to a data source other than Microsoft SQL Server.

Syntax
aaDBConnection.CreateConnection(
string ConnectionString,
aaDBConnectionType ConnectionType)

Parameters
Acceptable values for ConnectionType are as follows:
• OleDb
• Oracle

Note: Use OleDb to connect to the Microsoft Access data

source.

GetCommand()
Use the GetCommand() method to retrieve a reference to an
aaDBCommand object created previously with the same or a
different script. Do not create a new aaDBConnection object
to access a previously created command object.

Syntax
aaDBCommand.GetCommand(
string CommandId)

Parameters
commandId
The Id is generated internally by the SQLData Script
Library. For details, see GetId() on page 42.

Remarks
If CommandID does not represent a valid ID,
GetCommand() returns a null reference.

GetConnection()
Use the GetConnection() method to request a connection to
a data source.

SQLData Script Library User’s Guide

32  Chapter 2 aaDBAccess Object

Syntax
aaDBConnection.GetConnection(
string ConnectionString)

Parameters
ConnectionString
A previously formatted connection string or valid
ArchestrA reference.

Remarks
The GetConnection() method returns a connection object to
be used for subsequent SQL Server requests. Each time that
GetConnection() is called with the identical connection
string to a previous call, it returns the same connection object
for reuse. This method is best used with a script that runs
repeatedly, where a new connection object for each iteration
would constitute a risk of memory leakage.
You cannot assume that a physical connection occurs after
requesting a connection to a data source. Connections are
opened only on an as-needed basis to perform an operation.
The only time that you can check connectivity status is
immediately after an operation completes.
This method immediately provides a connection object to be
used for subsequent SQL requests. The first call to
GetConnection() returns a unique connection object for the
specified connection string, similar to CreateConnection().
Subsequent calls to GetConnection() return references to
the same connection object. Thus, you can make multiple
calls to reuse the same object.
The connection returned by GetConnection() is never the
same object as the one returned by CreateConnection().
This difference enables you to place GetConnection() calls
at the top of a script that run once per scan without
constantly creating connection objects.

Note: Be sure to call Dispose() on connection objects that

have been created with this method. The aaDBAccess
SQLData Script Library contains a reference to the objects.
Garbage collection cannot be performed on them until you call
Dispose().

You can check the status of the connection by using the

ConnectionState read-only property.

SQLData Script Library User’s Guide

 Methods33

Authentication
The following three database authentication methods are
supported:
• Windows Integrated Security
• Windows Account
• SQL Server Authentication
You must provide a standard connection string that is
created from keyword = value pairs separated by semicolons.
Follow this link for a list of connection string keywords:
http://msdn2.microsoft.com/en-us/library/ms254499.aspx
For Windows Integrated Security specify the following
parameter in the connection string:
Integrated Security=true;

For Windows Account authentication, specify a connection

string that adheres to the following syntax:
User ID=<domain>\<username>;Password=<password>;

For SQL Server Authentication, specify a connection string

that adheres to the following syntax:
User ID=<UserName>;Password=<password>;

Connecting to Databases Other Than

SQL Server
Use the overloaded GetConnection() method to access a
data source other than Microsoft SQL Server.

Syntax
aaDBConnection.GetConnection(
string ConnectionString,
aaDBConnectionType ConnectionType)

Parameters
Acceptable values for ConnectionType are as follows:
• OLEDB
• Oracle

Note: Use OLEDB to connect to the Microsoft Access data

source.

SQLData Script Library User’s Guide

34  Chapter 2 aaDBAccess Object

GetDiagnostics()
Use the GetDiagnostics() method to return diagnostic
information about all connections in a dataset.

Syntax
void GetDiagnostics()

Remarks
The returned dataset contains multiple tables. The table
with index 0 contains the global diagnostic information. The
remaining tables in the dataset correspond to each DCM
connection object. For details about diagnostic properties, see
the SQLData Object Help.

GetTransaction()
Use the GetTransaction() method to obtain a reference to an
aaDBTransaction object created previously in the same or a
different script. Do not create a new aaDBConnection object
to access a previously created transaction.

Syntax
aaDBTransaction GetTransaction(
string TransactionID)

Parameters
TransactionID
The ID is generated internally by the SQLData Script
Library. See GetID() on page 89.

Remarks
If TransactionID does not represent a valid ID,
GetTransaction() returns a null reference.

LogDiagnostics()
Use the LogDiagnostics() method to create a snapshot of all
diagnostics available for a connection to be dumped to the
logger. For details about diagnostic properties, see the
SQLData Object Help.

Syntax
void LogDiagnostics()

SQLData Script Library User’s Guide

 Methods35

RemoveCommand()
Use the RemoveCommand() method to instruct the
SQLData Script Library to remove internal references to the
aaDBCommand object referenced by CommandID, release
all resources used by the object, and clean up all references to
the object in memory.

Syntax
void RemoveCommand(
string CommandID)

Parameters
CommandID
The unique ID, generated internally by the SQLData
Script Library. For details, see GetId() on page 42.

Remarks
You must call RemoveCommand() if you previously
requested CommandID. Otherwise, the memory cannot be
released until the engine process is shut down.
Do not keep this command object in memory, especially when
it is associated with a large dataset.

RemoveTransaction()
Use the RemoveTransaction() method to instruct the
SQLData Script Library to remove all references to the
aaDBTransaction object referred to by TransactionID,
release all resources used by the object, and clean up all
references to the object in memory.

Syntax
void RemoveTransaction(
string TransactionID)

Parameters
TransactionID
The unique ID, generated internally by the SQLData
Script Library. See aaDBTransaction.GetID() on page 89.

Remarks
Internally, the SQLData Script Library ensures that all
aaDBCommand objects explicitly added to this object are
removed.
You must call this method if you previously requested the
transaction ID. Otherwise, the memory cannot be released
until the engine process is shut down.

SQLData Script Library User’s Guide

36  Chapter 2 aaDBAccess Object

Do not keep this command object in memory, especially when

it is associated with a large dataset.

ResetDiagnostics
Use the ResetDiagnostics() method to reset the current
diagnostic values associated with the DCMConnectionMgr
and all DCMConnections.

Syntax
void ResetDiagnostics()

Shutdown()
Use the Shutdown() method to gracefully cancel outstanding
command object requests and release references to all
persisted aaDBCommand and aaDBTransaction objects.
Call this method just once from a shutdown script in the
hosting engine.

Syntax
void Shutdown()

SQLData Script Library User’s Guide

 37

Chapter 3

aaDBCommand Object

This section contains reference information about the

aaDBCommand object and the methods and properties that
you can use with it.

aaDBCommand Object
Use objects of type aaDBCommand to process SQL
statements and stored procedures or to access a single table
or view.
Create instances of type aaDBCommand by calling
CreateCommand() on an instance of the aaDBConnection
object. For example, assuming that the aaDBConnection
instance is called Connection:
Connection.CreateCommand()

When a script requests the command object ID, the command

object is flagged to be persisted.
The aaDBCommand objects are persisted across scripts and
scan cycles but not across failover or shutdown.

Note: You must call Dispose() on each instance of

aaDBCommand where an ID was created. You can also call
aaDBAccess.RemoveCommand() with the ID.

You can retrieve an aaDBCommand object at any time by

calling the static method aaDBAccess.GetCommand() and
passing the previously acquired string ID.

SQLData Script Library User’s Guide

38  Chapter 3 aaDBCommand Object

The aaDBCommand object provides support for types that

make sense for QuickScript. Other types may be supported
by database columns, such as large text files or generic
binary large objects (BLOBs), but a script might not be able
to generate or analyze them. In general, if the script cannot
manipulate objects of a particular type, such as a BLOB of
type char[] or byte[], it might still be possible to read or write
an object of that type to or from some alternate script library
while storing it as type object within the script. In these
cases, the object may be blindly written to a database using
SetCurrentRowColumnByName() or
SetCurrentRowColumnByIndex() and may be blindly read
from a database using GetCurrentRowColumnByName()
or GetCurrentRowCollumnByIndex().
The life cycle of the aaDBCommand object follows this
pattern:
1 The object is created by calling the
aaDBConnection.CreateCommand() method.
2 Parameters are added to the command object as
necessary.
3 The command object is run synchronously or
asynchronously.
4 The dataset object wrapped by the aaDBCommand
object is accessed and manipulated. This process may
involve writing the dataset object back to the database.
5 Steps 2 through 4 can be repeated as needed.

Methods
You can use the following methods with the aaDBCommand
object.

AddRow()
Use the AddRow() method to add an empty row to a memory
table and make it current.
You can then add values to the row by using the following
methods:
• SetCurrentRowColumnByIndex()
• SetCurrentRowColumnByName()
• SetCurrentRow()

SQLData Script Library User’s Guide

 Methods39

Syntax
result AddRow()

Remarks
The actual update to the data source is delayed until you call
SaveChangesSync() or SaveChangesAsync().

DeleteCurrentRow()
Use the DeleteCurrentRow() method to mark the currently
selected row for deletion. The current row is not deleted from
the data source until you call SaveChangesSync() or
SaveChangesAsync().

Syntax
result DeleteCurrentRow()

Dispose()
Use the Dispose() method to instruct the SQLData Script
Library to free all memory resources associated with the
command object. If the command is running, Dispose()
cancels it. It is preferred to cancel the command before
calling Dispose().

Syntax
Void Dispose()

Remarks
After Dispose() is called, subsequent method calls to the
command fail.
If an ID has been retrieved for this command object, you
must call Dispose() or aaDBAccess.RemoveCommand().
If you requested the ID of this command object, it is very
important that you call Dispose() so it can flag the SQLData
Script Library to clear all the references to this object.
When you request a dataset it is very important for you to
call the Dispose() method when you are no longer interested
in the results of a specific command object.
If you have made changes to the memory dataset such as
updating, deleting, or adding, but did not issue
SaveChangesSync() or SaveChangesAsync(), all changes are
discarded.

SQLData Script Library User’s Guide

40  Chapter 3 aaDBCommand Object

Subsequent method calls to request scrolling or to modify the

memory dataset fail and return either a null object or error
code 1016.

ExecuteAsync()
Use the ExecuteAsync() method to queue a command object
in the connection for later processing. ExecuteAsync()
returns immediately, and processing occurs in the
background.

Syntax
result ExecuteAsync( )

Remarks
You can check for status by reading the ExecutionState
read-only property.
After ExecuteAsync() is processed, you can still obtain a
reference to the command objects and analyze their
ExecutionState and LastError properties.
To free all resources allocated for the command object, you
must call Dispose().

ExecuteAsyncCancel()
Use the ExecuteAsyncCancel() asynchronous method to
cancel the operations of a running command. If the command
has already started running, it may run to completion. If the
command is queued while waiting for other commands, it is
removed from the queue without running.

Syntax
result ExecuteAsyncCancel( )

Remarks
To check for status, you can request the ExecutionState
read-only property.
After the method has successfully completed, the command
object is canceled.

ExecuteSync()
Use the ExecuteSync() method to run the command object.
This method runs synchronously and blocks the engine
thread.

SQLData Script Library User’s Guide

 Methods41

Syntax
result ExecuteSync( )

Remarks
Use the ExecutionState and LastExecutionError properties to
check for status of this method.
After ExecuteSync() is processed you can still obtain a
reference to the command object and analyze its
ExecutionState and LastError properties.
Use the LastExecutionError property to check if the
command failed or succeeded (success is indicated by a blank
string), since ExecuteSync() may return 0 in the case of a
failure instead of an error message.
To free all resources allocated for the command object, you
must call Dispose().

GetCurrentRowColumnByIndex()
Use the GetCurrentRowColumnByIndex() method to
obtain a specific column value from the current row. Use this
method to read a single column value. For more information,
see SelectRow() on page 45.
You must provide a zero-based column index.

Syntax
object GetCurrentRowColumnByIndex(
int ColumnNumber)

Parameters
ColumnNumber
Zero-based index to the table column.

Return Value
The object returned on failure is Null. The requested index is
either negative, larger than the number of columns, or there
is no valid current row.

GetCurrentRowColumnByName()
Use the GetCurrentRowColumnByName() method to
obtain a specific column value from the current row by
column name. Use this method to read a single column value.
For more information, see SelectRow() on page 45.
You must provide a column name.

SQLData Script Library User’s Guide

42  Chapter 3 aaDBCommand Object

Syntax
object GetCurrentRowColumnByName(
string ColumnName)

Parameters
ColumnName
Column name.

GetDataSet()
Use the GetDataSet() method to retrieve the dataset stored
in memory that was generated when the command object
finished processing.

Syntax
DataSet GetDataset( )

Remarks
It is not recommended that you use this method under
normal conditions, because the actual dataset may contain
large amount of data (huge number of rows). This method is
provided for advanced users that want to directly use the
SQLClient namespace to interact with the dataset.

Note: If you execute this method in a synchronous script

with a large number of rows, the script may time out. If you
plan to use this method, it is recommended that you
configure the script to run asynchronously.

ArchestrA QuickScript uses 1-based indexing when

square-bracket notation is used with numeric indexes, such
as DataSet.Tables[7].
To avoid confusion, use square-bracket notation with
collections that support strong name indexing, such as
DataSet.Tables["Customers"]. You can also bypass the
dataset object by using the wrapping accessor functions
described in the next sections.

GetId()
Use the GetID() method to retrieve the ID of an
aaDBCommand object instance for use in a different script
or scan. The SQLData Script Library generates a unique
command object ID, which remains unique across all scripts
on the engine.

SQLData Script Library User’s Guide

 Methods43

Syntax
string GetId()

Return Value
On failure, this method returns the value Null.

Remarks
The SQLData Script Library returns a string value, but the
script engine automatically attempts to cast this value to
other types. If the script assigns the returned ID to any type
other than string, the ID is corrupted and does not work in
future GetCommand(ID) calls.

GetParameterByIndex()
Use the GetParameterByIndex() method to retrieve output
or to return parameters after the command object has been
processed. If the parameter cannot be evaluated, the
returned value is null.

Syntax
object GetParameterByIndex(
int Index)

Parameters
Index
1-based parameter index.

Remarks
You must provide a one-based parameter index.

Note: Use this method only for parameters defined in an

OLEDB-type query, as specified by the connection object. If
the connection type is not OleDb, null is returned.

GetParameterByName()
Use the GetParameterByName() method to retrieve output
or return parameters after the command object has been
processed. If the parameter cannot be evaluated, the
returned value is null.
You must provide a parameter name.

Syntax
object GetParameterByName(
string ParameterName)

SQLData Script Library User’s Guide

44  Chapter 3 aaDBCommand Object

Parameters
ParameterName
Parameter name.

Remarks
It is not considered an error if the ResultSet returned from a
query contains no rows. Zero-row results can also be expected
as results of queries that contain parameters, so this might
be an expected result, depending on the purpose of the query.

Note: Use this method only for parameters defined in a

non-OLEDB-type query, as specified by the connection object.
If the connection type is not OleDb, null is returned.

GetRow()
Use the GetRow() method to quickly scroll through the
records in the memory table and examine the row values and
determine an index to be used for selecting a row of interest.
For more information, see SelectRow() on page 45.
You must provide a zero-based row index.

Syntax
aaDBRow GetRow(
int RowNum)

Parameters
RowNum
A zero-based row index less than the row count in the
memory dataset.

Remarks
This method executes synchronously.
The aaDBRow returned object has two members:
• columnNames: An array filled with column names.
• columnValues: An array filled with column values
corresponding to the row index.
The array items must be converted to strings before you can
use them in string manipulation.
After the command object is successfully run you can use the
columnValues array to set ArchestrA attributes.

Note: Before setting ArchestrA attributes you may need to

cast the individual items from the columnValues array.

SQLData Script Library User’s Guide

 Methods45

SaveChangesAsync()
Use the SaveChangesAsync() method to instruct the
SQLData Script Library to write back to the data source all
changes made to the memory dataset. The dataset must
have been acquired by calling ExecuteAsync() or
ExecuteSync().

Syntax
result SaveChangesAsync()

Remarks
This method runs asynchronously. The request for updating
the data source is queued and the method completes
immediately.
You must check for status by getting the ExecutionState
property value.

SaveChangesSync()
This method is similar to SaveChangesAsync() except that it
runs synchronously.

Syntax
result SaveChangesSync()

Remarks
This method blocks the engine thread when the script itself
is synchronous.
It is highly recommended that you use this method only in
asynchronous scripts.
When you configure the asynchronous script, make sure that
the TimeoutLimit value is large enough to accommodate the
time that this method may take to run the command object.

SelectRow()
Use the SelectRow() method to select the row with the index
rowNumber in the memory table.

Syntax
result SelectRow(
long RowNumber)

SQLData Script Library User’s Guide

46  Chapter 3 aaDBCommand Object

Parameters
RowNum
The zero-based index of the record in the memory table.

Remarks
After you select a row, you can then read, delete or update
the row using the following methods:
• GetCurrentRowColumnByIndex()
• GetCurrentRowC()
• SetCurrentRowColumnByIndex()
• SetCurrentRowColumnByName()
• SetCurrentRow()

SelectTable()
Use the SelectTable() method to select the table with the
index TableIndex in the memory dataset.
You can then read, delete, or update this DataTable.

Syntax
result SelectTable(
long RowNumber)

Parameters
TableNumber
A zero-based index of the table in the memory dataset.

Remarks
By default, immediately after a command object returns a
non- empty dataset that runs successfully the table with
index 0 is selected.

SetCurrentRow()
Use the SetCurrentRow() method to set values for multiple
columns at the same time. You must provide the column
names to set and the corresponding values to be set,
respectively, in the following two members of the Row
parameter:
• columnNames
• columnValues

SQLData Script Library User’s Guide

 Methods47

Syntax
result SetCurrentRow (
aaDBRow Row)

Parameters
Row
You can construct two ArrayList objects by using string
constants or valid Archestra reference strings.

Remarks
When you construct the input ArrayList object, you can
specify constants as well as valid ArchestrA reference
strings.
Necessary conversions are performed internally to cast
values to the specific column type.
The actual update to the data source is delayed until you call
SaveChangesSync() or SaveChangesAsync().
If SetCurrentRow() encounters a failure to change a
column, some columns may have already been changed in the
internal dataset. In this case, the internal dataset reverts to
the state it had immediately after the last update or
SaveChanges() call. It is possible that this reversion of the
internal dataset could undo changes applied prior to the
current SetCurrentRow() call. For instance, if the script has
a loop to modify 10 rows with SetCurrentRow() and nine
rows return without a bad error code but the tenth row
returns a bad error code, the internal dataset reverts to its
state before the first SetCurrentRow() call.
Example
Dim inputCol as System.Collections.ArrayList;

Dim inputVal as System.Collections.ArrayList;

Dim inputRow as aaDBClient.aaDBRow;

inputCol = new System.Collections.ArrayList();

inputCol.Add("Name");

inputCol.Add("Description");

inputCol.Add("DateTime");

inputVal = new System.Collections.ArrayList();

inputVal.Add("Name");

inputVal.Add(me.strValue);

inputVal.Add(me.DT);

SQLData Script Library User’s Guide

48  Chapter 3 aaDBCommand Object

inputRow.columnNames = inputCol;

inputRow.columnValues = inputVal;

SetCurrentRowColumnByIndex()
Use the SetCurrentRowColumnByIndex() method to
update the column at index columnNumber in the currently
selected row.

Syntax
result SetCurrentRowColumnByIndex (
int ColumnNumber,
object NewValue)

Parameters
ColumnNumber
The zero-based index of the column in the memory table.
NewValue
You can specify a constant or a valid ArchestrA reference
string. Both relative references and fully qualified
references are supported. For example:
• me.ShortDesc – relative reference
• UD1.status – fully qualified reference string
• "John Smith" – constant

Remarks
Necessary conversions are performed internally to cast
newValue to the column type.
When you try to change a value using this method and the
type passed in does not match the type specified for the
column in the database table, one of the following outcomes
occurs:
• The value is written with an automated type conversion
• The transaction fails completely because the conversion
would result in loss of data.
The actual update to the data source is delayed until you call
SaveChangesSync() or SaveChangesAsync().

SQLData Script Library User’s Guide

 Methods49

SetCurrentRowColumnByName()
Use the SetCurrentRowColumnByName() method to
update the column named ColumnName in the currently
selected row.

Syntax
result SetCurrentRowColumnByName (
string ColumnName,
object NewValue)

Parameters
ColumnName
String constant that is enclosed in quotation marks or
another ArchestrA reference that can evaluate to a
string. For example:
"LastName" – Spaces are allowed.
For more details see SQL Server documentation
regarding column naming rules.
NewValue
You can specify a constant or a valid ArchestrA reference
string. Both relative references and fully qualified
references are supported. For example:
• me.ShortDesc – relative reference
• UD1.status – fully qualified reference string
• "John Smith" – constant

Remarks
Necessary conversions are performed internally to cast
newValue to the column type.
When you try to change a value using this method and the
type passed in does not match the type specified for the
column in the database table, one of the following outcomes
occurs:
• The value is written with an automated type conversion
• The transaction fails completely because the conversion
would result in loss of data.
The actual update to the data source is delayed until you call
SaveChangesSync() or SaveChangesAsync().

SQLData Script Library User’s Guide

50  Chapter 3 aaDBCommand Object

SetParam Type Methods for SQL Server

and Oracle
Frequently, the SQL statement that you use to create a
command has parameters encoded in it. In such cases, you
must set values for all parameters needed as input by the
SQL statement before you run the command.
For SQL Server databases, parameters are indicated by
@<ParameterName> so that each parameter is named. The
following method call accommodates named parameters:
Set<Type>ParameterByName()

You must use the version of the method that matches the
way that you created your connection object. When you
create a connection object with
aaDBConnectionTypeOleDb, you must use the method
Set<Type>ParameterByIndex(). For all other connections,
use the method Set<Type>ParameterByName().
Parameters are usually mapped to a table column, which
always has a specific type. The method properties that you
must supply with each of the methods in this subsection
depend on the column type that they map to.
Separate methods are necessary because different column
types require that you specify different method parameters.
For example, a column of type NVarChar requires a length
be specified while a column type of Decimal requires
precision and scale.
The method parameters that are common across all methods
are:
• Parameter Name (parameterName)
• Parameter Value (parameterValue)
You can specify null for parameterValue when the
Parameter Direction is Output or ReturnValue.
Parameter Direction (parameterDirection) enumerated
values are:
• Input
• InputOutput
• Output
• ReturnValue

SQLData Script Library User’s Guide

 Methods51

Output Parameters
The GetParameterByIndex() and GetParameterByName()
methods return values to the script through InputOutput,
Output, or ReturnValue parameters.
It is not possible to return values directly to ArchestrA
attributes through InputOutput, Output or ReturnValue
parameters, only DIM script variables. This is a constraint of
the scripting infrastructure implemented in Application
Server version 3.0.
If you want the value returned by GetParameterByIndex()
or GetParameterByName() to set a value to an ArchestrA
attribute reference, perform the following steps:
1 Declare a local script variable and return the
InputOutput, Output, or ReturnValue parameter by
making a GetParameterByIndex() or
GetParameterByName() method call.
2 Use this local variable to set the desired ArchestrA
reference.

SetBitParameterByName()
Note: Do not use this method for the Oracle data type
Boolean value. Use SetIntParameterByName instead.

Use the SetBitParameterByName() method to configure a

bit parameter by the name encoded into the text of a SQL
statement using the @ character.

Syntax
result SetBitParameterByName (
string ParameterName,
object ParameterValue,
aaDBParameterDirection ParameterDirection)

Parameters
ParameterName
String identifier used in the SQL statement.
In the following SQL statement the parameter name is
boolValue.
"SELECT StateProvinceID
,StateProvinceCode
,CountryRegionCode
,IsOnlyStateProvinceFlag
,Name
,TerritoryID

SQLData Script Library User’s Guide

52  Chapter 3 aaDBCommand Object

,rowguid
,ModifiedDate
FROM AdventureWorks.Person.StateProvince
WHERE IsOnlyStateProvinceFlag = @boolValue"

ParameterValue
A discrete value or a valid ArchestrA reference string.
For example:
• 0
• false
• me.boolValue

Example
SetBitParameterByName ("boolValue", me.boolValue,
aaDBParameterDirection.Input)

SetCharParameterByName()
Use the SetCharParameterByName() method to configure a
character string parameter by the name encoded into the text
of a SQL statement using the @ character.

Syntax
result SetCharParameterByName (
string ParameterName,
object ParameterValue,
aaDBParameterDirection ParameterDirection,
int Length)

Parameters
ParameterName
The string identifier that is used in the SQL statement.
In the following SQL statement the input parameter is
"lastName."
"SELECT * FROM Person.Contact WHERE (LastName =
@lastName)"

ParameterValue
A string constant or valid ArchestrA reference string. For
example:
• "Smith"
• me.LastName
• null - Output and ReturnValue parameters.
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.

SQLData Script Library User’s Guide

 Methods53

Length
Specifies the maximum length of the parameter.
If the length of the parameterValue is greater, the
parameterValue is truncated to the specified length.

Example
SetCharParameterByName ("lastName",
"Smith",aaDBParameterDirection.Input, 50)

SetDecimalParameterByName()
Use the SetDecimalParameterByName() method to
configure a decimal parameter by the name encoded into the
text of a SQL statement using the @ character.

Syntax
result SetDecimalParameterByName (
string ParameterName,
object ParameterValue,
aaDBParameterDirection ParameterDirection,
short Precision,
short Scale)

Parameters
ParameterName
The string identifier used in the SQL statement.
In the following SQL statement the name of the
parameter is "RejectedQuantity".
"INSERT INTO Purchasing.PurchaseOrderDetail
(PurchaseOrderID
,DueDate
,OrderQty
,ProductID
,UnitPrice
,ReceivedQty
,RejectedQty
,ModifiedDate)
VALUES
(4,'2008-01-28',4,4,4,12.89,@RejectedQuantity,
'2008-01-28') "

ParameterValue
This parameter supports float, double or string values.
You can also specify a valid ArchestrA reference string.
For example:
• 123.333

SQLData Script Library User’s Guide

54  Chapter 3 aaDBCommand Object

• "123.333333333333333333"
• me.Quantity
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.
Precision
A number that indicates the total number of digits.
Scale
A number that indicates the number of digits to the right
of the decimal point.

Example
SetDecimalParameterByName ("RejectedQuantity",
me.Quantity,aaDBParameterDirection.Input, 8, 2)

SetDateTimeParameterByName()
Use the SetDateTimeParameterByName() method to
configure a DateTime parameter by the name encoded into
the text of a SQL statement using the @ character.

Syntax
result SetDateTimeParameterByName (
string ParameterName,
object ParameterValue,
aaDBParameterDirection ParameterDirection)

Parameters
ParameterName
The string identifier used in the SQL statement. For
example, in the following SQL statement, the name of the
parameter is "NewDate"
"INSERT INTO Purchasing.PurchaseOrderDetail
(PurchaseOrderID
,DueDate
,OrderQty
,ProductID
,UnitPrice
,ReceivedQty
,RejectedQty
,ModifiedDate)
VALUES
(4,'2008-01-28',4,4,4,12.89,12.56,@NewDate)"

SQLData Script Library User’s Guide

 Methods55

ParameterValue
The DateTime, string value, or a valid ArchestrA
reference string.
For example:
• '2004-03-11 10:17:21.587'
• me.dtValue
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.

Example
SetDateTimeParameterByName
("NewDate",me.dtValue,aaDBParameterDirection.Input)

SetDoubleParameterByName()
Use the SetDoubleParameterByName() method to
configure a double parameter by the name encoded into the
text of a SQL statement using the @ character.

Syntax
result SetDoubleParameterByName (
string ParameterName,
object ParameterValue,
aaDBParameterDirection ParameterDirection)

Parameters
ParameterName
The string identifier used in the SQL statement.
In the following SQL statement the output parameter
name is "AvgReject"
"SELECT @AvgReject = Avg(RejectedQty)
FROM Purchasing.PurchaseOrderDetail "

ParameterValue
A double-precision floating number or a valid ArchestrA
reference string. For example:
• 123.333
• me.Limit
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.

SQLData Script Library User’s Guide

56  Chapter 3 aaDBCommand Object

Example
SetDoubleParameterByName
("AvgReject",null,aaDBParameterDirection.Output)

SetFloatParameterByName()
Use the SetFloatParameterByName() method to configure
a float parameter by the name encoded into the text of a SQL
statement using the @ character.

Syntax
result SetFloatParameterByName (
string ParameterName,
object ParameterValue,
aaDBParameterDirection ParameterDirection

Parameters
ParameterName
String identifier used in the SQL statement.
In the following SQL statement the name of the output
parameter is "AvgReject."
"SELECT @AvgReject = Avg(RejectedQty)
FROM Purchasing.PurchaseOrderDetail "

ParameterValue
A floating number or a valid ArchestrA reference string.
For example:
• 123.333
• me.Limit
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.

Example
SetFloatParameterByName ("AvgReject", null,
aaDBParameterDirection.Output)

SQLData Script Library User’s Guide

 Methods57

SetIntParameterByName()
Use the SetIntParameterByName() method to configure an
integer parameter by the name encoded into the text of a
SQL statement using the @ character.

Note: Use this method for the Oracle data type Boolean.It is
specific to Oracle.

Syntax
result SetIntParameterByName (
string ParameterName,
object ParameterValue,
aaDBParameterDirection ParameterDirection)

Parameters
ParameterName
The string identifier that is used in the SQL statement.
In the following SQL statement the name of the output
parameter is "Cnt"
"SELECT @Cnt=Count (*)(RejectedQty)
FROM Person.Contact "

ParameterValue
An integer value or a valid ArchestrA reference string.
For example:
• 10
• me.OrderCount
• Null - Output
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.

Example
SetIntParameterByName ("Cnt", null,
aaDBParameterDirection.Output)

SQLData Script Library User’s Guide

58  Chapter 3 aaDBCommand Object

SetLongParameterByName()
Use the SetLongParameterByName() method to configure
a long parameter by the name encoded into the text of a SQL
statement using the @ character.

Syntax
result SetLongParameterByName (
string ParameterName,
object ParameterValue,
aaDBParameterDirection ParameterDirection)

Parameters
ParameterName
The string identifier that is used in the SQL statement.
In the following SQL statement the name of the output
parameter is "ProdID"
"SELECT ProductID, SUM(WorkOrderID)
AS OrderCnt
FROM Production.WorkOrder
WHERE ProductID = @ProdID
GROUP BY ProductID"

ParameterValue
An integer value or a valid ArchestrA reference string.
For example:
• 10
• me.ProductID
• Null - Output
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.

Example
SetLongParameterByName
("ProdID",me.ProductID,aaDBParameterDirection.Output
)

SQLData Script Library User’s Guide

 Methods59

SetParam Type Methods for OLEDB

Frequently, the SQL statement that you use to create a
command has parameters encoded in it. In such cases, you
must set values for all parameters needed as input by the
SQL statement before you run the command.
For data providers accessed through OLEDB, parameters are
indicated by identical placeholder characters, and
parameters must be indicated by index. The method call
Set<Type>ParameterByIndex() accommodates the indexed
parameters of OLEDB.
Parameters are usually mapped to a table column, which
always has a specific type. The method parameters that you
supply with each of the methods in this subsection vary
depending on the column type that they map to.

Note: Because parameters are sequentially numbered, it is

important that there be no gaps in the sequence. The
sequence is checked when the command object with
parameters is executed. Gaps cause the command object to
fail.

It is necessary to have separate methods because different

column types require that you specify different method
parameters.
For example a column of type NVarChar requires that you
specify a length, while a column type of Decimal requires
that you specify precision and scale.
The following method parameters are common across all
methods:
• Parameter Index (Index) – this is 1-based
• Parameter Value (parameterValue)
You can specify null for parameterValue when the
parameterDirection is Output or ReturnValue.

• Parameter Direction (parameterDirection)

The following are enumerated values:
• Input
• InputOutput
• Output
• ReturnValue

SQLData Script Library User’s Guide

60  Chapter 3 aaDBCommand Object

SetBitParameterByIndex()
Use the SetBitParameterByIndex() method to configure a
bit parameter as encoded into the text of an OLEDB SQL
statement.

Syntax
result SetBitParameterByIndex (
int Index,
object ParameterValue,
aaDBParameterDirection ParameterDirection)

Parameters
Index
The sequential index of the parameter as used in the SQL
statement.
In the following SQL statement, the parameter
corresponds to the question mark (?) character:
"SELECT StateProvinceID
,StateProvinceCode
,CountryRegionCode
,IsOnlyStateProvinceFlag
,Name
,TerritoryID
,rowguid
,ModifiedDate
FROM AdventureWorks.Person.StateProvince
WHERE IsOnlyStateProvinceFlag = ?"

ParameterValue
A discrete value or a valid ArchestrA reference string.
For example:
• 0.
• false.
• me.boolValue.
• ParameterDirection. For possible values, see
aaDBParameterDirection on page 70.

Example
SetBitParameterByIndex (0, me.boolValue,
aaDBParameterDirection.Input)

SQLData Script Library User’s Guide

 Methods61

SetCharParameterByIndex()
Use the SetCharParameterByIndex() method to configure a
character string parameter as encoded into the text of an
OLEDB SQL statement.

Syntax
result SetCharParameterByIndex (

int Index,

string ParameterValue,

aaDBParameterDirection ParameterDirection,

int Length)

Parameters
Index
The sequential index of the parameter as used in the SQL
statement.
In the following SQL statement the input parameter
corresponds to the question mark (?) character.
"SELECT * FROM Person.Contact WHERE (LastName > ?)"

ParameterValue
A string constant or valid ArchestrA reference string. For
example:
• "Smith"
• me.LastName
• null - Output and ReturnValue parameters
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.
Length
The maximum length of the parameter.
If the length of the parameterValue is greater, the
parameterValue is truncated to the specified length.

Example
SetCharParameterByIndex (0,
"Smith",aaDBParameterDirection.Input, 50)

SQLData Script Library User’s Guide

62  Chapter 3 aaDBCommand Object

SetDateTimeParameterByIndex()
Use the SetDateTimeParameterByIndex() method to
configure a DateTime parameter as encoded into the text of
an OLEDB SQL statement.

Syntax
result SetDateTimeParameterByIndex (
int Index,
object ParameterValue,
aaDBParameterDirection Parameterdirection)

Parameters
Index
The sequential index of the parameter as used in the SQL
statement. For example:
In the following SQL statement the parameter
corresponds to the question mark (?) character:
"INSERT INTO Purchasing.PurchaseOrderDetail
(PurchaseOrderID
,DueDate
,OrderQty
,ProductID
,UnitPrice
,ReceivedQty
,RejectedQty
,ModifiedDate)
VALUES
(4,'2008-01-28',4,4,4,12.89,12.56,?)"

ParameterValue
DateTime, string value, or a valid ArchestrA reference
string.
For example:
• '2004-03-11 10:17:21.587'
• me.dtValue
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.

Example
SetDateTimeParameterByIndex (1, me.dtValue,
aaDBParameterDirection.Input)

SQLData Script Library User’s Guide

 Methods63

SetDecimalParameterByIndex()
Use the SetDecimalParameterByIndex() method to
configure a decimal parameter as encoded into the text of an
OLEDB SQL statement.

Syntax
result SetDecimalParameterByIndex (
int Index,
object ParameterValue,
aaDBParameterDirection ParameterDirection,
short Precision,
short Scale)

Parameters
Index
Sequential index of the parameter as used in the SQL
statement. For example:
In the following SQL statement the parameter
corresponds to the question mark (?) character:
"INSERT INTO Purchasing.PurchaseOrderDetail
(PurchaseOrderID
,DueDate
,OrderQty
,ProductID
,UnitPrice
,ReceivedQty
,RejectedQty
,ModifiedDate)
VALUES
(4,'2008-01-28',4,4,4,12.89,?,'2008-01-28') "

ParameterValue
This parameter supports float, double, or string values.
You can also specify a valid ArchestrA reference string.
For example:
• 123.333
• "123.333333333333333333"
• me.Quantity
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.
Precision
A number that indicates the total number of digits.

SQLData Script Library User’s Guide

64  Chapter 3 aaDBCommand Object

Scale
A number that indicates the number of digits to the right
of the decimal point.

Example
SetDecimalParameterByIndex (1,
me.Quantity,aaDBParameterDirection.Input, 8, 2)

SetDoubleParameterByIndex()
Use the SetDoubleParameterByIndex() method to
configure a double parameter as encoded into the text of an
OLEDB SQL statement.

Syntax
result SetDoubleParameterByIndex (
int Index,
object ParameterValue,
aaDBParameterDirection ParameterDirection)

Parameters
Index
The sequential index of the parameter as used in the SQL
statement.
In the following SQL statement, the output parameter
corresponds to the question mark (?) character:
"SELECT ? = Avg(RejectedQty)
FROM Purchasing.PurchaseOrderDetail "

ParameterValue
A double-precision floating number or a valid ArchestrA
reference string. For example:
• 123.333
• me.Limit
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.

Example
SetDoubleParameterByIndex (1, null,
aaDBParameterDirection.Output)

SQLData Script Library User’s Guide

 Methods65

SetFloatParameterByIndex()
Use the SetFloatParameterByIndex() method to configure
a float parameter as encoded into the text of an OLEDB SQL
statement.

Syntax
result SetFloatParameterByIndex (
int Index,
object ParameterValue,
aaDBParameterDirection ParameterDirection)

Parameters
Index
The sequential index of the parameter as used in the SQL
statement.
In the following SQL statement the output parameter
corresponds to the question mark (?) character:
"SELECT ? = Avg(RejectedQty)
FROM Purchasing.PurchaseOrderDetail "

ParameterValue
A double-precision floating number or a valid ArchestrA
reference string. For example:
• 123.333
• me.Limit
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.

Example
SetFloatParameterByIndex (1, null,
aaDBParameterDirection.Output)

SetIntParameterByIndex()
Use the SetIntParameterByIndex() method to configure a
integer parameter as encoded into the text of an OLEDB SQL
statement.

Syntax
result SetIntParameterByIndex (
int Index,
object ParameterValue,
aaDBParameterDirection ParameterDirection)

SQLData Script Library User’s Guide

66  Chapter 3 aaDBCommand Object

Parameters
Index
The sequential index of the parameter as used in the SQL
statement.
In the following SQL statement the output parameter
corresponds to the question mark (?) character.:
"SELECT ? = Avg(RejectedQty)
FROM Purchasing.PurchaseOrderDetail "

ParameterValue
A double-precision floating number or a valid ArchestrA
reference string. For example:
• 123.333
• me.Limit
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.

Example
SetIntParameterByIndex (1, null,
aaDBParameterDirection.Output)

SetLongParameterByIndex()
Use the SetLongParameterByIndex() method to configure
a long parameter as encoded into the text of an OLEDB SQL
statement.

Syntax
result SetLongParameterByIndex (
int Index,
object ParameterValue,
aaDBParameterDirection ParameterDirection)

Parameters
Index
The sequential index of the parameter as used in the SQL
statement.
In the following SQL statement the output parameter
corresponds to the question mark (?) character:
" SELECT ProductID, SUM(WorkOrderID) AS OrderCnt
FROM Production.WorkOrder
WHERE ProductID = ?
GROUP BY ProductID"

SQLData Script Library User’s Guide

 Properties67

ParameterValue
A double-precision floating number or a valid ArchestrA
reference string. For example:
• 123.333
• me.ProductID
ParameterDirection
For possible values, see aaDBParameterDirection on
page 70.

Example
SetLongParameterByIndex (1, me.ProductID,
aaDBParameterDirection.Output)

Properties
You can use the following properties with the
aaDBCommand object.

CommandTimeout
This property accesses the underlying CommandTimeout
property of the DCM command object. The DCM command
object in turn, accesses the
ADO.NetDbCommand.CommandTimeout property.
According to MSDN, this CommandTimeout property gets
or sets the wait time before terminating the attempt to run a
command object and generating an error.
Notes:

• If the DCM command object has been removed or is

otherwise invalid, reading this property returns 0;
writing it has no effect. An exception is not thrown.
• When aaDBConnectionType=Oracle, this property is not
supported. Setting a command object timeout has no
effect, and the value returned is always 0.

CurrentRowNumber
This read-only property returns the row value most recently
set by the last call to SelectRow() or the new row number
that has been created if AddRow() has been called since
SelectRow().
This property returns a value of -1 if any of the following
conditions occurred:
• A call to SelectRow() was not made.

SQLData Script Library User’s Guide

68  Chapter 3 aaDBCommand Object

• An invalid row number was passed in the last call to

SelectRow().

• DeleteCurrentRow() was called.

Syntax
long CurrentRowNumber;

CurrentTableNumber
This read-only property returns the table index most recently
set by the last call to SelectTable().
This property returns 0 by default immediately after a
command object (returning a dataset that is not empty) is
run successfully.
This property returns -1 if any of the following conditions
occurred:
• An invalid index was passed in the last call to
SelectTable()
• The resulting dataset is empty

Syntax
long CurrentTableNumber;

Disposed
This read-only property returns a Boolean value that
indicates whether the command object has been disposed. If
disposed, the command object can no longer be used.

ExecutionState
This read-only property returns the execution state of a SQL
command. Because command processing can be
asynchronous, you must determine whether the command
has been processed before you request the execution state.

Syntax
aaDBCommandState.ExecutionState

LastExecutionError
This property returns the last error, if any, that is the error
string generated by the provider.
Use this property in conjunction with the ExecutionState
property.

SQLData Script Library User’s Guide

 Public Enumerations69

The LasExecutionError property returns the error

generated by the provider for the failed command object.

Syntax
string LastExecutionError

RowCount
Use this read-only property to obtain the number of records
in the memory dataset that was retrieved by a SQL
command. When it is used with a SQL action command such
as INSERT, DELETE, or UPDATE, the property returns the
number of records affected.
This property returns a value of zero in the following cases:
• The SQL command has not been queued.
• The SQL command has been queued but is not completed.
• The SQL command has completed with an error.

Syntax
int RowCount;

Public Enumerations
The following public enumerations apply to the
aaDBCommand object.

aaDBCommandState
This public enumeration indicates the state of an
aaDBCommand object.

Created
This value indicates that the command has been created.
However, the command has not yet run, and you can assign
parameters to the command.

Queued
This value indicates that the command is queued for
execution. This state occurs immediately after the call to
aaDBCommand.ExecuteAsync() or
aaDBCommand.ExecuteSync(). Queued is a transitional
state that changes to either Failed or Completed.

SQLData Script Library User’s Guide

70  Chapter 3 aaDBCommand Object

Failed
This value indicates that the command failed.

Completed
This value indicates that the command completed
successfully.

Canceled
This value indicates that the command has been canceled.

Disposed
This value indicates that Dispose() has been called for the
command object. Disposed is automatically set when
aaDBAccess.RemoveCommand() is called, or when
Dispose() is called on the connection object or transaction
object that owns the command.

aaDBCommandType
This public enumeration describes how the command text for
an aaDBCommand object is used.

Note: When you use the aaDBCommandType

enumeration, be aware that not all requests work with all data
providers. For example, Microsoft Access does not support
stored procedures. The InputOutput direction is not supported
by all data providers. Always check the documentation for the
data providers about supported options.

sqlStatement
Indicates that the command text is a valid SQL statement.

storedProcedure
Indicates that the command text is a stored procedure name.

aaDBParameterDirection
This public enumeration indicates the direction of
parameters used for SQL statements.

SQLData Script Library User’s Guide

 Public Enumerations71

Note: When you use the aaDBParameterDirection

enumeration, be aware that not all requests work with all data
providers. For example, Microsoft Access does not support
stored procedures. The InputOutput direction is not supported
by all data providers. Always check the documentation for the
data providers about supported options.

Input
This value indicates that the parameter is input only.

InputOutput
This value indicates that the parameter is capable of both
input and output.

Output
This value indicates that the parameter is output only.

ReturnValue
This value indicates the presence of a return value from an
operations such as a stored procedure, built-in function, or
user-defined function.

SQLData Script Library User’s Guide

72  Chapter 3 aaDBCommand Object

SQLData Script Library User’s Guide

 73

Chapter 4

aaDBConnection Object

This section discuses aaDBConnection object and the

methods and properties that you can use with it.

aaDBConnection Object
Use objects of type aaDBConnection to create a new
aaDBCommand object or aaDBTransaction object. You can
create instances of aaDBConnection only through the static
methods aaDBAccess.CreateConnection() or
aaDBAccess.GetConnection().
Creating an instance of the aaDBConnection object is not
equivalent to creating and maintaining a physical connection
to the data source.
The actual physical connection opens on demand when a
request is made to run aaDBCommand objects or
aaDBTransaction objects. The physical connections are
controlled by the Database Connection Manager (DCM).
The SQLData Script Library does not expose any mechanism
to allow you to fine-tune its behavior, such as defining how
many connections to use.

SQLData Script Library User’s Guide

74  Chapter 4 aaDBConnection Object

Connection Pooling
When you request a SQL command or transaction to be run
on the aaDBConnection object, an actual physical
connection is opened on demand and closed when the
command or transaction finishes processing.
The SQLData Script Library uses the DCM common
component in regard to connection pooling. When an
aaDBConnection object is first created, no attempt is made
to achieve a physical connection. The ConnectionState
property remains in the Disconnected state. The physical
connection is attempted only after a command object is run (a
stand-alone command object or a command object that is part
of a transaction).
After the first command object that requires a physical
connection runs, the physical connection remains open for an
unspecified period (depending on loading) and closes
automatically after a time.
If a script requires confirmation of a successful physical
connection, it must issue some benign SQL statement and
then check the ConnectionState property of the connection.

Note: You must call Dispose() on each instance of

aaDBConnection.

Methods
You can use the following methods with the
aaDBConnection object.

CreateCommand()
Use the CreateCommand() method to create a new
aaDBCommand object.

Syntax
aaDBCommand CreateCommand(
string CommandText,
aaDBCommandType CommandType,
bool ReturnDataset)

SQLData Script Library User’s Guide

 Methods75

Parameters
You can also configure the newly created object by adding
parameters and then executing them.
The parameters are identified in the SQL statement by
the at sign (@) character when ProviderType is SQL.
The following SQL statement has one parameter,
lastName:
"SELECT * FROM Person.Contact WHERE (LastName >
@lastName)"

CreateCommand for Oracle

The parameters are identified in the SQL statement by the
colon (:) character when ProviderType is Oracle.
"SELECT * FROM Person.Contact WHERE (LastName >
:lastName)"

CreateCommand for OLEDB

The parameters are identified in the SQL statement by the
question mark (?) character and no name when
ProviderType is OLEDB.
"SELECT * FROM Person.Contact WHERE (LastName > ?)"

In this case, you configure the parameters by index and not

by name.
Be aware that you cannot mix configuration parameters by
index and by name.

Return Value
If a failure occurs, this method returns null.
Getting the ExecutionState property of the newly-created
command object returns Created.

Parameters
CommandText
One of the following:
SQL Statement
Stored Procedure name
CommandType
Specifies how the SQL statement is handled:
sqlStatement
storedProcedure

SQLData Script Library User’s Guide

76  Chapter 4 aaDBConnection Object

ReturnDataset
Boolean, indicates if the command object is to return a
dataset
If True, you want a data table to be returned. For
example:

sqlStatement ="SELECT * FROM Person.Contact"

If False, you want to modify only the database or get the
Output or ReturnValue parameter. Examples are
INSERT, DELETE, and UPDATE SQL statements.
The data that is returned upon successful execution of a
query (Table, View or StoredProcedure) is stored in memory.
Scalar values are not returned, other than by being part of
the returned dataset.
You can then access this data by using the interface provided
by the aaDBCommand object.

CreateTransaction()
Use the CreateTransaction() method to create a new
aaDBTransaction object.

Syntax
aaDBTransaction CreateTransaction()

Return Value
If a failure occurs, this method returns null.
Getting the ExecutionState property of the newly-created
aaDBTransaction object returns Created.

Remarks
You add aaDBCommand objects to this object that are
processed as a whole in the order that they were added.

Dispose()
Use the Dispose() method to free all memory resources
associated this database connection object.

Syntax
void Dispose()

Remarks
If commands or transactions are running when Dispose() is
called, Dispose() cancels the command or transaction object.

SQLData Script Library User’s Guide

 Properties77

GetDiagnostics()
Use the GetDiagnostics() method to return a set of
diagnostic information about all connections in a dataset.

Syntax
void GetDiagnostics()

Remarks
The returned dataset contains multiple tables. The table
with index 0 contains the global diagnostics. The rest of the
tables in the dataset correspond to each DCMConnection
object. For details about diagnostic properties, see the
SQLData Object Help.

LogDiagnostics()
Use the LogDiagnostics() method to dump a snapshot of all
available connection diagnostic information to the logger. For
details about diagnostic properties, see the SQLData Object
Help.

Syntax
void LogDiagnostics()

ResetDiagnostics
Use the ResetDiagnostics() method to reset the current
diagnostic values of the connection object.

Syntax
void ResetDiagnostics()

Properties
You can use the following properties with the
aaDBConnection object.

ConnectionName
Use this property to enable the log of diagnostics that was
generated by calling aaDBAccess.LogDiagnostics() to
include a meaningful name. Having a meaningful name may
be necessary if a debugging effort requires you to distinguish
one connection from another. To see the connection name in
the logged diagnostics, look for the line that reads as follows:

SQLData Script Library User’s Guide

78  Chapter 4 aaDBConnection Object

aaDBIntegration ConnectionName, <Name>, , Clilent assigned conection name,

The <Name> part of the line is replaced with the name that
the script has applied to the ConnectionName property of the
aaDBConnection object. If the ConnectionName property has
not been assigned a name by the script, it defaults to a name
of the form SQLScriptConnection<N>, where <N> is an
incrementing integer value.

Syntax
String ConnectionName

ConnectionState
Use this read-only property to verify that the connection
string specified by GetConnection successfully establishes
the initial connection to the data source.

Note: You cannot use this property to determine the status

of an actual physical connection to the data source. No polling
mechanism is available to detect a broken connection.

If intermittent network failures occur, ConnectionState

does not indicate the failure until a command or transaction
is run. However, when a command is run, the
ConnectionState property updates the current connection
state.
The return type is an enumerated value of type
aaDBConnectionState.

Syntax
aaDBConnectionState ConnectionState

Disposed
This read-only property indicates whether Disposed() has
been called for a connection object. If the property returns
True, no other method or property can be called on this
instance.

Syntax
Bool Disposed

LastError
Use this read-only property with the ExecutionState
property. It returns the last error string generated by the
provider.

SQLData Script Library User’s Guide

 Public Enumerations79

This property shows a description of errors that were

encountered while parsing the connection string. The string
comes from exceptions thrown by the Microsoft object or
data provider objects.

Syntax
string LastError

Public Enumerations
The following public enumerations apply to the
aaDBConnection objects.

aaDBConnectionState
This public enumeration determines the state of the
aaDBConnection object. Each value reflects the current
state of the connection in the DCM.

Disconnected
Disconnected is the state of the aaDBConnection object
immediately after it transitions through Connected or fails to
connect. The disconnect timing is controlled by the
underlying ADO.Net communication pooling logic. The
Disconnected state remains active until the DCM is
required to create a physical connection in response to a
command.
A previous connected state can transition to a disconnected
state if a command is run and the physical connection has
been lost.

Connecting
This value indicates a transition state. It indicates that the
DCM has started a physical connection to a database based
on its internal connection pooling logic and the connection is
not complete or has not yet failed.

Connected
This value indicates that the DCM has established a physical
connection to a database in response to a command.

SQLData Script Library User’s Guide

80  Chapter 4 aaDBConnection Object

Created
This value indicates the initial state for a connection after
creation until a transaction or command is run on it. After
the state changes to something else, the state can never
return to Created.

Disposed
This value indicates that Dispose() has been called for the
connection.

aaDBConnectionType
This public enumeration determines the type of connection
that an aaDBConnection object is being created for.

Sql
This value indicates a connection for a Microsoft SQL Server
database.

OleDb
This value indicates a connection using Microsoft OLEDB.

Oracle
This value indicates a connection for an Oracle database
server.

SQLData Script Library User’s Guide

 81

Chapter 5

aaDBRow Object

This section describes the aaDBRow object and the methods

and properties that you can use with it.

aaDBRow Object
Use objects of type aaDBRow to access (set or get) a single
row from the memory dataset generated while an
aaDBCommand object is running.
An instance of the aaDBRow object is returned by
aaDBCommand.GetRow(). SetCurrentRow() also requires an
instance of this type as an input parameter.
You can modify the aaDBRow object returned by GetRow()
and feed it back to SetCurrentRow(), or you can construct a
new aaDBRow object specifically for SetCurrentRow().
The aaDBRow object has two public members both of type
ArrayList:

• columnName
• columnValue

Note: You can use this type to update a row in the memory
table by configuring only a subset of the columns.

The two arrays must have the same size.

Note: You must call Dispose() on each instance of

aaDBRow.

SQLData Script Library User’s Guide

82  Chapter 5 aaDBRow Object

aaDBRow —Public Constructor

You can use a public constructor in a script to create an
aaDBRow object from two synchronized ArrayList objects
for use with aaDBCommand.SetCurrentRow().
To use this constructor, first create the new ArrayList
objects, and fill them with column names and values. Use
positional placement within the two ArrayList objects to
correspond names with values.
Then create a new aaDBRow object with this constructor,
passing in the two ArrayList objects. For an example, see the
parameters table in the aaDBConnection.SetCurrentRow()
section.

Syntax
aaDBRow(

ArrayList Names,
ArrayList Values)

Methods
You can use the following methods with the aaDBRow
object.

aaDBRow —Public Constructor

You can use a public constructor in a script to create an
aaDBRow object from two synchronized ArrayList objects
for use with aaDBCommand.SetCurrentRow().
To use this constructor, first create the new ArrayList
objects, and fill them with column names and values. Use
positional placement within the two ArrayList objects to
correspond names with values.
Then create a new aaDBRow object with this constructor,
passing in the two ArrayList objects. For an example, see the
parameters table in the aaDBConnection.SetCurrentRow()
section.

Syntax
aaDBRow(

ArrayList Names,
ArrayList Values)

SQLData Script Library User’s Guide

 Properties83

GetColumnName()
Use the GetColumnName() method to retrieve the name of
the column specified by ColumnNum.

Syntax
string GetColumnName(
int ColumnNum)

Return Value
If ColumnNum is equal to or greater than the number of
columns stored in the row, as returned by the ColumnCount
property, null is returned.

GetColumnValue()
Use the GetColumnValue() method to retrieve the value of
the column specified by ColumnNum.

Syntax
object GetColumnValue(
int ColumnNum)

Return Value
If ColumnNum is equal to or greater than the number of
columns stored in the row, as returned by the ColumnCount
property, null is returned.

Note: The value is returned as a generic object and must be

cast by the script to the intended type.

Properties
You can use the following properties with the aaDBRow
object.

ColumnCount
Use this read-only property to retrieve the number of
columns stored in the row object.

Syntax
int ColumnCount

SQLData Script Library User’s Guide

84  Chapter 5 aaDBRow Object

ColumnNames
Use this read-only property to retrieve the ArrayList that
internally stores the column names for the row.

Syntax
ArrayList ColumnNames

ColumnValues
Use this read-only property to retrieve the ArrayList that
internally stores the column values for the row.

Syntax
ArrayList ColumnValues

SQLData Script Library User’s Guide

 85

Chapter 6

aaDBTransaction Object

This section explains how to use the aaDBTransaction

object and the methods and properties associated with it.

aaDBTransaction
Use objects of type aaDBTransaction to process multiple
aaDBCommand objects as a single unit.
Create instances of type aaDBTransaction by calling the
CreateTransaction() method on an instance of the
aaDBConnection object. For example, assuming that the
aaDBConnection instance is called Connection:
Connection.CreateTransaction()

If you want to ensure that all SQL commands are run as a

whole or not run at all, you must create an instance of the
aaDBTransaction object. Use the instance to create
aaDBCommand objects.
When the transaction object is run, all aaDBCommand
objects that are added to this aaDBTransaction object are
run in the order that they were added. If the transaction is
rolled back, none of the objects are run.
Commands added to a transaction cannot be run as
stand-alone command objects but are automatically
processed when the transaction runs.
When a script requests the transaction object ID, the
transaction object is flagged to be persisted. The SQLData
Script Library persists the object across scripts and scan
cycles.

SQLData Script Library User’s Guide

86  Chapter 6 aaDBTransaction Object

You can retrieve an aaDBTransaction object at any time by

calling the static method aaDBAccess.GetTransaction ()
and passing the previously acquired string ID.

Note: You must call Dispose() on each instance of

aaDBTransaction.

Methods
You can use the following methods with the
aaDBTransaction object.

CreateCommand()
Use the CreateCommand() method to create a new
aaDBCommand object. You can configure the new object by
adding parameters and then running it.

Syntax
aaDBCommand CreateCommand(
string CommandText,
aaDBCommandType CommandType,
bool ReturnDataset)

Remarks
For more details, see Chapter 4, aaDBConnection Object.

Dispose()
Use the Dispose() method to instruct the SQLData Script
Library to free all resources allocated for the transaction
object and all commands that were added as part of this
transaction.

Syntax
void Dispose()

Remarks
If the transaction is currently running, Dispose()
automatically cancels the transaction before removing it.
The SQLData Script Library issues Dispose() calls for every
command in the transaction.
If an ID has been retrieved for this command, you must call
Dispose() or aaDBAccess.RemoveCommand().

SQLData Script Library User’s Guide

 Methods87

ExecuteAsync()
Use the ExecuteAsync() method to instruct the SQLData
Script Library to queue all command objects in the
transaction that are queued for later processing.
ExecuteAsync() returns immediately and processing occurs
in the background.

Syntax
Result ExecuteAsync()

Remarks
You can use the ExecutionState property to check for status.
If any commands complete with an error, the SQLData
Script Library issues a transaction rollback to prevent
changes to the data source.
After ExecuteAsync() is processed, you can still obtain a
reference to any commands that were added and analyze
their ExecutionState and LastExecutionError properties.
When the transaction object runs, all aaDBCommand
objects that are added to the aaDBTransaction are run in
the order that they were added. The following outcomes can
occur as the result of processing a transaction:
• Success: All commands succeeded. Each command shows
an ExecutionState of Completed. Any dataset for that
command is associated with it.
• Cancellation: Each command in the transaction shows
an ExecutionState of Canceled. Any data associated
with the command is removed.
• Failure: When one command in a transaction fails, the
command has an ExecutionState of Failed. All
commands preceding it show an ExecutionState of
Completed and retain any datasets that were part of
their successful processing.
To free all resources allocated for the transaction object and
the commands, you must call Dispose().

SQLData Script Library User’s Guide

88  Chapter 6 aaDBTransaction Object

ExecuteAsyncCancel()
Use the ExecuteAsyncCancel() method to instruct the
SQLData Script Library to roll back all commands that are
queued as part of a transaction.

Syntax
Result ExecuteAsyncCancel()

Remarks
You can use the ExecutionState property to check for status.
As a result of successful execution, all command objects
created from this transaction are canceled.

ExecuteSync()
Use the ExecuteSync() method to instruct the SQLData
Script Library to run all commands that are queued as part
of a transaction.

Syntax
Result ExecuteSync()

Remarks
Use the ExecutionState and LastExecutionError properties to
check for status of this method.
If any one of the commands completes with an error, the
SQLData Script Library issues a rollback action to guarantee
that the data source does not see any of the changes.
When the transaction object runs, all aaDBCommand
objects that are added to the aaDBTransaction are run in
the order that they were added. The following outcomes can
occur as the result of processing a transaction:
• Success: All commands succeeded. Each command shows
an ExecutionState of Completed. Any dataset for that
command is associated with it.
• Cancellation: Each command in the transaction shows
an ExecutionState of Canceled. Any data associated
with the command is removed.
• Failure: When one command in a transaction fails, that
command object has an ExecutionState of Failed. All
command objects preceding it show an ExecutionState of
Completed and retain any datasets that were part of
their successful processing.

SQLData Script Library User’s Guide

 Properties89

After ExecuteSync() is processed, you can still obtain a

reference to the command objects that were added and
analyze their ExecutionState and LastExecutionError
properties.
Use the LastExecutionError property to check if the
command failed or succeeded (success is indicated by a blank
string), since ExecuteSync() may return 0 in the case of a
failure instead of an error message.
To free all resources allocated for the aaDBTransaction
object and the aaDBCommand objects you must call
Dispose().

GetID()
Use the GetID() method if you want to retrieve the ID of an
aaDBTransaction object instance to get a reference to this
object at a later time in a different script or scan.
The SQLData Script Library generates a unique transaction
ID and persists the transaction object in memory.

Syntax
string GetID()

Return Value
If a failure occurs, the GetID() method returns null.

Note: The SQLData Script Library returns a string value, but

the script engine automatically attempts to cast this value to
other types. If the script assigns the returned ID to any other
type than string, the ID is corrupted and does not work in
future GetTransaction(ID) calls.

Properties
Use the following properties with the aaDBTransaction
object.

Disposed
This read-only property indicates whether Disposed() has
been called for a transaction object. If the property returns
True, no other method or property can be called on this
instance.

Syntax
Bool Disposed

SQLData Script Library User’s Guide

90  Chapter 6 aaDBTransaction Object

ExecutionState
Use this read-only property to return the state of this
transaction object.
Because the processing of the transaction is asynchronous,
you must determine if it has finished processing before you
request the results.

Syntax
aaDBTransactionState ExecutionState

FailedCommandID
Use this property to return the ID of the first failed command
object during transaction processing.
If the processing action succeeds, FailedCommandID = 0.
Syntax
string FailedCommandID

LastExecutionError
During processing, this property is set to the last error, if
any. The error string is the error string generated by the
provider.
Use this property in conjunction with the ExecutionState
property.
LastExecutionError indicates the error generated by the
provider for the first command object in the transaction that
failed.
To find the command object that failed to process, check the
FailedCommandID property.
LastExecutionError is blank when the transaction runs
successfully.

Syntax
string LastExecutionError

SQLData Script Library User’s Guide

 Public Enumeration91

Public Enumeration
The following public enumeration applies to the
aaDBTransaction object.

aaDBTransactionState
This public enumeration indicates the state of an
aaDBTransaction.

Created
This value indicates that a transaction has been created. The
transaction has not yet run. You can add commands to the
transaction.

Queued
This value indicates that the transaction has been queued to
run. This state occurs immediately after an
aaDBTRansaction.ExecutedAsync() or
aaDBTRansaction.ExecutedSync() call. Queued is a
transitional state that changes to either Failed or
Completed.

Failed
This value indicates that the transaction has failed.

Completed
This value indicates that the transaction completed
successfully.

Canceled
This value indicates that the transaction was canceled before
it could complete.

Disposed
This value indicates that the Dispose() method has been
called for the command object. Disposed is automatically set
when aaDBAccess.RemoveTransaction() is called or when
the connection object that owns the transaction is disposed.

SQLData Script Library User’s Guide

92  Chapter 6 aaDBTransaction Object

SQLData Script Library User’s Guide

 93

Chapter 7

Error Codes

Various API scripting methods return an error code as a

numeric value.
Methods with syntax descriptions that begin with “result”
return these numeric values.
This table shows the numeric value, its corresponding error,
and meaning of each error code.

Numeric
Value Error Text and Description

-1 Unknown Failure
This value indicates an exception whose reason could not be determined
at run time.
0 Success
This value indicates a good result; no error occurred.
100 SoftwareError
This indicates that the internal code returned an unexpected result, but
the case was handled.
1000 StatementNotReady
This error is returned when an aaDBCommand object is run, but it is
not properly prepared for processing.
1001 StatementFailed
This error is returned when an aaDBCommand object runs and fails to
complete properly. This result occurs when the SQL query is malformed.

SQLData Script Library User’s Guide

94  Chapter 7 Error Codes

Numeric
Value Error Text and Description

1002 DatasetIsNull
This error is returned when the results of an aaDBCommand object are
being examined or manipulated, but no dataset is associated with the
object. This message can mean that the command has not yet run, the
SQL query was malformed, or the object was not of a type to return data.
1003 DatasetIsEmpty
This error occurs when the currently selected row or table number is
beyond the end of the data in the dataset that is associated with the
aaDBCommand object.

1004 InvalidConnection
This error is returned when an aaDBCommand attempts to run and the
connection object it is attached to has not established a good connection
to the database.
1005 InvalidRowNum
This error is returned by aaDBCommand.SelectRow() when the row
number specified is negative or larger than the number of rows in the
dataset that is associated with the aaDBCommand object.
1006 InvalidColValue
This error is returned when a column is examined or manipulated by the
index and the index does not represent a valid column number.
1007 InvalidTableNum
This error is returned by aaDBCommandSelectTable() when the table
number does not represent a table that is currently stored in the dataset
that is associated with the aaDBCommand object.
1008 MissingParameter
This error is returned when an OLEDB style aaDBCommand object is
run and not all parameter indexes were supplied.
1009 NamedParametersNotSupported
This error is returned when an attempt is made to call
SetXXXParameterByName() for a non-OLEBB style aaDBCommand
object.
1010 ParameterNameIsRequired
This error is returned when an attempt is made to call
SetXXXParameterByIndex() for a non-OLEBB style aaDBCommand
object.

SQLData Script Library User’s Guide

 95

Numeric
Value Error Text and Description

1011 InvalidRequestOperationInProgress
This error is returned when an attempt is made to run an
aaDBCommand object that is currently processing.
If a command or transaction is currently in progress through
ExecuteAsync(), that same object cannot be executed again with
ExecuteAsync() or ExecuteSync() until the previous process is
complete. Only a single object can be in the processing queue at any time.
1012 SaveChangesNotSupportedForStoredProcedure
This error is returned when either SaveChangesSync() or
SaveChangesAsync() is called after manipulating the dataset associated
with an aaDBCommand object whose query was originally against a
stored procedure.
1013 InvalidRequestNotSupportedInCurrentState
This error is returned when the aaDBCommand object is not in a state
where the requested run or cancel can be honored.
1014 InvalidRequestPartOfTransaction
This error indicates that you attempted to run or save changes to an
aaDBCommand object that was created to be part of an
aaDBTransaction. This activity is not permitted.

1015 DCMObjectInvalid
This error indicates that the DCM cannot provide an object to support
aaDBConnection, aaDBCommand, aaDBTransaction.

1016 ObjectIsDisposed
The script attempted to use an object after calling Dispose().

SQLData Script Library User’s Guide

96  Chapter 7 Error Codes

SQLData Script Library User’s Guide

 97

Index

A GetRow() 44
aaDBAccess object 27, 31 properties 68
CreateConnection() 28, 30 CommandTimeout 68
GetCommand() 31 CurrentRowNumber 68
CurrentTableNumber 69
GetConnection() 28
Disposed 69
GetDiagnostics() 34
ExecutionState 69
GetTransaction() 34 LastExecutionError 69
LogDiagnostics() 34 RowCount 70
RemoveCommand() 35 SaveChangesAsync() 45
RemoveTransaction() 35 SaveChangesSync() 45
ResetDiagnostics() 36 SelectRow() 45
Shutdown() 36 SelectTable() 46
aaDBCommand object 37 SetBitParameterByName() 51
AddRow() 38 SetCharParameterByName() 52
DeleteCurrentRow() 39 SetCurrentRow() 46
Dispose() 39 SetCurrentRowByIndex() 48
ExecuteAsync() 40 SetCurrentRowColumnByName() 49
ExecuteAsyncCancel() 40 SetDateTimeParameterByName() 54
ExecuteSync() 40 SetDecimalParameterByName() 53
GetCurrentRowColumnByIndex() 41 SetDoubleParameterByName() 55
GetCurrentRowColumnByName() 41 SetFloatParameterByName() 56
GetDataSet() 42 SetIntParameterByName() 57
GetId() 42 SetLongParameterByName() 58
GetParameterByIndex() 43 aaDBCommandState public enumeration
GetParameterByName() 43 Canceled 71

SQLData Script Library User’s Guide

98 Index

Completed 71 Dispose() 86
Created 70 ExecuteAsync() 87
Disposed 71 ExecuteAsyncCancel() 88
Failed 70 ExecuteSync() 88
Queued 70 GetID() 89
aaDBCommandType public enumeration properties
sqlStatement 71 Disposed 89
storedProcedure 71 ExecutionState 90
aaDBConnection object 73 FailedCommandID 90
CreateCommand() 74 LastExecutionError 90
CreateTransaction() 76 aaDBTransactionState public
enumeration
Dispose() 76
Canceled 91
GetDiagnostics() 77
Completed 91
LogDiagnostics() 77
Created 91
properties
Disposed 91
ConnectionName 77
ConnectionState 78 Failed 91
Disposed 78 Queued 91
LastError 78 Access, example connection string 17
ResetDiagnostics() 77 accessing the SQLData Script Library 12
aaDBConnection public enumeration AddRow on aaDBCommand 38
Connected 79 architecture, script library 13
Connecting 79 asynchronous script example
Created 80 overview 19
Disconnected 79 process script code 22
Disposed 80 process script configuration 20
aaDBConnectionState public query script code 20
enumeration 79 query script configuration 20
aaDBConnectionType public authentication modes
enumeration SQL Server 30
OleDb 80 Windows account 29
Oracle 80 Windows integrated security 29
Sql 80
aaDBParameterDirection public C
enumeration Canceled value
Input 72 aaDBCommandState public
InputOutput 72 enumeration 71
Output 72 aaDBTransaction public
ReturnValue 72 enumeration 91
aaDBRow object 81 ColumnCount property for aaDBRow 83
GetColumnName() 83 ColumnNames property for aaDBRow 84
GetColumnValue() 83 ColumnValues property for aaDBRow 84
properties command objects, creating 15
ColumnCount 83 commands, creating new 73
ColumnNames 84 CommandTimeout property 68
ColumnValues 84 Completed value
public constructor 82 aaDBCommandState public
aaDBTransaction object 85 enumeration 71
CreateCommand() 86

SQLData Script Library User’s Guide

 99

aaDBTransaction public aaDBCommand 39

enumeration 91 aaDBConnection 76
Connected value for aaDBTransaction 86
aaDBConnectionState public Disposed property 69
enumeration 79
aaDBConnection 78
Connecting value for
aaDBTransaction 89
aaDBConnectionState public
enumeration 79 Disposed value
connection objects aaDBCommandState public
enumeration 71
creating 28
aaDBConnectionState public
creating with command 15
enumeration 80
creating with transaction 15
aaDBTransaction public
reusable 27 enumeration 91
unique 28 Documentation 9
connection pooling 11, 28 documentation conventions 9
diagram 13
ConnectionName property for E
aaDBConnection 77
example scripts
connections
asynchronous
pooling 11, 28
overview 19
working with 28 process script code 22
ConnectionState property for process script configuration 20
aaDBConnection 78 query script code 20
conventions, documentation 9 query script configuration 20
CreateCommand() connecting to Microsoft Access data 17
aaDBConnection 74 connecting to Microsoft Excel data 17
aaDBTransaction 86 connecting to Oracle data source 17
CreateConnection() on aaDBAccess connecting to SQL Server data
objects 30 source 16
Created value detailed description 18
aaDBCommandState public overview 17
enumeration 70 synchronous
aaDBConnectionState public code 24
enumeration 80
configuration 23
aaDBTransaction public overview 23
enumeration 91
Excel
CreateTransaction()
example connection string 17
aaDBConnection 76
transaction support 17
CurrentRowNumber property 68
ExecuteAsync()
CurrentTableNumber property 69
aaDBCommand 40
aaDBTransaction 87
D
ExecuteAsyncCancel()
DeleteCurrentRow() on
aaDBCommand 40
aaDBCommand 39
aaDBTransaction 88
differences between CreateConnection()
and GetConnection 28 ExecuteSync()
Disconnected value for aaDBCommand 40
aaDBConnectionState public aaDBTransaction 88
enumeration 79 ExecutionState property
Dispose() aaDBCommand 69

SQLData Script Library User’s Guide

100Index

aaDBTransaction 90 LastExecutionError property

aaDBCommand 69
F aaDBTransaction 90
Failed value LogDiagnostics()
aaDBCommandState public aaDBConnection 77
enumeration 70 LogDiagnostics() on aaDBAccess
aaDBTransaction public objects 34
enumeration 91
FailedCommandID property for M
aaDBTransaction 90 multiple commands, processing as single
functions of SQLData Script Library 12 unit 85

G N
GetColumnName() for aaDBRow 83 new command, creating 73
GetColumnValue() for aaDBRow 83 new transaction object, creating 73
GetCommand() on aaDBAccess
objects 31 O
GetConnection() 31 OLEDB
on aaDBAccess objects 31 SetParam type methods 58
GetCurrentRowColumnByIndex() on OLEDB databases
aaDBCommand0. 41
connecting to 31, 33
GetCurrentRowColumnByName() on
connecting to Microsoft Access 17
aaDBCommand 41
connecting to Microsoft Excel 17
GetDataSet() on aaDBCommand 42
SetParam type methods 59
GetDiagnostics()
OleDb value for aaDBConnectionType
aaDBAccess objects 34
public enumeration 80
aaDBConnection 77
Oracle databases
GetID()
connecting to 17, 31, 33
aaDBCommand 42
SetParam type methods 50
aaDBTransaction 89
Oracle value for aaDBConnectionType
GetParameterByIndex() on public enumeration 80
aaDBCommand 43
Output parameters for SQL Server and
GetParameterByName() on Oracle 51
aaDBCommand 43
Output value for
GetRow() on aaDBCommand 44 aaDBParameterDirection public
getting rows, setting rows 81 enumeration 72
GetTransaction() on aaDBAccess 34
P
I processing 37
importing the SQLData Script Library processing multiple commands as a single
file 12 unit 85
Input value for aaDBParameterDirection public constructor for aaDBRow object 82
public enumeration 72 public enumerations
Input/Output value for aaDBCommandState 70
aaDBParameterDirection public
aaDBCommandType 71
enumeration 72
aaDBConnectionState 79
L aaDBConnectionType 80
aaDBParameterDirection 71
LastError property on
aaDBConnection 78 aaDBTransactionState 91

SQLData Script Library User’s Guide

 101

Q overview 19
Queued value process script code 22
process script configuration 20
aaDBCommandState public
enumeration 70 query script code 20
query script configuration 20
aaDBTransaction public
enumeration 91 description of sample scripts 18
diagram of relationships 14
R Microsoft Access connection string
example 17
RemoveCommand() on aaDBAccess
objects 35 Microsoft Excel connection string
example 17
RemoveTransaction() on aaDBAccess
objects 35 Oracle connection string example 17
ResetDiagnostics() 36 SQL Server connection string
example 16
ResetDiagnostics() on
aaDBConnection 77 synchronous script example
ReturnValue value for code 24
aaDBParameterDirection public configuration 23
enumeration 72 overview 23
reusable connection objects, creating 27 work flow 15
Row Count aaDBCommand object script library examples
property 70 overview 17
rows, getting or setting from memory SelectRow() on aaDBCommand 45
dataset 81 SelectTable() on aaDBCommand 46
SetBitParameterByName() on
S aaDBCommand 51
sample scripts SetCharParameterByName() on
asynchronous aaDBCommand 52
overview 19 SetCurrentRow() on aaDBCommand 46
process script code 22 SetCurrentRowByIndex() on
process script configuration 20 aaDBCommand 48
query script code 20 SetCurrentRowColumnByName() on
query script configuration 20 aaDBCommand 49
detailed description 18 SetDateTimeParameterByName() on
overview 17 aaDBCommand 54
synchronous SetDecimalParameterByName() on
aaDBCommand 53
code 24
SetDoubleParameterByName() on
configuration 23
aaDBCommand 55
overview 23
SetFloatParameterByName() on
SaveChangesAsync() on
aaDBCommand 56
aaDBCommand 45
SetIntParameterByName() on
SaveChangesSync() on
aaDBCommand 57
aaDBCommand 45
SetLongParameterByName() on
script examples
aaDBCommand 58
connecting to Microsoft Access data
SetParam type methods
source 17
OLEDB 59
connecting to Oracle data source 17
Oracle and SQL Server 50
connecting to SQL Server 16
SetParam type methods for OLEDB 58
script library
Shutdown() 36
architectural overview 13
SQL Server authentication mode 30
asynchronous script example

SQLData Script Library User’s Guide

102Index

SQL statements, processing 37 T

Sql value for aaDBConnectionType public tables, accessing 37
enumeration 80
technical support, contacting 10
SQLData Script Library
transaction object, creating 15, 73
accessing 12
functions 12 U
importing file 12
unique connection objects, creating 28
sqlStatement value for
aaDBCommandType public
enumeration 71 V
stored procedures 37 views, accessing 37
storedProcedure value for
aaDBCommandType public W
enumeration 71 Windows account authentication
synchronous script example mode 29
code 24 Windows integrated security
configuration 23 authentication mode 29
overview 23 work flow for scripting 15

SQLData Script Library User’s Guide