Connections are the links between the client and a data source. Connections allow the user at a client to issue commands to be executed on the server, and provide a pathway for the server’s response to the client. A command sent to the server and the server’s response is considered one statement. Multiple statements can be executed using the same connection.

Connection limits

The SQLMaxConnections setting in the defaults file allows you to define the maximum number of connections your application can maintain simultaneously between a client and server. The connectivity package used (such as TCP/IP) determines the maximum number of connections allowed between a client and a server. If this setting isn’t used in the defaults file, the default value of 32 will be used. This is the maximum number of connections allowed by some TCP/IP packages.

Be sure to consult the documentation of the connectivity package to be used with your application. If the package allows fewer than 32 connections, be sure to set the SQLMaxConnections defaults file setting to the number of connections allowed by that package, or lower. The SQLMaxConnections setting should never exceed the number of connections allowed by that package.

If the maximum number of connections is reached before the application maximum is reached, the application may freeze or shut down. To avoid this, we recommend that you set the number of connections lower than the maximum number allowed by the connectivity package. If a user runs more than one application that uses connections to a server, the applications must share the limited number of connections offered by the connectivity package.

Applications you create will rarely require more than five simultaneous connections.

If a user reaches the maximum number of connections set for your application, a message will appear stating that the operation can’t be executed because the maximum number of connections has been reached. The user will be returned to the point where he or she initiated the operation, and will be able to try again, in case a connection has become available.

Connection pools

Establishing a connection between a client and server at runtime can be time-consuming. Dexterity allows you to design your application to keep open connections in reserve, thus limiting the amount of time spent establishing connections. These open but inactive connections are stored in a connection pool, where they can be accessed and used immediately.

The size of the connection pool is specified by the SQLMaxInactiveConnections defaults file setting. A connection pool can be created when an application is started, using the SQLNumInitialConnections and SQLMaxInactiveConnections defaults file settings. If you want the connection pool to contain three connections at startup, you should set both defaults file settings to 3.

If the SQLNumInitialConnections setting is greater than zero, the Dexterity Login window will be used to establish the connections to the data source, even if you have designed your own Login window. This is because your window is defined in your dictionary, and the connections are created before your dictionary is opened.

If you choose to use your own Login window, you must set the SQLNumInitialConnections setting to 0 (zero). However, if the SQLMaxInactiveConnections setting is greater than 0 (zero), the connection established for use by your Login window will be added to the connection pool when the login has been successfully completed.

The default setting for SQLNumInitialConnections is zero, and the maximum setting is 5. For SQLMaxInactiveConnections, the default setting is 3, and the maximum setting is 5. If the number of initial connections is less than the number of inactive connections, then any new connection that is established will be stored in the connection pool when it’s no longer needed.

When a connection is needed, one is taken from the connection pool and used. If no connections are available in the pool, a new connection will be established and used. As connections are no longer needed, they’re returned to the connection pool until the maximum number of inactive connections is reached. When the maximum number is reached, any connections that are no longer needed will be released.


Documentation Feedback