Locating SQL Anywhere database servers using the Host connection parameter

A SQL Anywhere client attempting to find a database server over TCP/IP using the Host connection parameter tries the following steps to find the server:

If the database server is not found, then an error specifying that the server is not found is returned. If a different error occurs, then the connection attempt fails without attempting further steps. See Database server not found.

Once the client has successfully connected to the database server, it attempts to connect to the database. See Locating the database.

  • Step 1: Check the database server address cache (sasrv.ini)   If the connection string includes the Host connection parameter but not ServerName, the SQL Anywhere client cannot use the sasrv.ini file. See Step 2: Attempt a TCP/IP connection to the address(es) specified in the Host connection parameter.

    The client checks its sasrv.ini file for an entry that matches the database server name specified by the ServerName connection parameter.

    If no matching cache entry is found, the client attempts a direct TCP/IP connection. See Step 2: Attempt a TCP/IP connection to the address(es) specified in the Host connection parameter.

    If a cache entry matches both the ServerName connection parameter and the address specified by the Host connection parameter, the client attempts a TCP/IP connection to the IP address listed in the cache.

    • Step 1: Example   Assume there is a computer with the host name kangaroo and the IP address 10.25.13.5. A database server named joey is running on this computer on port 49152.

      For the connection string Host=kangaroo;ServerName=joey, the client finds an entry in its sasrv.ini file that matches the server name joey. The IP address in the cache is 10.25.13.5:49152. The client compares the address of the specified Host name with 10.25.13.5. The addresses match, so the client connects over TCP/IP to 10.25.13.5:49152 and then verifies that the connected server is named joey. The connection is successful.

  • Step 2: Attempt a TCP/IP connection to the address(es) specified in the Host connection parameter   When multiple addresses are specified, the client attempts to connect to each address in the order that they are specified in the Host connection parameter. The client attempts connections until it connects successfully or it has tried all the addresses.

    When an address includes a port, the client attempts a TCP/IP connection to the address and port number specified. If no port is specified, then the client attempts a TCP/IP connection at the specified address on the default port, 2638.

    • If the client connects to the database server and ServerName is specified, the client compares the database server's name to the value specified by ServerName.

      If the database server name matches, then the connection is successful. The client updates its sasrv.ini file.

      If the database server name does not match, then the client attempts to connect using UDP find server requests. See Step 3: Send out UDP find database server requests.

    • If the client connects to the database server and ServerName is not specified, then the connection is successful.

    • If the client cannot connect and a ServerName is specified, then the client attempts to connect using UDP find server requests. See Step 3: Send out UDP find database server requests.

    • If the client cannot connect and ServerName is not specified, then the connection fails.

    • Step 2: Example   Assume there is a computer with the host name kangaroo and the IP address 10.25.13.5. A database server named joey is running on this computer on port 49152. This is the first time that the client has connected to this server, so there is no cached address in its sasrv.ini file.

      For the connection string Host=kangaroo:49152;ServerName=joey, the client connects over TCP/IP to 10.25.13.5:49152 and then verifies that the connected server is named joey. The connection is successful, so the client updates its sasrv.ini file.

  • Step 3: Send out UDP find database server requests   The SQL Anywhere client only sends out UDP find database server requests when the connection string includes the ServerName connection parameter and the Host value does not specify a port. UDP find server requests are sent to port 2638 on the specified addresses.

    By default, all the database servers on the same computer (except for a computer running Mac OS X) listen for UDP packets on port 2638. On Mac OS X, only one server can listen for UDP packets on port 2638. When a database server receives a UDP find server request, the database server compares its name to the name specified in the UDP request. If the names match, then the database server sends back a UDP response packet containing its IP address and port number. Only the matching database server sends a response packet.

    By default, the client waits up to five seconds for a UDP response. If no responses are received, the UDP packets are re-sent every second until this process times out.

    When the client receives the UDP response packet, the client attempts a TCP/IP connection to the address and port specified in the packet.

    If the client can connect to a database server, then the connection is successful. The client updates its sasrv.ini file.

    Note

    UDP packets cannot find the following database servers:

    In each of these cases, specifying the port of the database server in the Host connection parameter should allow the client to connect successfully.

    • Step 3: Example   Assume there is a computer with the host name kangaroo and the IP address 10.25.13.5. A database server named joey is running on this computer on port 49152. This is the first time that the client has connected to this server, so there is no cached address in its sasrv.ini file.

      For the connection string Host=kangaroo;ServerName=joey, the client attempted to connect over TCP/IP to 10.25.13.5:2638 and it failed (Step 2). Because the connection string does not have a port number specified, the client sends UDP find server requests to address 10.25.13.5:2638. The database server joey is listening on UDP address 10.25.13.5.2638 and responds with the address 10.25.13.5:49152. The client connects over TCP/IP to 10.25.13.5:49152. The connection is successful, so the client updates its sasrv.ini file.