Connecting to the InterSystems Database
This chapter describes how to create a connection between your client application and an InterSystems server using an IRISConnection object.
Creating a Connection
Refer to “Connecting Your Application to InterSystems IRISOpens in a new tab” for a complete guide to creating a connection between your client application and the InterSystems server.
The code below establishes a connection to a namespace named USER. See “Connection Parameter Options” for a complete list of parameters that can be set when instantiating a connection object.
The following simple method could be called to start a connection:
public IRISConnection Conn;
private void CreateConnection(){
try {
Conn = new IRISConnection();
Conn.ConnectionString =
"Server=localhost; Port=51773; Namespace=USER;"
+ "Password=SYS; User ID=_SYSTEM;";
Conn.Open();
}
catch (Exception eConn){
MessageBox.Show("CreateConnection error: " + eConn.Message);
}
}
Once the object has been created, it can be shared among all the classes that need it. The connection object can be opened and closed as necessary. You can do this explicitly by using Conn.Open() and Conn.Close(). If you are using an ADO.NET Dataset, instances of DataAdapter will open and close the connection automatically, as needed.
Connection Pooling
Connection pooling is on by default. The following connection string parameters can be used to control various aspects of connection pooling:
-
Pooling — Defaults to true. Set Pooling to false to create a connection with no connection pooling.
-
Max Pool Size and Min Pool Size — Default values are 0 and 100. Set these parameters to specify the maximum and minimum (initial) size of the connection pool for this specific connection string.
-
Connection Reset and Connection Lifetime — Set Connection Reset to true to turn on the pooled connection reset mechanism. Connection Lifetime specifies the number of seconds to wait before resetting an idle pooled connection. The default value is 0.
For example, the following connect string sets the initial size of the connection pool to 2 and the maximum number of connections to 5, and activates connection reset with a maximum connection idle time of 3 seconds:
Conn.ConnectionString =
"Server = localhost;"
+ " Port = 51774;"
+ " Namespace = USER;"
+ " Password = SYS;"
+ " User ID = _SYSTEM;"
+ " Min Pool Size = 2;"
+ " Max Pool Size = 5;"
+ " Connection Reset = true;"
+ " Connection Lifetime = 3;";
See the “Quick Reference for the .NET Managed Provider” for more details on the various connection pooling methods and properties.
Server Configuration
Very little configuration is required to use a .NET client with an InterSystems server process. This section describes the server settings required for a connection, and some troubleshooting tips.
Every .NET client that wishes to connect to an InterSystems server needs the following information:
-
A URL that provides the server IP address, port number, and namespace.
-
A case-sensitive username and password.
Check the following points if you have any problems:
-
Make sure that the server process is installed and running.
-
Make sure that you know the IP address of the machine on which the server process is running.
-
Make sure that you know the TCP/IP port number on which the server is listening.
-
Make sure that you have a valid username and password to use to establish a connection. (You can manage usernames and passwords using the Management Portal: System Administration > Security > Users).
-
Make sure that your connection URL includes a valid namespace. This should be the namespace containing the classes and data your program uses.
