[QODBC ALL] QODBC - QRemote Server Ping Count and Auto-Close Timeout Configuration

Problem Description:

When using QODBC over QRemote (remote access to QuickBooks from another machine), connections may unexpectedly close after a period of inactivity or during long-running queries. This is controlled by two settings: the PingTotalCount limit (maximum pings before forced disconnect) and the Auto Close broken connections interval (how quickly a dead connection is detected and closed).

Affected products: QODBC Desktop, QRemote Server, QRemote Client
Expected outcome: Administrators can configure ping count and auto-close timeout to match their application's expected query duration and network stability.

Symptoms:

• QODBC connections close unexpectedly after a fixed period (e.g., 50 minutes) without any error from QuickBooks or the application.
• Long-running SQL queries via QRemote fail with a connection timeout, even though QuickBooks is still processing the query.
• Connections hang indefinitely after an application crashes - no automatic cleanup occurs.
• "Ping from client socket object" messages flooding the QRemote Server event log (resolved in v24 build 352+).

How Ping and Auto-Close Work Together:

The ping mechanism and the auto-close timeout work in tandem to manage stale connections:

1. Ping interval depends on the "Auto Close broken connections" setting:

2. PingTotalCount is the maximum number of pings before forced disconnect: The total connection lifetime = Ping Interval × PingTotalCount. For example, with Auto Close set to 6 minutes (5-minute ping interval) and PingTotalCount=10: 5 min × 10 = 50 minutes total before forced disconnect.
3. Auto Close broken connections detects dead links: If the client stops responding for the configured interval (e.g., 6 minutes), QRemote Server considers the connection lost and closes it immediately. The effective close time in this scenario is roughly double the interval: 1 minute to detect + 5 minutes of ping timeout = ~11 minutes total.

Configuration via ODBCINST.INI:

PingTotalCount is configured manually in the ODBCINST.INI file on the machine where QRemote Client is installed:

[QRemote Driver for QuickBooks (32 bit)]
PingTotalCount=10

File location: C:\ProgramData\QODBC Driver for QuickBooks\ODBCINST.INI

Recommended values: PingTotalCount should be between 3 and 50. Values above 90,000 are the maximum possible. The default value after installation may be 90,000 (effectively unlimited), which means connections will only close due to network issues or manual intervention.

Example Scenarios:

Scenario 1 - Hung SQL Statement:

A SQL query is executing on the QuickBooks side, but the application crashes before closing the connection. With PingTotalCount=10 and Auto Close=6 minutes, QRemote Server keeps the connection open for 50 minutes (5-minute ping × 10 counts), then aborts the statement and closes the connection automatically.

Scenario 2 - Network Disconnect During Query:

A network issue interrupts communication between QRemote Client and Server during an active query. With Auto Close=6 minutes, the server detects the lost connection after 6 minutes. Combined with ping timeout, the total close time is approximately 11 minutes. The connection is automatically terminated.

Scenario 3 - Long-Running Report Query:

A report takes longer than 50 minutes to execute (with default PingTotalCount=10 and Auto Close=6). The connection will be forcefully closed at the 50-minute mark. To prevent this, increase PingTotalCount in ODBCINST.INI (e.g., set it to 100 for an approximate 8-hour window).

Additional Notes:

• Ping flood fix (v24+): Starting with QODBC v24 build 352, the "Ping from client socket object" log spam issue was resolved. A ping count limit was added to prevent excessive logging.
• Default PingTotalCount after fresh install: May be set to 90,000 (effectively unlimited). Modify as needed for your environment's needs.
• Auto Close broken connections setting: This is configured in the QODBC DSN settings under the General tab. It controls how quickly stale connections are detected and cleaned up.
• Configuration applies to the QRemote Client machine: Only modify ODBCINST.INI on machines that run the QRemote Client, not the QuickBooks server machine.

Keywords: