Timeout configuration is an important (yet often times overlooked) step in the deployment of an application that uses CA IDMS Server. Timeouts apply to both the ODBC and JDBC Drivers within CA IDMS Server, and are important for 2 reasons:
- They limit the time a front-end client application will wait for a response from CA IDMS (in the event of a back-end failed/stalled task, communications error, etc), thereby eliminating prolonged hangs.
- They permit CA IDMS to clean up resources on the backend CV (in the event of front-end PC failure, communications error, etc), thereby avoiding "No PTE Available" situations.
There are several components in a typical Client/Server Application that require timeout configuration. In this article we'll outline each of those components, provide some general recommendations on appropriate timeout values, talk about "Connection Pooling", and look at the interactions between these software components.
CCI is the communications vehicle that provides connectivity to the mainframe platform for all ODBC-based connections, as well as for JDBC type-2 connections. The PC portion of CCI has 3 timeout variables that can be configured via the Windows-based CAICCI-PC properties sheet. They are:
- Reply Wait - Represents the number of seconds that CCI/PC will wait for a response from CA IDMS. The default value is '-1' (indefinite).
- Ready to Receive - Represents the number of seconds that CAICCI/PC will wait for the receipt of the 2 nd (and successive) packet(s) within a TCP/IP packet stream. The default value is '-1' (indefinite wait).
- Ready to Send - Represents the number of seconds that CAICCI/PC will wait to be able to send data over a TCP/IP connection. The default value is 60 seconds.
The "Reply Wait" variable is by far the most important of the 3 timeouts listed above. This variable is reset for every communications request (of which there can be several for each SQL request). If a response to a request is not received (from the CA IDMS CV) within this interval, then an appropriate error will be generated and handed back to the CA IDMS ODBC or JDBC Driver. A "Reply Wait" interval of 30 seconds is usually sufficient for most Web-based applications.
Ad-hoc user queries will likely require a greater amount of time. This is especially true for long-running queries that read large volumes of data before returning any rows into the result-set (which can occur in queries using the ORDER BY or GROUP BY clause).
Both the "Ready to Receive" and the "Ready to Send" variables should also be set to 30 seconds for typical Web applications.
Data Source Definition:
The "Reply Wait" variable (discussed above) can also be implemented at the Data Source level, using the "Server" tab within the CA IDMS ODBC Administrator. This allows you to configure your wait specific to the needs of the application using the Data Source. The following variable can be found in the "CCI Options" section of the "Server" panel:
- Wait Timeout - Overrides the CCI/PC-based "Reply Wait" value for this particular Data Source definition.
CASERVER & IDMSJSRV Tasks:
Backend timeouts are controlled using the TASK statement within your CA-IDMS CV. The default task codes for the CA IDMS Server product are "CASERVER" and "IDMSJSRV". The CASERVER task is used to service connections coming in via the CCILINE, whereas the IDMSJSRV task is used to service JDBC type-4 connections. There are three variables on these tasks that come into play with regard to timeouts:
- Resource Timeout Interval - Represents the amount of time CA IDMS will allow a dormant connection to persist if no task is active , before terminating the connection.
- External Wait Interval - Represents the amount of time CA IDMS will allow a dormant connection to persist if a task is active , before terminating the task and connection.
- Inactive Interval (or Stall Interval ) - Represents the amount of time CA IDMS will allow a task to wait for a resource, before terminating the task and connection.
Note that a connection is considered dormant if no reads/writes are being performed on the PTE for the connection, and there is no outstanding database request being serviced. Also note that the CA IDMS Server tasks are terminated when a SUSPEND request is received (which occurs after every COMMIT).
Appropriate values for these intervals are highly dependant on the type of activity being performed by the task. Web-based applications tend to run relatively short-lived queries. These applications may want to run with a Task whose:
- " Resource Timeout Interval " is set at about 60 seconds
- " External Wait Interval" is set at about 60 seconds
- "Inactive Interval" is set at about 30 seconds
On the other end of the spectrum, end-user Ad-hoc queries will need significantly larger Resource Timeout and External Wait intervals, owing to the fact that:
- Users may take several minutes to read the contents of a screen before taking some action that will generate another request to the DBMS. This will require an increase in the " Resource Timeout Interval ".
- In certain situations a task may remain active during the time noted above... This will require an increase in the " External Wait Interval".
You may want to establish a unique "CASERVER-like" (or "IDMSJSRV-like") task definition for each different application/web-site/user-group that accesses your CA-IDMS CV. Application specific timeouts (as well as DB Limits if applicable) can then be established for these cloned tasks. The new task definitions should then be referenced in the Data Source definitions used by these applications and/or users.
JDBC type-4 applications can use several additional (JDBC Driver-based) configuration parameters to control the timing-out of the IDMSJSRV task. Refer to the section entitled "J2EE Connection Pooling" (later in this document) for a discussion of these Server-16.0 configuration options and how they relate to a few of the commonly-used App Servers.
Connection Pooling is a performance enhancing mechanism used in both the ODBC and JDBC API's. Connection pooling enables an application to use a connection from a pool of pre-existing connections, rather than having to build (and tear down) a new connection for each new query. This can have a significant positive effect on performance, especially for web-based applications that tend to make repeated (short-lived) queries against the same Data Source. In cases such as this, connection management can represent a substantial portion of the overall time required to execute a query.
There are many products that implement Connection Pooling. It's often implemented at the Web Server layer, but is also found in components such as Microsoft's OLE DB and the ODBC Driver Manager. Connection pooling works by intercepting the "Disconnect" function issued by an application program. Rather than passing this call to the ODBC or JDBC Driver, the call is suppressed and the connection is placed in a "pool". When a "Connect" request is then encountered for the same Data Source, it too is suppressed and one of the pooled connections is returned to the application.
Why do I care about all of this? How is this pertinent to Timeout Configuration in CA IDMS Server?
Connections are retired from the pool after some period of inactivity. This Connection Pooling (CP) Timeout period is generally configurable by the user. For example, in the case of the ODBC Driver Manager, the "CPTimeout" parameter can be set using the "Connection Pooling" tab in the ODBC Administrator. A reasonable timeout interval for pooled connections is about 60 seconds. It's very important that pooled connections be timed-out from the component that created the pool, and not some other downstream layer. Similarly, it's also important that an application not implement Connection Pooling in multiple software components. We'll talk more about these considerations in just a minute. For more information on connection pooling, please refer to:
Also note that Connection Pooling within the CA IDMS JDBC Driver became available on the CA IDMS Database Server 5.0 release. Please refer to Appendix "B" in the CA IDMS Server User guide for more information on this feature.
J2EE Connection Pooling:
All of the popular J2EE Web Servers provide connection pooling facilities within their application server components. This includes IBM's WebSphere, BEA System's WebLogic, and Red Hat's JBoss.
As an alternative to establishing multiple IDMSJSRV tasks on your CV (each with unique timeout specifications), with the 16.0 release of CA IDMS Server you can now set these values on the JDBC-Client side using various properties that you set within your application server. The properties are:
- externalWait - Overrides the external wait interval for the server task invoked by the type-4 driver. This effectively becomes the socket timeout
- resourceInterval - Overrides the resource interval for the server task invoked by the type-4 driver
These (CA IDMS Server) properties are passed to the backend CA IDMS CV when a connection is initially negotiated, and affect the IDMSJSRV (or derivative) task directly. This provides you a means of configuring your timeouts all from one place, without having to modify (and/or create new) task definitions within CA IDMS. These properties can be used by applications running under a J2EE server as well as by standalone Java applications running CA-IDMS Server 16.0.
For applications running under a J2EE app server, two additional properties are also available to affect the "Resource Timeout" interval of your IDMSJSRV task within CA IDMS. They are
- maxIdleTime - Specifies the interval in seconds that a pooled connection can be idle before it is closed.
- propertyCycle - Interval in seconds the pool manager should wait before enforcing these policies.
When the "maxIdleTime" property is set, the internal setting for the "resourceInterval" value on the IDMSJSRV task is set to the value specified plus the value of the "propertyCycle" property. This aligns the task resource interval with the application server idle time so that the CA IDMS system does not terminate an idle pooled connection due to inactivity.
Note that your IDMS Listener PTE must be appropriately configured in order for these properties to be honored. Typically, by default, the IDMS ODBC/JDBC listener PTE is defined as 'TCPJSRV'. To permit your applications to override the timers in IDMS, you must specify the 'TIMEOUT=-1' parameter within the PARM STRING on your listener PTE. This change will need to be made within the IDMS SysGen. To make this change dynamically, on a temporary basis, you can enter the following DCMT command sequence:
- DCMT V PTE TCPJSRV OFFLINE
- DCMT V PTE TCPJSRV PARM 'TASK=IDMSJSRV,TIMEOUT=-1'
- DCMT V PTE TCPJSRV ONLINE
It's intended that you would set these CA IDMS Server properties to the same values used for the corresponding properties within your Application Server. The table below correlates these property names for the leading App Servers:
|CA-IDMS Server Prop.||WebSphere Prop.||WebLogic Property||JBoss Property|
|maxIdleTime||Unused Timeout||Shrink Frequency||Idle_timeout_minutes|
Note that the use of these properties requires the use of the 'IDMS' networkProtocol. Please refer to the sections entitled "DataSource connection Properties" and "IdmsConnectionPoolDataSource" in Appendix 'B' of the CA IDMS Server User Guide for more information on these properties.
Now that we've reviewed all of the timeout configuration points, let's take a look at how these settings relate to one another and review the problems that can occur when they're not properly set.
The problem that users encounter most frequently is the improper timeout of pooled connections. It's quite common for Web-based applications to pool connections. As we noted earlier, it's very important for these pooled connections to be expired by the pooling facility that created them, and not by either:
- Another Connection Pooling facility
- CA IDMS CV
When this occurs, a pooling facility may attempt to re-use a connection that another layer has terminated. This can result in delays (at minimum), failed Web requests (most often times), and even a total inability to access your backend CA IDMS CV from your Web Server. To avoid this, you need to insure that:
- Only 1 Connection Pooling facility is employed
- Your CASERVER Task's " Resource Timeout Interval" is greater than your Pooled Connection Timeout value
The second item (above) has been found to be most problematic. Users who specify a Resource Timeout Interval that is less than their "CPTimeout" value (in the case of the ODBC Driver Manager's pooling facility for example) will prematurely terminate their connections on the CA-IDMS side, without the pooling facility's knowledge. The next time that connection is exercised the SQL request will fail. Depending on the sophistication of the pooling facility, the request will either be retried or the failure will be handed back to the Web user. In extreme cases the pooling facility may even repeatedly attempt to re-use a broken connection, causing a total outage. Note that neither the " External Wait Interval" nor the CCI/PC " Reply Wait" is a factor in this situation, because no backend task is active for pooled connections nor is there any outstanding communications request with the backend CA- DMS CV.
The second Timeout Relationship that we need to discuss has to do with stalled tasks. This case is far less common (or problematic) than that described above, and involves a timeout relationship between the CCI/PC " Reply Wait" interval and the CASERVER Task's " Inactive Interval". Should a timeout occur while processing a request on the backend CV, it's better for the timeout to be triggered within CA IDMS itself (where the work is being performed), rather than within CCI/PC (where we are waiting for a reply). The reason for this is two-fold:
- If the CCI/PC timeout occurs first then the backend CA IDMS session with be "orphaned". This will result in an additional error within CA IDMS when the task either completes or times-out as well.
- It doesn't make much sense to have a task active on the backend CA IDMS CV if there's no client partner to communicate with.
To avoid this situation you should always configure your CCI/PC " Reply Wait" interval to be greater than your CASERVER Task's " Inactive Interval".
Properly configured Timeout settings are necessary for the proper functioning of your CA-IDMS Server applications. While it's impossible to provide a standard configuration recommendation for all environments, a typical Web-based application can use the following configuration as a baseline:
- For ODBC Connections, as well as JDBC type-2 and type-3 connections:
- A unique Data Source should be defined for each Application. The Data Source should have a Wait Timeout interval of 30 seconds (which will override the CCI/PC-based "Reply Wait" interval).
- A unique CASERVER-type Task Code should be defined for each application. The Data Source defined above should reference this Task Code. The Task Code should be defined in CA IDMS with the:
- " Resource Timeout Interval " set at 90 seconds
- " External Wait Interval" set at 90 seconds
- "Inactive Interval" set at 30 seconds
- The Connection Pooling Timeout interval should be set to 60 seconds.
- For JDBC type-4 connections:
- Use the "maxIdleTime" and "propertyCycle" properties to affect the "Resource Timeout Interval" on your IDMSJSRV task.
- The " externalWait" property can be used to override the external wait interval on your task if needed.
- A common task code can likely be used for multiple applications connecting in this manner.
For more information about the CA IDMS Database Server Option please visit: https://docops.ca.com/ca-idms/19/en/using/using-ca-idms-server
Other Relevant Information: