.NET Connector. (MS Windows)

Transcription

1 tcaccess, Version 8.0 tcaccess.net documentation.net Connector (MS Windows) Last Review: 12/10/ /10/2010 Page 1

2 tcaccess.net documentation tcaccess, Version 8.0 Table of contents 1. General Requirements Installation Publishing of a.net application NET architecture Class "TcaConnection" Properties Methods Possible ConnectionString options: Examples VB.NET C# Class "TcaCommand" Properties Methods Examples VB.NET C# Class "TcaCommandBuilder" Properties Methods Examples VB.NET C# Class "TcaDataAdapter" Properties Methods Examples VB.NET C# Class "TcaDataReader" Properties Methods Examples VB.NET C# Class "TcaException" Properties Methods Examples VB.NET C# Class "TcaTransaction" Properties Methods Examples VB.NET C#...20 Page 2 12/10/2010

3 tcaccess, Version 8.0 tcaccess.net documentation 3. tcaccess.net and Prepared Statements General Usage of Prepared Statements Examples for Prepared Statements VB.NET C# tcaccess.net and Stored Procedures General Usage of Stored Procedures Examples for Stored Procedures VB.NET C# Index /10/2010 Page 3

4 tcaccess.net documentation tcaccess, Version General Using the tcaccess.net Connector enables developers to create.net applications that access mainframe data. tcaccess.net implements an ADO.NET interface and provides support for ADO.NET development tools. Applications using the tcaccess.net Connector can be developed in any language supported by the.net environment. 1.1 Requirements All functions provided by the tcaccess.net programming interface are part of file "Tca.Data.dll". This file must be added as link to the project (C#, Visual Basic, etc.). The required steps can be obtained from the documentation of the corresponding development tool..net Framework 2.0 is required. 1.2 Installation After the installation of tcaccess file "Tca.Data.dll" is part of the tcaccess installation directory. The.NET Connector can be added as link from this directory to the project. The Connector may also be included in the global Assembly Cache. To do this tool "Gacutil.exe" can be used (refer to.net Framework documentation). gacutil -i Tca.Data.dll It is also possible to use the extension provided by the.net Framework SDK for the Windows Shell (Assembly Cache Viewer (Shfusion.dll)). The shell extension allows to drag assemblies into the global Assembly Cache (mostly directory "C:\WINNT\Assembly"). Alternatively the configuration tool of the.net Framework (Mscorcfg.msc) can be used. It allows the display of the global Assembly Cache and to add new Assemblies to the cache. 1.3 Publishing of a.net application When publishing a.net application that uses the tcaccess.net Connector file "Tca.Data.dll" must be included in the installation file as application. The necessary steps can be found in the documentation of the corresponding development tool. On all machines where the application will be installed a path must exist that points to the tcaccess base directory. Page 4 12/10/2010

5 tcaccess, Version 8.0 tcaccess.net documentation 2..NET architecture The tcaccess.net Connector contains classes used to establish a connection to the database, executes queries and statements and to evaluate result sets. The following are the most important classes of the tcaccess.net Connectors: TcaConnection: Represents a connection to the tcaccess Host. TcaCommand: Represents a SQL-statement that should be executed at the tcaccess Host. TcaCommandBuilder: Automatically creates statements that should be used for a table to apply changes to a data record (dataset) for the assigned tcaccess host database. TcaDataAdapter: Represent SQL-statements and a database connection that should be used to fill a database object and to modify a tcaccess database. TcaDataReader: Provides the methods used to retrieve the "forward only" data records of a tcaccess database. TcaException: The exception will be used if tcaccess returns an error. TcaTransaction: Represents a SQL transaction that should be executed against a tcaccess database. All of these classes are explained in detail in the following chapters. The chapters provide an overview of the most important tcaccess.net Connector classes and are not meant to be a syntax reference. 2.1 Class "TcaConnection" A TcaConnection object represents a connection to a tcaccess data source. All properties are initialized during the creation of the TcaConnection instance.. When a TcaConnection becomes invalid it will not be closed. It must be explicitly closed using method "Close" Properties The following properties are available: Name ConnectionString ConnectionTimeout Database State Description Specifies or retrieves the connection string (refer to "Possible ConnectionString options"). Specifies or retrieves the timeout value used to establish a connection. If the timeout value is reached the attempt ends and an error is generated. Retrieves the name of the current database or the one that should be used after a connection has been established. If the database name has been specified, the creator (schema) name can be omitted in the SQL statement. Example: If the database name has been set to "DEMO" instead of "select * from DEMO.TEST" only "select * from TEST" can be used. Provides the current state of the connection Methods The following methods are available: Name BeginTransaction ChangeDatabase Close CreateCommand Open Description Starts a database transaction. Changes the current database object for an open TcaConnection-object. (refer to property "Database") Closes the connection with a database. Creates a Command-object that is assigned to the connection. Opens a database connection. The properties specified for the ConnectionString will be used. 12/10/2010 Page 5

6 tcaccess.net documentation tcaccess, Version Possible ConnectionString options: Option Description Default Config Name of the tcaccess configuration UID tcaccess user name. If this option is not defined the user name specified in the connection will be used. PWD tcaccess user password. If this option is not defined the password specified in the connection will be used. Trace "Yes" creates an access log in a text file. No Type This parameter specifies the type of the ODBC access for this data TCA/SQLX source. The following entries are allowed: TCA/SQLX tcaccess SQL-Engine SQL/DS SQL/DS DB2 DB/2 Parameter The data source parameter are explained in manual "tcaccess 8.0 Windows Client". ShowStat "Yes" displays a status window that contains transfer information. No Transactions This option is available for DB2, SQL/DS and the SQL-Engine. No Transactions are only possible for SQL-Engine tables if the underlying data source also supports transactions. Examples are DL/I databases and VSAM-files controlled by CICS Journalling/Recovery. Neither PS/PDS-files, SAM-files or VSAM Batch files support logical transactions. If the option has been defined it is the responsibility of the calling Windows application to correctly perform transaction processing. SendStatistics FixedFieldSize UsePreparedCommands OptimisticReadAhead LogonAsSqlId Pooling ConnectionLifetime If the option is not active no transaction support is available. However it is still possible to use the standard ODBC commands (i.e. a "Pass-Through Query in Microsoft Access): "NOCOMMIT", "COMMIT", "ROLLBACK" "Yes" will send statistical information about the transfer to the host, similar to the tcaccess Front end program. If this option is specified trailing blanks for character fields are not truncated. Using this option commands are being prepared on the host and are executed as "Prepared Command". This option specifies whether the Optimistic Read Ahead function should be used for the data source. This option specifies whether the the data source should use the current user name from the session sign-on as default SQLID. After method "Close" for the Connection-object has been used the connection to the host should not be closed but rather becomes part of a connection pool. If a new connection is established using the same ConnectionString the connection can be reused. Defines the maximum "Age" of a connection in seconds. If a connection reaches this age it is no longer included in the pool but closed. No No No No No No Examples The following example creates a TcaConnection- and a TcaCommand-object. The TcaConnection will be opened and used as connection for TcaCommand. Then, the ExecuteNonQuery will be called and the connection will be closed VB.NET The example shows how TcaConnection is used withvb.net. Page 6 12/10/2010

7 tcaccess, Version 8.0 tcaccess.net documentation Public Sub InsertRow() Dim connstr As String connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;" Dim conn As New TcaConnection(connStr) Dim cmd As New TcaCommand("INSERT INTO DEMO.TEST (100, NAME )") cmd.connection = conn conn.open() cmd.executenonquery() conn.close() End Sub C# The example shows how TcaConnection is used with C#. public void InsertRow() { string connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;"; TcaConnection conn = new TcaConnection(connStr); TcaCommand cmd = new TcaCommand("INSERT INTO DEMO.TEST (100, NAME )"); cmd.connection = conn; conn.open(); cmd.executenonquery(); conn.close(); } 2.2 Class "TcaCommand" The TcaCommand object represents a SQL-statement that is executed using a tcaccess data source Properties The following properties are available: 12/10/2010 Page 7

8 tcaccess.net documentation tcaccess, Version 8.0 Name CommandText CommandTimeout CommandType Connection Parameters Transaction UpdatedRowSource Description Specifies or retrieves the command text for the data source. Specifies or retrieves the timeout value that should be used for the command execution before an error is generated. Specifies how the CommandText-property should be interpreted. Specifies or retrieves the TcaConnection that should be used for this instance of TcaCommand. Retrieves the TcaDataParameterCollection. Specifies or retrieves the transaction used for the command object. Specifies or retrieves how the results of commands for DataRow should be applied if they are used by the update method of TcaDataAdapter. Page 8 12/10/2010

9 tcaccess, Version 8.0 tcaccess.net documentation Methods The following methods are available: Name Cancel CreateParameter ExecuteNonQuery ExecuteReader ExecuteScalar Prepare Description Attempts to cancel the execution of a TcaCommand. This operation is not supported. Creates a new instance of a TcaDataParameter-object. Executes a SQL statement for the Connection-object and returns the number of affected rows. Executes CommandText and creates a TcaDataReader. Executes the query and returns the first column of the first row of the result set. Additional columns or rows are ignored. Creates a prepared command version for the data source Examples The following example creates a TcaConnection- and a TcaCommand-object. The TcaConnection will be opened and used as connection for TcaCommand. Then, the ExecuteNonQuery will be called and the connection will be closed VB.NET The example shows the usage of TcaCommand with VB.NET. Public Sub InsertRow() Dim connstr As String connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;" Dim conn As New TcaConnection(connStr) Dim cmd As New TcaCommand("INSERT INTO DEMO.TEST (100, NAME )") cmd.connection = conn conn.open() cmd.executenonquery() conn.close() End Sub C# The example shows the usage of TcaCommand with C#. 12/10/2010 Page 9

10 tcaccess.net documentation tcaccess, Version 8.0 public void InsertRow() { string connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;"; TcaConnection conn = new TcaConnection(connStr); TcaCommand cmd = new TcaCommand("INSERT INTO DEMO.TEST (100, NAME )"); cmd.connection = conn; conn.open(); cmd.executenonquery(); conn.close(); } 2.3 Class "TcaCommandBuilder" A TcaDataAdapter object automatically creates the required SQL statements to modify a record in a tcaccess host database. Also a TcaCommandBuilder object can be created to automatically generate SQL statements for a table. Property "SelectCommand" of the TcaDataAdapter object must be specified. If this is the case all statements that have not been specified will be created by TcaCommandBuilder. The TcaCommandBuilder object registers itself as listener for "OnRowUpdating"-events when property "dataadapter" has been specified. Only one TcaDataAdapter- and one TcaCommandBuilder-object can be linked at a time. TcaCommandBuilder must execute SelectCommand to get the required meta data to create INSERT, UPDATE and DELETE commands. This requires a new read of the data source that may impact performance. The best performance can be achieved by directly specifying the commands and not to use TcaCommandBuilder. SelectCommand must at least return a primary key or a unique column otherwise exception InvalidOperation-will be created and no commands will be generated. If an assignment exists to DataAdapter TcaCommandBuilder automatically generates properties "InsertCommand", "UpdateCommand" and "DeleteCommand" for the TcaDataAdapter if these are NULLreferences. If a command already exists for a property this command will be used. Database views that consist of joins between 2 or more databases are not being treated as a single table. In this case TcaCommandBuilder cannot be used for the automatic command generation. The required command must be explicitly specified. Page 10 12/10/2010

11 tcaccess, Version 8.0 tcaccess.net documentation Properties The following properties are available: Name DataAdapter QuotePrefix QuoteSuffix Description Specifies or retrieves a TcaDataAdapter object for which transact SQL statements will be automatically generated. Specifies or retrieves the quote prefix that should be used for the specification of database objects (i.e tables or columns) that may contains spaces or reserved tokens. The default is a single quote ('). Specifies or retrieves the quote suffix that should be used for the specification of database objects (i.e tables or columns) that may contains spaces or reserved tokens. The default is a single quote (') Methods The following methods are available: Name DeriveParameters GetDeleteCommand GetInsertCommand GetUpdateCommand RefreshSchema Description Retrieves the parameter information of the procedure stored in TcaCommand and pads the parameter listing of the specified TcaCommand object. (This is a static method). Retrieves the automatically generated TcaCommand object that is required for database DELETEs. Retrieves the automatically generated TcaCommand object that is required for database INSERTs. Retrieves the automatically generated TcaCommand object that is required for database UPDATEs. Deletes the commands assigned to this TcaCommandBuilder Examples The following example creates a TcaConnection- and a TcaDataAdapter-object. A SelectCommand is assigned to TcaDataAdapter. The created TcaCommandBuilder object will be assigned to TcaDataAdapter. The connection is opened and a DataSet is created. Modifications to data in DataSet is represented by an update command for the database. The corresponding Delete-, Insert- or Update-statement has been created by TcaCommadBuilder. Then the connection will be closed VB.NET The example demonstrates the use of TcaCommandBuilder with VB.NET. 12/10/2010 Page 11

12 tcaccess.net documentation tcaccess, Version 8.0 Public Sub SelectRows() Dim connstr As String connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;" Dim conn As New TcaConnection(connStr) Dim da As TcaDataAdapter = New TcaDataAdapter() da.selectcommand = New TcaCommand("select * from DEMO.TEST", conn) Dim cb As TcaCommandBuilder = New TcaCommandBuilder(da) conn.open() Dim ds As DataSet = New DataSet da.fill(ds) code to modify data in DataSet without the TcaCommandBuilder this line would fail da.update(ds) conn.close() End Sub C# The example demonstrates the use of TcaCommandBuilder with C#. Page 12 12/10/2010

13 tcaccess, Version 8.0 tcaccess.net documentation public void SelectRows() { string connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;"; TcaConnection conn = new TcaConnection(connStr); TcaDataAdapter da = new TcaDataAdapter(); da.selectcommand = new TcaCommand("select * from DEMO.TEST", conn); TcaCommandBuilder cb = new TcaCommandBuilder(da); conn.open(); DataSet ds = New DataSet(); da.fill(ds); // code to modify data in DataSet // without the TcaCommandBuilder this line would fail da.update(ds); } conn.close(); 2.4 Class "TcaDataAdapter" A TcaDataAdapter object acts as a link between a DataSet and a tcaccess database for the retrieval and storing of data. TcaDataAdapter-object provides method "Fill" to adjust the data in DataSet with the data in the data source. Method "Update" adjust the data of the data source with the data in DataSet by using the corresponding SQL statements for the data source. 12/10/2010 Page 13

14 tcaccess.net documentation tcaccess, Version Properties The following properties are available: Name DeleteCommand InsertCommand SelectCommand UpdateCommand Description Specifies or retrieves a command to DELETE data records. Specifies or retrieves a command to INSERT data records. Specifies or retrieves a command to SELECT data records. Specifies or retrieves a command to UPDATE data records Methods The following methods are available: Name Fill Update Description Inserts into a DataSet or table. Retrieves the corresponding INSERT., UPDATE- or DELETE staement for every affected row Examples The following example creates a TcaConnection- and a TcaDataAdapter-object. A SelectCommand is assigned to TcaDataAdapter. The connection will be opened and a supplied DataSet will be filled. After the process is completed the connection will be closed VB.NET The example shows the processing of TcaDataAdapter with VB.NET. Public Sub SelectRows(ds As DataSet) Dim connstr As String connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;" Dim conn As New TcaConnection(connStr) Dim da As TcaDataAdapter = New TcaDataAdapter() da.selectcommand = New TcaCommand("select * from DEMO.TEST", conn) conn.open() da.fill(ds) conn.close() End Sub C# The example shows the processing of TcaDataAdapter with C#. Page 14 12/10/2010

15 tcaccess, Version 8.0 tcaccess.net documentation public void SelectRows(DataSet ds) { string connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;"; TcaConnection conn = new TcaConnection(connStr); TcaDataAdapter da = new TcaDataAdapter(); da.selectcommand = new TcaCommand("select * from DEMO.TEST", conn); conn.open(); da.fill(ds); conn.close(); } 2.5 Class "TcaDataReader" A TcaDataReader object provides the methods to retrieve the "forward only" data records of a tcaccess database. To create a TcaDataReader object method "ExecuteReader" of a TcaCommand object must be called. It is not possible to directly call a constructor. As long as a TcaDataReader object is in use the corresponding TcaConnection will be busy to retrieve the data for TcaDataReader. Therefore no other operations except close - can be executed on TcaConnection. This is true as long a method "CLOSE" has not been called for the TcaDataReader object. "IsClosed" and "RecordsAffected" are the only properties that can be called after TcaDataReader has been closed. Although "RecordsAffected" can be called at any time during the existence of the TcaDataReader object, method "CLOSE" should always be called before a value for "RecordsAffected" is returned to make sure that the correct value is available Properties The following properties are available Name Depth FieldCount HasRows IsClosed Item RecordsAffected Description Gets a value that indicates the depth of the current row. The tcaccess.net Connector always returns 0. Gets the number of columns of the current row Gets a value that indicates whether TcaDataReader has one or more rows. Gets a boolean value that indicates whether the TcaDataReader instance has been closed. Gets the column value in the system format. Gets the number of rows affected by a transact-sql-statements. 12/10/2010 Page 15

16 tcaccess.net documentation tcaccess, Version Methods The following methods are available: Name Close GetBoolean GetByte GetBytes GetChar GetChars GetDataTypeName GetDateTime GetDecimal GetDouble GetFieldType GetFloat GetGUID GetInt16 GetInt32 GetInt64 GetName GetOrdinal GetSchemaTable GetString GetValue GetValues IsDBNull NextResult Read Description Closes the TcaDataReader object. Gets the Boolean value of the specified column. Gets the value of the specified column as a byte. Reads a stream of bytes from the specified column offset into the buffer an array starting at the given buffer offset. Gets the single character value of the specified column. Reads a stream of characters from the specified column offset into the buffer as an array starting at the given buffer offset. Gets a string representing the data type of the specified column Gets the value of the specified column as a DateTime object. Gets the value of the specified column as a Decimal object. Gets the value of the specified column as a double-precision floating point number. Gets the Type that is the data type of the object returned by GetValue. Gets the value of the specified column as a single-precision floating point number. Gets the value of the specified column as a globally unique identifier (GUID). Gets the value of the specified column as a 16-bit signed integer. Gets the value of the specified column as a 32-bit signed integer. Gets the value of the specified column as a 64-bit signed integer. Gets the name of the specified column. Gets the column ordinal, given the name of the column. Returns a DataTable that describes the column metadata of the TcaDataReader.. Gets the value of the specified column as a string. Gets the value of the specified column in its native format. Gets all attribute columns in the collection for the current row. Gets a value that indicates whether the column contains non-existent or missing values. Advances the data reader to the next result, when reading the results of batch Transact-SQL statements.. Advances the TcaDataReader to the next record Examples The following example creates a TcaConnection- and a TcaDataAdapter-object. A SelectCommand is assigned to TcaDataAdapter. The connection will be opened and a supplied DataSet will be filled. After the process is completed the connection will be closed VB.NET The example shows the usage of TcaDataReader with VB.NET. Page 16 12/10/2010

17 tcaccess, Version 8.0 tcaccess.net documentation Public Sub ReadData() Dim connstr As String connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;" Dim conn As New TcaConnection(connStr) Dim cmd As New TcaCommand("select * from DEMO.TEST", conn) conn.open() Dim rdr As TcaDataReader rdr = cmd.executereader() while rdr.read() Console.WriteLine(rdr.GetInt32(0) & ", " & rdr.getstring(1) ) End While rdr.close() conn.close() End Sub C# The example shows the usage of TcaDataReader with C#. public void ReadData () { string connstr = " UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;"; TcaConnection conn = new TcaConnection(connStr); TcaCommand cmd = new TcaCommand("select * from DEMO.TEST", conn); conn.open(); TcaDataReader rdr = cmd.executereader(); while (rdr.read()) Console.WriteLine(rdr.GetInt32(0) + ", " + rdr.getstring(1) ); rdr.close(); conn.close(); } 2.6 Class "TcaException" A TcaException object is created whenever tcaccess.net detects an error. 12/10/2010 Page 17

18 tcaccess.net documentation tcaccess, Version Properties The following properties are available: Name Error Message Number Description Returns a TcaError object Returns an error message for the current exception. Returns an error number that identifies the error Methods TcaException has no methods Examples The following example analyzes a TcaException object and displays a summary upon console VB.NET The example sghows the usage of TcaException with VB.NET. Public Sub EvaluateTcaException(ex As TcaException) Console.WriteLine("Exception caught:") Console.WriteLine(" Number: " + ex.number) Console.WriteLine(" Message: " + ex.message) If Not ex.error Is Nothing Then Dim error As TcaError error = ex.error; Dim szmsg As String szmsg = String.Format("[{0}][{1:D}] : {2}", error.level, error.code, error.message); Console.WriteLine(" SQL Internal: " + szmsg) End If End Sub C# The example sghows the usage of TcaException with C#. Page 18 12/10/2010

19 tcaccess, Version 8.0 tcaccess.net documentation public void EvaluateTcaException(TcaException ex) { Console.WriteLine("Exception caught:"); Console.WriteLine(" Number: " + ex.number); Console.WriteLine(" Message: " + ex.message); if (ex.error!= null) { TcaError error = ex.error; String szmsg = String.Format("[{0}][{1:D}] : {2}", error.level, error.code, error.message); } } Console.WriteLine(" SQL Internal: " + szmsg); 12/10/2010 Page 19

20 tcaccess.net documentation tcaccess, Version Class "TcaTransaction" A TcaTransaction object represents a SQL transaction that should be executed for the tcaccess database Properties The following properties are available: Name Connection IsolationLevel Description Specifies the Connection object that is assigned to the transaction. Specifies the IsolationLevel-enumeration for this transaction Methods The following methods are available: Name Commit Rollback Description Performs a Commit for the database transaction. Performs a rollback for a not yet completed transaction Examples The following example creates a TcaConnection- and a TcaDataAdapter-object. The TcaCommand executes an INSERT statement that is "rollback"ed. The connection is closed VB.NET The example shows the usage of TcaTransaction with VB.NET. Public Sub InsertRow() Dim connstr As String connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;" Dim conn As New TcaConnection(connStr) Dim transaction As TcaTransaction = conn.begintransaction() Dim cmd As New TcaCommand("insert into DEMO.TEST values (200, NewName )", conn) conn.open() cmd.executenonquery() transaction.rollback() conn.close() End Sub C# The example shows the usage of TcaTransaction with C#. Page 20 12/10/2010

21 tcaccess, Version 8.0 tcaccess.net documentation public void InsertRow() { string connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;"; TcaConnection conn = new TcaConnection(connStr); TcaTransaction transaction = conn.begintransaction(); TcaCommand cmd = new TcaCommand(("insert into DEMO.TEST values (200, NewName )", conn)); } conn.open(); cmd.executenonquery(); transaction.rollback(); conn.close(); 12/10/2010 Page 21

22 tcaccess.net documentation tcaccess, Version tcaccess.net and Prepared Statements 3.1 General Using the tcaccess.net Connector it is possible to use Prepared Statements. The usage of Prepared Statements can lead to better performance especially for queries that are executed multiple times, hence the query must only be analyzed once. Also the network usage can be reduced, because only parameter must be sent instead of the full query. 3.2 Usage of Prepared Statements To use a Prepared Statement a TcaCommand-object must be created and the query that should be executed must become the "CommandText"- property. Next method "Prepare" of the TcaCommand-object should be called and the parameter for the dynamic elements of the query can be added. After the query and parameter have been built the statement can be executed using methods "ExecuteNonQuery", "ExecuteReader" or "ExecuteScalar". For every additional execution only the parameter values must be changed and the execute method must be called again. It is not necessary to set the "CommandText"- property again and the parameter must not be newly defined. 3.3 Examples for Prepared Statements The following example shows a simple use of Prepared Statements. The ConnectionString used to establish the connection must have option "UsePreparedCommands" set to "Yes". The query to be prepared contains the column names as parameter where the name is prefixed by (? ). Using "Prepare" prepares the query. The parameter must be defined according to the database structure. Finally the parameter values are created within a loop and the query is executed. Page 22 12/10/2010

23 tcaccess, Version 8.0 tcaccess.net documentation VB.NET Public Sub InsertRows() Dim connstr As String connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;" connstr += "UsePreparedCommands=Yes;" Dim conn As New TcaConnection(connStr) conn.open() Dim cmd As New TcaCommand("insert into DEMO.TEST values (?id,?name)", conn) cmd.prepare() cmd.parameters.add("id", TcaDbType.Int32, 4) cmd.parameters.add("name", TcaDbType.String, 40) Dim i As Int32 for i = 1 To Next cmd.parameters("id").value = i cmd.parameters.("name").value = String.Format("Name {0}", i); cmd.executenonquery() conn.close() End Sub 12/10/2010 Page 23

24 tcaccess.net documentation tcaccess, Version C# public void InsertRows() { string connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;"; connstr += "UsePreparedCommands=Yes;"; TcaConnection conn = New TcaConnection(connStr); conn.open(); TcaCommand cmd = New TcaCommand("insert into DEMO.TEST values (?id,?name)", conn); cmd.prepare(); cmd.parameters.add("id", TcaDbType.Int32, sizeof(int32)); cmd.parameters.add("name", TcaDbType.String, 40); Int32 i; for (i = 1 ; i <= 100 ; i++) {..} } cmd.parameters("id").value = i; cmd.parameters.("name").value = String.Format("Name {0}", i); cmd.executenonquery(); conn.close(); Page 24 12/10/2010

25 tcaccess, Version 8.0 tcaccess.net documentation 4. tcaccess.net and Stored Procedures 4.1 General A Stored Procedure is a logical unit of processing steps stored in a database. Clients must not perform the individual steps but can rather execute the Stored Procedure. tcaccess.net supports the execution of Stored Procedures using the TcaCommand objects. Data can be passed to the Stored Procedure using the the collection obtained with TcaCommand. Parameter (In-parameter) and results from the Stored Procedure can be retrieved (Out-Parameter). 4.2 Usage of Stored Procedures To use a Stored Procedure a TcaCommand-object must be created and the name of the Stored Procedure that should be executed must be specified as "CommandText"- property. Property "CommandType" must be set to "CommandType.StoredProcedure". Next for each parameter of the Stored Procedure a Tcacommand parameter must be created. In-parameter are defined using the parameter name and a value. Out-parameter must be defined using the parameter name and the expected data type. All parameter have the parameter direction in common (In or Out). After all the parameter have been specified the Stored Procedure can be executed using method "ExecuteNonQuery". 4.3 Examples for Stored Procedures The following example shows a simple use of Stored Procedures. The Stored Procedure has one input parameter ("SWITCH") and two output parameter ("DATE" and "TIME"). Depending upon the input parameter the output parameter are returned by the Stored procedure. Properties "CommandText" and "CommandType" must be set for the created TcaCommand-object. Next the parameter must be defined. Only the In-parameter contains a value. After the execution of the Stored Procedure the values of the out-parameter can be retrieved with method "ExecuteNonQuery". Note: The parameter definition can also be automated. To do this method "DeriveParameters" of class "TcaCommandBuilder" must be called. The method has the TcaCommand object specified as parameter and only the value of the in-parameter must be set. TcaCommandBuilder.DeriveParameters(cmd) cmd.parameters("switch").value = Int16.Parse(textBox1.Text) To determine the parameter information additional database accesses are necessary that may influence the execution performance. If the parameter information are known they should be explicitly defined to gain a far better performance. 12/10/2010 Page 25

26 tcaccess.net documentation tcaccess, Version VB.NET Public Sub CallProcedure() Dim connstr As String connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;" Dim conn As New TcaConnection(connStr) conn.open() Dim cmd As New TcaCommand("DEMO.TCATIMEQ", conn) cmd.commandtype = CommandType.StoredProcedure Dim parameter As TcaParameter parameter = cmd.parameters.add("?switch", TcaDbType.Int16) parameter.value = Int16.Parse(textBox1.Text) parameter = cmd.parameters.add("?date", TcaDbType.Date, 10) parameter.direction = ParameterDirection.Output parameter = cmd.parameters.add("?time", TcaDbType.Time, 8) parameter.direction = ParameterDirection.Output cmd.executenonquery() String szresult = String.Format("In SWITCH: {0}", textbox1.text) szresult += Environment.NewLine szresult += String.Format("Out DATE: {0}", cmd.parameters["?date"].value) szresult += Environment.NewLine szresult += String.Format("Out TIME: {0}", cmd.parameters["?time"].value) textbox2.text = szresult conn.close() End Sub Page 26 12/10/2010

27 tcaccess, Version 8.0 tcaccess.net documentation C# public void CallProcedure() { string connstr = "UID=MyUid;PWD=MyPwd;Type=TCA/SQLX;Config=ZVSE;"; TcaConnection conn = New TcaConnection(connStr); conn.open(); TcaCommand cmd = New TcaCommand("DEMO.TCATIMEQ ", conn); cmd.commandtype = CommandType.StoredProcedure; TcaParameter parameter = cmd.parameters.add("?switch", TcaDbType.Int16); parameter.value = Int16.Parse(textBox1.Text); parameter = cmd.parameters.add("?date", TcaDbType.Date, 10); parameter.direction = ParameterDirection.Output; parameter = cmd.parameters.add("?time", TcaDbType.Time, 8); parameter.direction = ParameterDirection.Output; cmd.executenonquery(); String szresult = String.Format("In SWITCH: {0}\r\n", textbox1.text); szresult += String.Format("Out DATE: {0}\r\n", cmd.parameters["?date"].value); szresult += String.Format("Out TIME: {0}\r\n", cmd.parameters["?time"].value); textbox2.text = szresult; conn.close(); } 12/10/2010 Page 27

28 tcaccess.net documentation tcaccess, Version Index P Procedures...25 S Statements...22 Page 28 12/10/2010