Configuring the "Timeout" Parameters when using IDMS Server

Products

• IDMS
• IDMS - Database

Issue/Introduction

Timeout configuration is an important (yet often times overlooked) step in the deployment of an application that uses IDMS Server. This article outlines some of the common problems that can occur with connection timeouts and looks at the various places where timeout parameters can be specified.

Environment

Release: All supported releases.
Component: IDMS Server.

Resolution

Timeout configuration is an important (yet often times overlooked) step in the deployment of an application that uses IDMS Server. Timeouts apply to both the ODBC and JDBC Drivers within IDMS Server, and are important for two reasons:

• Limiting the time a front-end client application will wait for a response from IDMS (in the event of a back-end failed/stalled task, communications error, etc), thereby eliminating prolonged hangs.
  
  
• Permitting 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. This article discusses each of those components, provides some general recommendations on appropriate timeout values, talks about "Connection Pooling", and looks at the interactions between these software components.

CCI PC:

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 CCI PC properties sheet. They are:

• Reply Wait - Represents the number of seconds that CCI PC will wait for a response from IDMS. The default value is '-1' (indefinite).
  
  
• Ready to Receive - Represents the number of seconds that CCI PC will wait for the receipt of the second (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 CCI 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 three 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 IDMS CV) within this interval, then an appropriate error will be generated and handed back to the 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 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 IDMS CV. The default task codes for the 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 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 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 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 IDMS Server tasks are terminated when a SUSPEND request is received (which occurs after every COMMIT).

Appropriate values for these intervals are highly dependent 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".

It may be a good idea to establish a unique "CASERVER-like" (or "IDMSJSRV-like") task definition for each different application/web-site/user-group that accesses the 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 configuration options and how they relate to a few of the commonly-used App Servers.

Connection Pooling:

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 is all of this interesting? How is this pertinent to Timeout Configuration in 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. These considerations are discussed further down. For more information on connection pooling, please refer to:

• Microsoft (ODBC): Pooling in the Microsoft Data Access Components
  
  
• Oracle (JDBC): Connection Pooling and Caching

Also note that Connection Pooling within the IDMS JDBC Driver became available on the IDMS Database Server 5.0 release. Please refer to the IDMS Server Reference guide and the Advanced Configuration section Configure Timeouts 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 the CV (each with unique timeout specifications), with the 16.0 release of IDMS Server it is now possible to set these values on the JDBC-Client side using various properties that can be set within the 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 (IDMS Server) properties are passed to the backend IDMS CV when a connection is initially negotiated, and affect the IDMSJSRV (or derivative) task directly. This provides a means of configuring the timeouts all from one place, without having to modify (and/or create new) task definitions within IDMS. These properties can be used by applications running under a J2EE server as well as by standalone Java applications running 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 the IDMSJSRV task within 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 IDMS system does not terminate an idle pooled connection due to inactivity.

Note that the 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 the applications to override the timers in IDMS, specify the 'TIMEOUT=-1' parameter within the PARM STRING on the listener PTE. This change will need to be made within the IDMS SysGen. To make this change dynamically, on a temporary basis, 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 these IDMS Server properties should be set to the same values used for the corresponding properties within the 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
propertyCycle	Reap Time	(n/a)	(n/a)

 

Note that the use of these properties requires the use of the 'IDMS' networkProtocol. Please refer to DataSource Connection Parameters for more information on these properties.

Timeout Relationships:

Now that all of the timeout configuration points have been reviewed, it's time to 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 noted earlier, it's very important for these pooled connections to be expired by the pooling facility that created them, and not by either:

1. Another Connection Pooling facility
   
   
2. 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 the backend IDMS CV from your Web Server. To avoid this, ensure that:

1. Only one Connection Pooling facility is employed
   
   
2. The CASERVER Task's " Resource Timeout Interval" is greater than the 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 the "CPTimeout" value (in the case of the ODBC Driver Manager's pooling facility for example) will prematurely terminate the connections on the 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 IDMS CV.

The second Timeout Relationship 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 IDMS itself (where the work is being performed), rather than within CCI PC (which is waiting for a reply). The reason for this is two-fold:

1. If the CCI PC timeout occurs first then the backend IDMS session with be "orphaned". This will result in an additional error within IDMS when the task either completes or times-out as well.
   
   
2. It doesn't make much sense to have a task active on the backend IDMS CV if there's no client partner to communicate with.

To avoid this situation, always configure the CCI PC " Reply Wait" interval to be greater than the CASERVER Task's " Inactive Interval".

Summary:

Properly configured Timeout settings are necessary for the proper functioning of 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:
  
  
  • " Resource Timeout Interval " set at 90 seconds
    
    
  • " External Wait Interval" set at 90 seconds
    
    
  • "Inactive Interval" set at 30 seconds
    
    
• 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 IDMS with the:
  
  
• 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 the IDMSJSRV task.
  
  
• The "externalWait" property can be used to override the external wait interval on the task if needed.
  
  
• A common task code can likely be used for multiple applications connecting in this manner.

Additional Information

Install IDMS Server