Connection pooling can improve performance of applications such as web servers that continually start short life phantom processes or QMClient sessions. Instead of terminating when the phantom completes its work or a QMClient connection is closed, the process enters an idle state waiting for a new connection to arrive, at which point it continues processing. This removes the need for start-up processing both in QM itself and, more significantly, in the application. For example, files opened in the server process do not need to be reopened and data in common blocks does not need to be reinitialised.
This feature is not currently available in the AIX (RS6000) version of QM. On this platform, the QMConnectPool() function will behave identically to QMConnect() and a pool name associated with a phantom process will be ignored.
A connection pool is defined by use of the POOL configuration parameter. This sets a case insensitive pool name of up to 15 characters and an associated pool size limit and timeout value.
This parameter may be repeated to define multiple pools.
The limit value sets the maximum number of idle processes that are allowed to be waiting in the pool. If the limit is reached, a process attempting to go into the idle state will be terminated.
The timeout value sets the period in seconds for which an idle process will wait before terminating. A value of zero implies no timeout. A timeout of a few seconds is recommended.
Using Connection Pooling with Phantom Processes
A phantom process can be started as a member of a connection pool by use of the POOL option to the PHANTOM command or the QMBasic PHANTOM statement. If a suitable idle phantom process exists in the pool, it will be woken, otherwise a new process is started. The NEW.PROCESS qualifier to the POOL option can be used to force creation of a new process.
When it completes its work, the phantom process can use the POOL.IDLE statement to join the pool of idle processes.
Using Connection Pooling with QMClient
QMConnectPool(host, port, username, password, account, poolname)
On first use, this function behaves exactly like QMConnect() except that, if the pool name is recognised by the server, the process started by this function becomes a member of that pool.
At the point when the client terminates the connection by using QMPoolIdle(), the server process will enter a waiting state and the client process connection to the server is closed. When a new QMClient connection arrives using QMConnectPool() for the same pool name, user name and account name, the waiting process resumes execution, processing the new connection. Note that the account name must match the account in which the idle process is currently operating which could be different from the account specified when the session started. If no suitable idle process is found, a new process is started.
If the pool size limit has been reached, QMPoolIdle() will terminate the server process in the same way as QMDisconnect(). This parameter value does not limit the number of active processes in the pool.
Because the server process will be picked up by a new client that has no knowledge of what has happened before, when a process goes into the idle state, files opened using QMOpen() are closed and objects instantiated with QMCreateObject() are destroyed.
From the client side, a connection pooling session looks identical to a non-pooled session. From the server side, the application must be written such that an executed series of commands or subroutines might not relate to the same client session. It may be necessary for the client to call some form of reset function prior to entering the idle state if there is session related data that must not be carried forward.
Although phantoms and QMClient sessions can exist in the same pool, only a process of the appropriate type will be woken from its idle state when new work arrives. It is recommended that different pool names are used for the two process types.
The SYSTEM(1060) function returns the pool name for a connection pooling process, a null string for other processes.