Chapter 8: Solve Connection and Import Problems
Set Connection and Diagnostic Options
Set a variable for the process that reads it. An environment setting in an Excel user's command window does not change an already-running gateway or an APPX engine started by the login manager. These scopes follow the reviewed 5.5.1 source; other releases should be checked separately.
| Variable | Purpose | Where to set it for this recipe |
|---|---|---|
ASQL_EXPERT_MODE=1 | Enables ASQL's script-editing controls. Presence enables it, even if the value is 0. | In the command window used to start ASQL on the administration computer. Clear it with set "ASQL_EXPERT_MODE=". |
ASQL_LOG=C:\ODBC-Logs\asql.log | Records ASQL's generated SQL and ODBC operations. Opening ASQL overwrites this file. | In the same command window, before starting ASQL. |
APPX_DATA_SERVER=localhost:31052 | Selects the APPX backend host and login-manager port. | On the gateway, in C:\Program Files (x86)\AppxODBCserver\appx.dbs\appx.env. Use the actual APPX hostname for a remote server. |
APPX_ODBC_LOG=C:\ODBC-Logs\gateway.log | Traces the APPX storage-manager part of the gateway, including file mapping and reads. Its default fallback is C:\tmp\appx-odbc.log if that path is writable. | In the gateway dictionary's appx.env, before opening a fresh connection. A new gateway task can overwrite the file; reproduce with one diagnostic connection. |
APPX_ODBC_CODE=-1 | Selects gateway trace categories; this is the source's default of all categories. 0 suppresses messages. | Alongside APPX_ODBC_LOG in the gateway dictionary's appx.env. |
APPX_NETIO_LOG=C:\ODBC-Logs\gateway-netio.log | Traces the APPX/Net file-manager client used by the gateway to reach APPX. | In the gateway dictionary's appx.env for the gateway side of the backend connection. |
APPX_NETIO_CODE=-1 | Selects that file-manager client's logging categories. | Alongside APPX_NETIO_LOG in the gateway dictionary's appx.env. |
APPX_NET_LOG=C:\ODBC-Logs\network | Traces APPX communication. The source adds a PID and role suffix to the filename. | In the gateway dictionary's appx.env for gateway traffic; in the login manager's engine Environment subkey for the APPX server side. Each side writes locally. |
APPX_NET_LOG_MASK=-1 | Selects communication trace categories. | In the same process environment as APPX_NET_LOG. |
APPX_NETIO_SERVER=C:\ODBC-Logs\server-netio.log | Traces the APPX/Net file-manager server serving file requests. | In the APPX login manager's engine Environment subkey, for the APPX engine handling the ODBC connection. |
APPX_IO_LOG=C:\ODBC-Logs\io_$(pid).log | Logs native APPX file I/O; the PID substitution separates engine log files. | In the APPX login manager's engine Environment subkey. |
APPX_IO_BITS=0xFFFFFFFF | Selects native APPX file-I/O logging categories. | Alongside APPX_IO_LOG for the APPX engine. |
APPXPATH | Identifies an APPX installation's application/data root. ASQL also uses it when searching for local System Administration structures. | Retain the APPX engine's existing configuration. Set it in an ASQL command window only when deliberately using local structures from that installation; it is not the gateway Host setting. |
APPX_UID | Carries an APPX login internally when connecting to the backend. | The gateway builds it from the supplied login. Use the client login prompt; do not put a password in a public script or shared appx.env. |
ASQL: one command window
Create a local log directory on the ASQL computer. Run these commands individually in Command Prompt:
mkdir C:\ODBC-Logs set "ASQL_EXPERT_MODE=1" set "ASQL_LOG=C:\ODBC-Logs\asql.log" "C:\Program Files (x86)\AppxODBCDriver\asql.exe"
After the reproduction, close ASQL and clear both overrides:
set "ASQL_EXPERT_MODE=" set "ASQL_LOG="
Keep ASQL logs private. The reviewed ASQL logging code can record the connection string, including a password. Do not attach or publish the raw log; remove credential-bearing lines from a separate copy before sharing it. Turn logging off after the focused reproduction.
This does not enable logging in Excel, WinSQL, the gateway service or the APPX server. For desktop driver-manager tracing, use the Tracing tab in the appropriate Windows ODBC Administrator; it is a separate diagnostic from ASQL_LOG and the gateway logs.
Gateway: the selected dictionary's appx.env
On the gateway computer, preserve appx.dbs\appx.env before editing it. Keep its APPX_DATA_SERVER line, add only the needed diagnostic assignments, and ensure the gateway service account can write the chosen local log directory. Start a fresh ODBC connection after the change; an existing initialized gateway task can retain its earlier settings. Arrange a gateway-service restart only if needed during a maintenance interval, because it affects other connected users.
For a first file-mapping diagnostic, add:
APPX_ODBC_LOG=C:\ODBC-Logs\gateway.log APPX_ODBC_CODE=-1
These are text-file assignments, not commands to run at a desktop prompt. Remove the added diagnostic lines after the test, reconnect, and retain the original endpoint configuration.
APPX engine: the login manager's Environment subkey
On the APPX server, the Windows login manager reads named string values from this registry subkey and supplies them to the engines it starts:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Appx-551-31052-OSAuth\Environment
Substitute the actual APPX login-manager Windows service name, not the ODBC Service alias sqlnw. Back up that subkey, then add individual REG_SZ values such as APPX_IO_LOG and APPX_IO_BITS, preserving its existing values. This APPX subkey is different from a generic Windows service's Environment multi-string value. Do not replace the entire service environment with a single logging assignment.
Make the log directory writable by the engine's account. Restart the corresponding login manager at an agreed interval, then create a new client connection so a new engine inherits the settings. In the reviewed source, machine-level environment values can override the same names in this subkey when LoadSystemEnvironment is enabled; check for duplicate definitions if a setting appears ineffective.
CreateLogFile and LogAllEvents are login-manager configuration properties, not environment variables. They belong under the APPX login-manager Windows service's Config subkey. Gateway sql_server.log is also a separate SQL-server log. Neither is enabled by setting ASQL_LOG on a desktop.
Log files can contain SQL, field values, paths and connection details. Collect one focused reproduction, keep the original evidence private, redact shared copies, then remove the temporary settings. Never publish a credential-bearing environment dump.