Connect-Star for .NET Framework: Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(22 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE: Connect<span class="superstar">&#9733;</span> for .NET Framework}}
{{DISPLAYTITLE: Connect-Star for .NET Framework}}
==Overview==
==Overview==


Connect<span class="superstar">&#9733;</span> for .NET Framework supports Connect<span class="superstar">&#9733;</span> functionality for Model 204. This includes all SQL and RCL statement syntax.
Connect-Star for .NET Framework supports Connect-Star functionality for Model 204. This includes all SQL and RCL statement syntax.


Connect<span class="superstar">&#9733;</span> for .NET Framework is a Microsoft Windows compatible driver.
Connect-Star for .NET Framework is a Microsoft Windows compatible driver.


See [[Model 204 documentation]] for related Model 204 documentation.
See [[Model 204 documentation]] for related Model 204 documentation.


==Connect<sup>&#9733;</sup> for .NET Framework environment==
==Connect-Star for .NET Framework environment==


===.NET Framework conformance===
===.NET Framework conformance===


Connect<span class="superstar">&#9733;</span> for .NET Framework is compliant with Microsoft<sup>&reg;</sup> .NET<sup>&reg;</sup> Framework 3.5 or higher.
Connect-Star for .NET Framework is compliant with Microsoft<sup>&reg;</sup> .NET<sup>&reg;</sup> Framework 3.5 or higher.


===Specifications and limitations===
===Specifications and limitations===


The Model204Client Help file is created during installation and can be found in the Connect Star for Model 204 program group under .NET.
The Help File, <var class="term">Model204Client Data Provider</var>, is created during installation and can be accessed from the Start menu with your Connect Star for Model 204 .NET application.


===Platforms tested===
===Platforms tested===


The following Microsoft<sup>&reg;</sup> Windows<sup>&reg;</sup> platforms have been tested successfully for connectivity with Connect<span class="superstar">&#9733;</span> for .NET Framework: <br />Windows 7, Windows 8.1 <br />Windows Server 2008, Windows Server 2012
The following Microsoft<sup>&reg;</sup> Windows<sup>&reg;</sup> platforms have been tested successfully for connectivity with Connect-Star for .NET Framework:  
<ul>
<li>Windows<sup>&reg;</sup> 7, Windows 8.1, or Windows 10</li>
<li>Windows Server<sup>&reg;</sup> 2008 or Windows Server 2012</li>
</ul>


These platforms are supported by Rocket Software.
These platforms are supported by Rocket Software.
Line 26: Line 30:
===Environment requirements===
===Environment requirements===


Before you install Connect<span class="superstar">&#9733;</span> for .NET Framework you must have the following installed in your working environment:
Before you install Connect-Star for .NET Framework you must have the following installed in your working environment:
<ul>
<ul>
<li>
<li>
Line 36: Line 40:
===Microsoft Visual Studio Integration===
===Microsoft Visual Studio Integration===


Connect<span class="superstar">&#9733;</span> for .NET Framework supports integration of the Model 204 .NET Framework data provider with Microsoft<sup>&reg;</sup> Visual Studio<sup>&reg;</sup>.
Connect-Star for .NET Framework supports integration of the Model 204 .NET Framework data provider with Microsoft<sup>&reg;</sup> Visual Studio<sup>&reg;</sup>.


Connect<span class="superstar">&#9733;</span> for .NET Framework installation registers Model204Client as a Data Designer Extensibility (DDEX) provider. This enables you to use Model204Client with Visual Studio wizard and visual designer data tools to build applications for Windows. Model 204 data objects appear as an object hierarchy in the Server Explorer window, and they can be dragged and dropped into various designer tools provided by the IDE.
Connect-Star for .NET Framework installation registers Model204Client as a Data Designer Extensibility (DDEX) provider. This enables you to use Model204Client with Visual Studio wizard and visual designer data tools to build applications for Windows. Model 204 data objects appear as an object hierarchy in the Server Explorer window, and they can be dragged and dropped into various designer tools provided by the IDE.


For documentation on using the data provider in Visual Studio, see the <var class="term">Using Model204Client in Microsoft Visual Studio</var> topic in the CCA.Data.chm help file that is installed with Model204Client.
For documentation on using the data provider in Visual Studio, open Connect-Star for .NET from the Start menu, and select the Help File. (This is the <var>CCA.Data.chm</var> help file that is installed with Model204Client.)
<div id="uninstall Connect* .NET Framework"></div>
In the chapter <var class="term">Using the Connect-Star .NET Framework Data Provider</var>, see the topic <var class="term">Using Model204Client in Microsoft Visual Studio</var>.


==Uninstalling a previous version of Connect<sup>&#9733;</sup> for .NET Framework==
==<b id="uninstall Connect* .NET Framework"></b>
<!--Note: div above -->
Uninstalling a previous version of Connect-Star for .NET Framework==
To uninstall a previous version of Connect<span class="superstar">&#9733;</span> for .NET Framework:
To uninstall a previous version of Connect-Star for .NET Framework:


Go to Control Panel > Add/Remove Programs, click on Connect<span class="superstar">&#9733;</span> Model 204 for .NET Framework, and remove it.
<ol>
<li>Open the control panel (for example, by going to Start > Control Panel). </li>
<li>Navigate to where you add and remove programs from Windows (for example, Add/Remove Programs or Programs and Features).</li>
<li>Click on Connect-Star Model 204 for .NET Framework, and uninstall it.</li>
</ol>


==Connect<sup>&#9733;</sup> for .NET Framework installation==
==Connect-Star for .NET Framework installation==


===Installing Connect<sup>&#9733;</sup> for .NET Framework===
===Installing Connect-Star for .NET Framework===
<ol>
<ol>
<li>
<li>
Ensure that you have fulfilled the preinstallation requirements as described in [[Connect* installation requirements#Preparing to install|Preparing to install]].</li>
Ensure that you have fulfilled the preinstallation requirements as described in [[Connect* installation requirements#Preparing to install|Preparing to install]].</li>
<li>
Navigate to the FTP server site:


ftp.rocketsoftware.com
<li>With your [[Rocket M204 user ID]] and password handy, go to the [https://model204.rocketsoftware.com Rocket M204 Customer Care page].</li>
</li>
 
<li>
<li>Click the <b>Download client (workstation) files</b> link to go to the [https://m204.rocketsoftware.com/maint/cllist Client files for Rocket Software page]. </li>
Enter the userid and password provided by Rocket.</li>
 
<li>
<li>The Connect-Star drivers are available in zip format. Click the <b>Download ZIP file</b> link for the Connect-Star drivers.</li>
Navigate to the M204  &gt; <var class="term">version</var> &gt; ConnectStar folder (where <var class="term">version</var> is 7.5, for example).</li>
 
<li>
<li>Click <b>Save as</b> to save the cstar.zip file in your preferred directory. (You will later be prompted for the directory where you want to actually install Connect-Star.)</li>
Open the DotNet File folder.</li>
 
<li>
<li>Expand the file in an unzip application, such as WinZip, and double-click the setup file appropriate for your operating system: setup_dotnet32.exe (32-bit) or setup_dotnet64.exe (64-bit). </li>
Choose the folder for the driver that you want: 32bit or 64bit.</li>
 
<li>
<li>The Connect Star Setup Wizard appears. Click <b>Next</b> and select an installation folder, or use the default folder (C:\Program Files\CCA\Connect Star for Model 204). Click <b>Next</b>.</li>
Download the files to your PC, in binary format.</li>
 
<li>
<li>Click <b>Install</b> to begin the installation.</li>  
Run the .exe file to install the application.</li>
</ol>


===Installation under Microsoft Windows 7 or Windows 8===
<li>Click <b>Finish</b> to complete the installation.</li>
You can run the Model 204 .NET installation using either setup.dotnet.exe or setup_dotnet.msi:
<ul>
<li>To run the Model 204 .NET installation using setup.dotnet.exe, just click on setup.dotnet.exe.</li>
<li>To run the Model 204 .NET installation using setup_dotnet.msi:</li>
<ol>
<li>Right-click on setup_dotnet.msi in the installation directory and select Properties.</li>
<li>Go to the Compatibility tab (see below) and check &quot;Run this program in compatibility mode&quot;.</li>
<li>Press apply.</li>
<li>Click on setup_dotnet.msi to install.</li>
</ol>
</ol>
</li>
</ul>
<p class="figure">[[File:CStar_5-1_setup_dotnet.jpg]] </p>


===Connection parameters===
===Connection parameters===
Line 97: Line 88:


===Documentation===
===Documentation===
The Help File, <var class="term">Model204Client Data Provider</var>, is created during installation.


The Model204Client Help file is created during installation and can be found in the Connect Star for Model 204 program group under .NET. The Help file provides complete documentation of the new Connect<span class="superstar">&#9733;</span> for .NET Framework features.
The readme file is displayed by default when installation is complete. For convenience, it contains links to the wiki as well as information on online help:
<ul>
<li>For help on classes and methods, access your Connect Star for Model 204 .NET application from the Start menu and select the Help File.</li>
<li>For information about creating a connection string, see the <var>CdmDbConnectionStringBuilder</var> class description in the Help File.</li>
</ul>


==Using Connect<sup>&#9733;</sup> for .NET Framework==
==Using Connect-Star for .NET Framework==


===Prerequisite===
===Prerequisite===


Before executing an SQL statement, check with your Connect<span class="superstar">&#9733;</span> administrator to make sure that either the demonstration database is installed and has been defined to the SQL catalog file, CCACAT, or you have other available tables defined in CCACAT. (See [[Connect* to Model 204 connection#SQL catalog population|SQL catalog population]].)
Before executing an SQL statement, check with your Connect-Star administrator to make sure that either the demonstration database is installed and has been defined to the SQL catalog file, CCACAT, or you have other available tables defined in CCACAT. (See [[Connect* to Model 204 connection#SQL catalog population|SQL catalog population]].)


===Verifying the .NET Framework connection===
===Verifying the .NET Framework connection===


Navigate to Programs.
<ol>
<ol>
<li>
<li>Navigate to Start > All Programs and open the Connect Star for Model 204 folder.</li>
Click on the Connect Star for Model 204 program group. </li>
<li>Open the .NET* folder and click on Database Connector. </li>
<li>
<li>Complete the Connection Information screen and click the Test Connection button.</li>
Then, click on .NET. &gt; DatabaseConnectivity. </li>
<li>
Complete the Connection Information screen and click the Test Connection button.</li>
</ol>
</ol>


Line 130: Line 122:
==Large object (BLOB and CLOB) data type support==
==Large object (BLOB and CLOB) data type support==


Connect<span class="superstar">&#9733;</span> for .NET Framework provides support for Model 204 BLOB and CLOB data types in SQL update and retrieval statements.
Connect-Star for .NET Framework provides support for Model 204 BLOB and CLOB data types in SQL update and retrieval statements.


Use these DataReader methods to retrieve data from BLOB columns:
Use these DataReader methods to retrieve data from BLOB columns:
Line 149: Line 141:
<ul>
<ul>
<li>
<li>
In Connect<span class="superstar">&#9733;</span> for .NET version 7.5 and earlier, connections are pooled by default.</li>
In Connect-Star for .NET version 7.5 and earlier, connections are pooled by default.</li>
<li>
<li>
In upcoming version 7.7 and later, pooling is turned off by default. (Disabling pooling alleviates Model 204 COMM errors on an RCL (IODEV 49) thread using a single threaded, non-pooling application.)</li>
In version 7.7 and later, pooling is turned off by default. (Disabling pooling alleviates Model 204 COMM errors on an RCL (IODEV 49) thread using a single threaded, non-pooling application.)</li>
</ul>
</ul>
<p>To enable pooling, set <code>pooling=true</code> in the connection string within the .NET or Web application. For example:</p>
<p>To enable pooling, set <code>pooling=true</code> in the connection string within the .NET or Web application. For example:</p>

Latest revision as of 17:51, 27 March 2024

Overview

Connect-Star for .NET Framework supports Connect-Star functionality for Model 204. This includes all SQL and RCL statement syntax.

Connect-Star for .NET Framework is a Microsoft Windows compatible driver.

See Model 204 documentation for related Model 204 documentation.

Connect-Star for .NET Framework environment

.NET Framework conformance

Connect-Star for .NET Framework is compliant with Microsoft® .NET® Framework 3.5 or higher.

Specifications and limitations

The Help File, Model204Client Data Provider, is created during installation and can be accessed from the Start menu with your Connect Star for Model 204 .NET application.

Platforms tested

The following Microsoft® Windows® platforms have been tested successfully for connectivity with Connect-Star for .NET Framework:

  • Windows® 7, Windows 8.1, or Windows 10
  • Windows Server® 2008 or Windows Server 2012

These platforms are supported by Rocket Software.

Environment requirements

Before you install Connect-Star for .NET Framework you must have the following installed in your working environment:

  • Model 204 Online, version 7.4 or higher with TCP/IP and SQL
  • Microsoft .NET Framework 3.5 or higher

Microsoft Visual Studio Integration

Connect-Star for .NET Framework supports integration of the Model 204 .NET Framework data provider with Microsoft® Visual Studio®.

Connect-Star for .NET Framework installation registers Model204Client as a Data Designer Extensibility (DDEX) provider. This enables you to use Model204Client with Visual Studio wizard and visual designer data tools to build applications for Windows. Model 204 data objects appear as an object hierarchy in the Server Explorer window, and they can be dragged and dropped into various designer tools provided by the IDE.

For documentation on using the data provider in Visual Studio, open Connect-Star for .NET from the Start menu, and select the Help File. (This is the CCA.Data.chm help file that is installed with Model204Client.) In the chapter Using the Connect-Star .NET Framework Data Provider, see the topic Using Model204Client in Microsoft Visual Studio.

== Uninstalling a previous version of Connect-Star for .NET Framework== To uninstall a previous version of Connect-Star for .NET Framework:

  1. Open the control panel (for example, by going to Start > Control Panel).
  2. Navigate to where you add and remove programs from Windows (for example, Add/Remove Programs or Programs and Features).
  3. Click on Connect-Star Model 204 for .NET Framework, and uninstall it.

Connect-Star for .NET Framework installation

Installing Connect-Star for .NET Framework

  1. Ensure that you have fulfilled the preinstallation requirements as described in Preparing to install.
  2. With your Rocket M204 user ID and password handy, go to the Rocket M204 Customer Care page.
  3. Click the Download client (workstation) files link to go to the Client files for Rocket Software page.
  4. The Connect-Star drivers are available in zip format. Click the Download ZIP file link for the Connect-Star drivers.
  5. Click Save as to save the cstar.zip file in your preferred directory. (You will later be prompted for the directory where you want to actually install Connect-Star.)
  6. Expand the file in an unzip application, such as WinZip, and double-click the setup file appropriate for your operating system: setup_dotnet32.exe (32-bit) or setup_dotnet64.exe (64-bit).
  7. The Connect Star Setup Wizard appears. Click Next and select an installation folder, or use the default folder (C:\Program Files\CCA\Connect Star for Model 204). Click Next.
  8. Click Install to begin the installation.
  9. Click Finish to complete the installation.

Connection parameters

Consult the .NET Framework online help for the specific connection parameters.

For a complete discussion of the connection parameters, see Connection parameters.

Documentation

The Help File, Model204Client Data Provider, is created during installation.

The readme file is displayed by default when installation is complete. For convenience, it contains links to the wiki as well as information on online help:

  • For help on classes and methods, access your Connect Star for Model 204 .NET application from the Start menu and select the Help File.
  • For information about creating a connection string, see the CdmDbConnectionStringBuilder class description in the Help File.

Using Connect-Star for .NET Framework

Prerequisite

Before executing an SQL statement, check with your Connect-Star administrator to make sure that either the demonstration database is installed and has been defined to the SQL catalog file, CCACAT, or you have other available tables defined in CCACAT. (See SQL catalog population.)

Verifying the .NET Framework connection

  1. Navigate to Start > All Programs and open the Connect Star for Model 204 folder.
  2. Open the .NET* folder and click on Database Connector.
  3. Complete the Connection Information screen and click the Test Connection button.

Debug trace for .NET Framework

To create a trace log file, use the loglevel parameter in the .NET connection string.

Log file location under Microsoft Windows

The driver places the Model204Client log file in the user's home directory:

C:\Users\user_name

Large object (BLOB and CLOB) data type support

Connect-Star for .NET Framework provides support for Model 204 BLOB and CLOB data types in SQL update and retrieval statements.

Use these DataReader methods to retrieve data from BLOB columns:

long GetBytes() object GetValue()

Use these DataReader methods to retrieve data from CLOB columns:

long GetBytes() long GetChars() string GetString() object GetValue()

In INSERT and UPDATE statements, use parameters for large object columns. First prepare the statement, then set the values of the parameters with the Parameter.Value property. The CCA.Data help file includes examples of storing and retrieving LOB columns.

Model204Client Connection Pooling

Connection pooling can reduce the number of times that you need to establish new connections to the server. When pooling is enabled and a new connection is opened, the pool manager obtains a server connection from an existing pool, if a suitable pool is available. The new connection must have exactly the same connection string as the pool.

  • In Connect-Star for .NET version 7.5 and earlier, connections are pooled by default.
  • In version 7.7 and later, pooling is turned off by default. (Disabling pooling alleviates Model 204 COMM errors on an RCL (IODEV 49) thread using a single threaded, non-pooling application.)

To enable pooling, set pooling=true in the connection string within the .NET or Web application. For example:

datasource=host:port;connectiontype=RCL;uid=myid;pwd=mypassword;pooling=true;loglevel=verbose

To disable pooling, set pooling=false in the connection string.

An application can have both pooled and non-pooled connections.

If no pool exists for a specified connection string, the pool manager creates a new pool and adds connection objects to the new pool until the minimum pool size requirement is satisfied.

New connections with the same connection string are obtained from the pool, adding connection objects as necessary up to the maximum pool size. When connections are closed or disposed, they are added back to the pool. A connection pool is accessible until it is explicitly cleared or the client process terminates.

The static method CdmDbConnection.ClearAllPools disposes all connection pools for the provider, and CdmDbConnection.ClearPool clears the connection pool associated with a specific connection string.

These methods sever idle connections on the server. Any connection in use at the time of the call is not closed until the application explicitly closes it. When that connection is subsequently closed, it is discarded instead of being returned to the pool.

Note: Transactions are specific to a connection and do not exist across connections.

Applications coded with connection pooling

An application should close or dispose connections when it finishes using them so that they are returned to the pool. Applications should also close active connections and clear all pools before terminating application processing. If this is not done, any connection open at termination will be severed by the server and receive the following error in the audit trail.

M204.2010: COMM ERROR STATUS, STATUSD = 53 1 M204.2012: REMOTE SQL SERVER COMMUNICATION ERROR RECEIVE WAIT STATUS

Connection string properties

The following connection string properties pertain to connection pooling.

Pooling

Determines whether connection pooling is enabled for connections created with the same connection string.

True enables pooling; false disables it.

Type: boolean

Default:
true (version 7.5 and earlier)
false (version 7.7 and later)

Max Pool Size

Maximum number of server connections in a pool.

If a new connection is opened and the maximum number of connections in the appropriate pool are already in use, the pool manager waits Waittime seconds for one to become available. If one does not become available within this time, it throws an exception.

Type: int

Default: 100

Min Pool Size

Minimum number of server connections in a pool.

If the minimum is larger than the maximum, the maximum value is used.

Type: int

Default: 0

Max Idle Time

Number of seconds a pooled connection can remain idle before the connection between the server and client is severed and the connection object is dropped from the pool.

When an application opens a new connection, the pool manager searches available connections in the associated pool and compares the time that data were last received from the server with the current time. It severs connections with a time span exceeding the value specified by Max Idle Time.

A value of zero indicates an infinite idle time.

Type: int

Default: 0

Waittime

The number of seconds the client will wait for a pooled connection to become available.

If no connection is available within this period of time, CdmDbConnection.Open will throw an exception.

Type: int

Default: 10

Properties summary

If Pooling is false, all other pooling parameters are ignored. If Pooling is true:

  • A new connection is taken from an existing pool, if the connection strings match exactly.
  • If the connection string does not match an existing pool, a new pool is created.
  • When a pooled connection is closed or disposed, it remains logged into Model 204 with the user ID and password specified in the connection string.
  • Model204Client severs a server connection when
    • it has been idle longer than MaxIdleTime seconds
    • CdmDbConnection.CloseAllPools or CdmDbConnection.ClosePool is executed for the pool.
  • Each connection is independent of all others. Transactions exist only within the context of a single connection.

MaxIdleTime property setting

The purpose of the MaxIdleTime property is to reduce the number of idle connections in a pool. This provides a way for applications with large numbers of idle connections to limit the overuse of resources.

In setting the MaxIdleTime value, you should take account of the value of the TIMEOUT parameter on the server process definition associated with the connection. For details, see DEFINE PROCESS command.

If the server does not receive input for more than TIMEOUT seconds, then it abnormally terminates and unbinds the session, making the connection unusable. MaxIdleTime on the client, therefore, should be less than the TIMEOUT value on the server. If not, an application might get a pooled connection that has been severed by the server. The request will throw an exception:

System.Exception: Fatal communications error: a Negative Response was received

Also, the server audit trail will show a timeout on that connection:

*** M204.1968: PROCESS TIMED OUT WAITING FOR COMPLETION OF READ() M204.2010: COMM ERROR STATUS, STATUSD = 53 2 *** M204.2010: COMM ERROR STATUS, STATUSD = 53 2 *** M204.2012: REMOTE SQL SERVER COMMUNICATION ERROR RECEIVE WAIT STATUS

This will not happen if TIMEOUT is unlimited (the default). If TIMEOUT is unlimited, however, the server does not reclaim unused connections.

Note: MaxIdleTime pertains only to pooled connections that have been closed or disposed on the client, and TIMEOUT pertains to all existing server connections. If a client connection has not been closed but sends no data to the server for a period of time longer than TIMEOUT, the next request executed on that connection will fail.

See also