Connect* for .NET Framework
Connect★ for .NET Framework supports Connect★ functionality for Model 204. This includes all SQL and RCL statement syntax.
Connect★ for .NET Framework is a Microsoft Windows compatible driver.
See Model 204 documentation for related Model 204 documentation.
Connect★ for .NET Framework environment
.NET Framework conformance
Connect★ 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.
The following Microsoft® Windows® platforms have been tested successfully for connectivity with Connect★ 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.
Before you install Connect★ 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★ for .NET Framework supports integration of the Model 204 .NET Framework data provider with Microsoft® Visual Studio®.
Connect★ 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★ 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★ .NET Framework Data Provider, see the topic Using Model204Client in Microsoft Visual Studio.
== Uninstalling a previous version of Connect★ for .NET Framework== To uninstall a previous version of Connect★ for .NET Framework:
- Open the control panel (for example, by going to Start > Control Panel).
- Navigate to where you add and remove programs from Windows (for example, Add/Remove Programs or Programs and Features).
- Click on Connect★ Model 204 for .NET Framework, and uninstall it.
Connect★ for .NET Framework installation
Installing Connect★ for .NET Framework
- Ensure that you have fulfilled the preinstallation requirements as described in Preparing to install.
- With your Rocket M204 user ID and password handy, go to the Rocket M204 Customer Care page.
- Click the Download client (workstation) files link to go to the Client files for Rocket Software page.
- The Connect★ drivers are available in zip format. Click the Download ZIP file link for the Connect★ drivers.
- 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★.)
- 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).
- 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.
- Click Install to begin the installation.
- Click Finish to complete the installation.
Consult the .NET Framework online help for the specific connection parameters.
For a complete discussion of the connection parameters, see Connection parameters.
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★ for .NET Framework
Before executing an SQL statement, check with your Connect★ 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
- Navigate to Start > All Programs and open the Connect Star for Model 204 folder.
- Open the .NET* folder and click on Database Connector.
- 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:
Large object (BLOB and CLOB) data type support
Connect★ 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★ 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:
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
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.
Determines whether connection pooling is enabled for connections created with the same connection string.
True enables pooling; false disables it.
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.
Min Pool Size
Minimum number of server connections in a pool.
If the minimum is larger than the maximum, the maximum value is used.
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.
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.
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.
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.