Connection Glossary: Service, sqlnw, DSNs and Ports

Start here when a setup page uses an unfamiliar name. These definitions apply throughout this 6.2.1 64-bit cookbook. The port values below belong to this edition's tested configuration; use the site's actual server names and verified listeners.

Find a term: Service field · sqlnw and the services file · Custom aliases · Check this computer · Host and endpoint · Database and DSN · Windows services and Services.msc · Gateway, Pipe and Socket · Ports.

Service field

The ODBC Service field is optional. Leaving it blank is a valid choice for the standard connection. Blank does not disable networking or leave the port undecided. The tested Dharma driver first looks up the TCP service name sqlnw on the client computer. Entering sqlnw explicitly requests that same lookup. With the same mapping, blank and explicit sqlnw select the same port.

This is different from Services.msc. The ODBC Service field selects a network port by name. Services.msc manages Windows background programs. Leaving this ODBC field blank does not stop a Windows service, and entering sqlnw does not start one.

This cookbook's current connection recipe uses the blank Service field. This is distinct from the default database name appx. Entering appx in Service requests a TCP service alias named appx; it does not select the APPX database. No appx TCP service alias is required for the standard recipe.

The shipped driver-install command creates the DSN with Host and Database but does not supply a Service value. An existing DSN can retain a previously configured value. Inspect the actual field rather than assuming that a screenshot of an existing installation shows an untouched installer default.

sqlnw and the Windows services file

sqlnw is a TCP service alias: a name used to look up a port number. It is the default network-service name used by the tested Dharma networking code. It is not an APPX user, SQL dictionary, Windows background-service name, executable or separate program to install.

Windows reads the name-to-port mapping from C:\Windows\System32\drivers\etc\services on the computer running the client. For this edition's verified gateway port, the relevant line is:

sqlnw          1992/tcp

This line means “when this computer looks up sqlnw for TCP, use port 1992.” It does not start the gateway, change its listening port, open a firewall or configure another computer. On a separate client and gateway, their services files are separate. Check each computer that performs a service-name lookup.

An existing wrong mapping can override the intended port even when Service is blank. Duplicate entries can select an unintended port; use one deliberate mapping for the selected alias. If no sqlnw mapping exists, the tested Supplied Dharma 14.01 x64 client falls back to TCP 1992. That fallback is a measured property of this driver, not a promise that every APPX/ODBC release uses that port. Another edition can use a driver with a different fallback.

The matching gateway script adds sqlnw 1992/tcp when its substring check finds no existing 1992 text. It does not reconcile duplicate service names. This test deliberately removed a conflicting older mapping and verified one sqlnw 1992/tcp entry against the actual listener.

Choosing a custom service name

Use a custom alias only when deliberately selecting a different gateway listener, for example when two gateways on the same host use different ports. An administrator can add appx_reporting 21990/tcp on the client and enter appx_reporting in the ODBC Service field. That example requires a gateway actually listening on TCP 21990 and the corresponding firewall access; adding the line alone does not create a working gateway.

Changing a mapping affects new connections that use that alias on this computer, including blank-Service connections that default to sqlnw. Changing one DSN to a distinct custom alias affects clients using that DSN. Preserve the original file and DSN before changing either. Close and reopen the client, then verify the destination port and the sample query. Keep the field as a service name in these recipes; do not substitute a numeric port without separately checking that driver's handling of numeric Service values.

Check the Service setting on this computer

1. Check the application's connection settings to find the DSN it actually uses. The cookbook uses AppxODBC. A workbook, report or connection string can override saved DSN settings, so inspect its Host and Service overrides as well. For example, Excel can retain SERVICE=sqlnw after the DSN is cleared. Clear Service in the workbook's login dialog, complete a refresh and save the workbook to retain the empty setting. Do this on the computer running that client; one desktop's settings do not establish another's.
2. Open C:\Windows\SysWOW64\odbcad32.exe for a 32-bit application, or C:\Windows\System32\odbcad32.exe for a 64-bit application. Match the application architecture, even on 64-bit Windows.
3. Select System DSN, select the actual DSN and choose Configure. If the application uses a User DSN, check User DSN under that same Windows account instead. Read Host, Database and Service. Choose Cancel when finished inspecting so the check does not change the connection.
4. If Service is blank, the tested driver uses the sqlnw lookup. If it contains sqlnw, that alias was explicitly requested. If it contains another name, look up that name instead. Open C:\Windows\System32\drivers\etc\services read-only and inspect the matching active entry, including aliases after the port. Text following # is a comment. Check for conflicting or duplicate entries.
5. Compare the resulting port with the gateway's actual listener. If no matching sqlnw entry exists, this edition's measured client fallback is 1992. Do not assume another custom name uses that same fallback. A valid port mapping alone does not prove that the intended gateway is running, reachable or able to authenticate.

For this edition's 64-bit System DSN on 64-bit Windows, run the following in 64-bit PowerShell. Replace AppxODBC in the registry path if the application uses another DSN. The commands read settings and active mapping lines; they do not change the DSN, services file, listener or firewall, and they display no password fields.

$dsn = Get-ItemProperty 'HKLM:\SOFTWARE\ODBC\ODBC.INI\AppxODBC'
$dsn | Select-Object Host, Database, Service
$alias = if ([string]::IsNullOrWhiteSpace($dsn.Service)) { 'sqlnw' } else { $dsn.Service }
"TCP alias selected: $alias"
Get-Content "$env:WINDIR\System32\drivers\etc\services" |
  Where-Object { ($_ -split '#', 2)[0] -match ('(^|\s)' + [regex]::Escape($alias) + '(\s|$)') }

An empty Service output cell means the DSN has no nonblank override. For the standard setup the displayed alias should be sqlnw, and its active line should select 1992/tcp for this gateway. No output from the last command means no matching active mapping was found; use the separately verified fallback information above. A populated Service field containing another name is a custom choice, not an APPX database name.

For a User DSN, the Windows-user registry location is HKCU:\SOFTWARE\ODBC\ODBC.INI\AppxODBC; inspect it while signed in as the application user. For a 64-bit System DSN, the location is HKLM:\SOFTWARE\ODBC\ODBC.INI\AppxODBC, without WOW6432Node. Microsoft documents the ODBC Administrator and registry distinctions. A DSN-less connection has no saved DSN to inspect: check the application's connection string while keeping any credentials private.

Host, localhost and endpoint

Host names the computer running the ODBC gateway. A hostname is a name that DNS or the local computer resolves to an IP address. localhost means the computer running the program, not automatically the APPX server. Use localhost only when the required gateway is on that same computer.

An endpoint is a host plus its listening TCP port. Here the client contacts the gateway at localhost:1992. The gateway separately contacts the APPX login manager at localhost:31062, as recorded in APPX_DATA_SERVER inside appx.dbs\appx.env. A remote client changes its DSN Host to the gateway host; the gateway's backend endpoint can remain on another computer.

Database, dictionary, DSN and APPX IDs

Database appx selects the SQL dictionary created on the gateway as appx.dbs. A dictionary stores SQL definitions describing APPX files; it is not the TCP service alias and is not a copy of the business records. ASQL Dictionary Importer reads the APPX file definitions and creates the shared SQL metadata in that dictionary.

DSN means Data Source Name: the saved ODBC connection settings on the client. AppxODBC is the default DSN name used by these recipes. A System DSN is available to authorized applications across Windows user accounts; a User DSN belongs to one Windows user. Its driver architecture must match the client program. In Windows, SysWOW64 contains the 32-bit ODBC Administrator and System32 contains the 64-bit administrator.

DMO / DMO are the Database ID and Application ID inside APPX. COUNTRY is the APPX file. ASQL exposes it as DMO_DMO_COUNTRY in SQL. These identifiers have different purposes from the gateway dictionary appx, the DSN AppxODBC, and the TCP alias sqlnw.

Windows services and service accounts

A Windows service is a background program managed by Windows Service Control Manager. The gateway's installed Windows service is Appx ODBC Data Gateway Server for Windows. sc.exe query and sc.exe start take this Windows service name, not the ODBC Service field's sqlnw alias. Running means the background program started; verify its actual listening socket as well.

Services.msc belongs to this Windows-service context, not the ODBC Service field. Open it on the gateway computer to inspect or manage the gateway background program, and on the APPX server to inspect the login manager. Do not search Services.msc for sqlnw as the way to check a port alias. The alias belongs in the plain-text services file described above. Microsoft's Service Control Manager reference describes the Windows component that controls background services.

The APPX login manager is another Windows service. This cookbook's test name is Appx-621-31062-OSAuth. Its name identifies the managed login-manager process, while 31062 is the separate TCP port on which that process accepts gateway connections. Use the site's actual Windows service name in service commands and in the HKLM\SYSTEM\CurrentControlSet\Services registry path.

A service account is the Windows identity under which a background service runs. It needs the appropriate file and log-directory permissions. It is separate from the APPX user entered in an ODBC login. An ODBC Service field value does not select either identity.

Gateway, driver, listener, Pipe and Socket

The ODBC driver is the client DLL loaded by Excel, Access, WinSQL, PowerShell or another ODBC application. The gateway receives its SQL requests and obtains records from the APPX engine. A listener is the program accepting TCP connections on a specific port. A firewall rule can permit traffic to that port; it does not prove that the right program is listening.

Pipe and Socket in the APPX Windows login-manager configuration describe its interface to the APPX engine. This edition was tested with Socket. That setting is separate from the desktop-to-gateway TCP connection and its ODBC Service field. Do not change it merely to match another edition's recipe.

Port reference for this edition

Use the gateway Windows-service and listener check, the client DSN check, and the complete COUNTRY result to verify the connection. A successful TCP probe alone does not verify authentication, imported metadata or correct field values.