Connect-Star for .NET Framework
Overview
Connect★ for .NET Framework supports Connect★ functionality for Model 204. This includes all SQL and RCL statement syntax.
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.
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.
Platforms tested
The following Microsoft® Windows® platforms have been tested successfully for connectivity with Connect★ for .NET Framework:
Windows 7, Windows 8
Windows Server 2008, Windows Server 2012
These platforms are supported by Rocket Software.
Environment requirements
Before you install Connect★ for .NET Framework you must have the following installed in your working environment:
- Model 204 Version 7 Release 4.0 or greater with TCP/IP and SQL
- Microsoft .NET Framework 3.5
Microsoft Visual Studio Integration
Connect★ for .NET Framework supports integration of the Model 204 .NET Framework data provider with Microsoft® Visual Studio® 2005. Later versions are not yet supported.
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, see the Using Model204Client in Microsoft Visual Studio topic in the CCA.Data.chm help file that is installed with Model204Client.
Uninstalling a previous version of Connect★ for .NET Framework
To uninstall a previous version of Connect★ for .NET Framework:
Go to Control Panel > Add/Remove Programs, click on Connect★ Model 204 for .NET Framework, and remove 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.
- Navigate to the FTP server site: ftp.rocketsoftware.com
- Enter the userid and password provided by Rocket.
- Navigate to the M204 > version > ConnectStar folder (where version is 7.5, for example).
- Open the DotNet File folder.
- Choose the folder for the driver that you want: 32bit or 64bit.
- Download the files to your PC, in binary format.
- Run the .exe file to install the application.
Installation under Microsoft Windows 7
You can run the Model 204 .NET installation using either setup.dotnet.exe or setup_dotnet.msi:
- To run the Model 204 .NET installation using setup.dotnet.exe, just click on setup.dotnet.exe.
- To run the Model 204 .NET installation using setup_dotnet.msi:
- Right-click on setup_dotnet.msi in the installation directory and select Properties.
- Go to the Compatibility tab (see below) and check "Run this program in compatibility mode".
- Press apply.
- Click on setup_dotnet.msi to install.
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 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★ for .NET Framework features.
Using Connect★ for .NET Framework
Prerequisite
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 Programs.
- Click on the Connect Star for Model 204 program group.
- Then, click on .NET. > DatabaseConnectivity.
- 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 Windows
The driver places the Model204Client log file in the user's home directory.
Under Windows 7, the directory would be:
C\Users\user_name
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.6 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.6 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.