KEEPALIVE (-KEEPALIVE)

The -KEEPALIVE command limits the amount of time that an HTTP adapter can reuse a connection. You can use the -KEEPALIVE command to prevent the HTTP adapter from attempting to reuse a connection that is closed (for example, when the connection exceeds the HTTP server KeepAliveTimeout setting).

A map reuses a connection under two conditions:
  • A running map reuses an active HTTP connection when it issues multiple HTTP requests that have the same command-line connection options within the same map instance.
  • A map also reuses an idle HTTP connection when it runs multiple times in different map instances. 
-KEEPALIVE timeout
Option
Description
timeout
The number of seconds that can elapse between consecutive reuses of a connection. After the timeout is exceeded, the HTTP adapter does not reuse the connection. Valid values are 0 - 99999. A 0 value specifies no connection reuse.

Example

A map issues multiple HTTP requests and runs multiple times. The HTTP server has a KeepAliveTimeout of 5 seconds. The tx_install_dirdtx.ini file has an IdleHTTP=10 setting.

The map processing sequence is:
  1. A new instance of Map 1 starts.
  2. Map 1, Input Card 1, iteration 1.
  3. Map 1, Output Card 1, iteration 1 runs.
    1. The HTTP adapter establishes Connection 1, or reuses a connection from a prior map that has similar HTTP settings.
    2. The map issues an HTTP Post operation.
  4. Map 1, Input Card 1, iteration 2.
  5. Map 1, Output Card 1, iteration 2 runs.
    1. The HTTP adapter reuses Connection 1.
    2. The map issues an HTTP Post operation.
  6. Map 1 completes.
  7. Map 1 runs again with a new instance number and repeats step 1.
Without the -KEEPALIVE command, consider these potential failure scenarios:
  • More than 5 seconds elapse between HTTP POST operations (steps 3b and 5b):
    • The HTTP server KeepAliveTimeout closes the connection.
    • The HTTP adapter attempts to use the active (but closed) connection in step 5b, and the map fails.
  • Less than 10 seconds elapse between step 5b in the first map instance and step 3a in the new map instance:
    • The HTTP adapter reuses the idle connection.
    • Step 3b activates the reused connection.
    • If more than 5 seconds elapse between HTTP POST operations (steps 3b and 5b), the HTTP server KeepAliveTimeout closes the connection. When the HTTP adapter attempts to use the active (but closed) connection in step 5a, the map fails.
The -KEEPALIVE 5 adapter command prevents the HTTP adapter from reusing a connection if more than 5 seconds elapse since the last time the map used the connection. Consider these successful scenarios:
  • More than 5 seconds elapse between HTTP POST operations (steps 3b and 5b):
    • The HTTP server KeepAliveTimeout closes the active connection.
    • The -KEEPALIVE 5 adapter command prevents the HTTP adapter from reusing the active (but closed) connection.
    • The HTTP adapter establishes a new connection, and the map completes successfully.
  • The connections idle time between map instances (steps 6 and 7) is between 5 - 9 seconds:
    • The idle time is less than 10 seconds, so the idle connection qualifies for reuse.
    • The time between requests exceeds the server KeepAliveTimeout value. The HTTP server closes the connection.
    • The -KEEPALIVE 5 adapter command prevents the HTTP adapter from reusing the idle (but closed) connection in step 3a.
    • The HTTP adapter establishes a new connection, and the map completes successfully.