Connect-Star for .NET Framework

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

• Connect★
• Connect★ for .NET Framework
• Connect★ for JDBC
• Connect★ for ODBC
• Connect★ installation requirements
• Connect★ to Model 204 connection
• Connect★ messages