Locating SQL Anywhere database servers using the CommLinks=TCPIP connection parameter

Note

It is recommended that you only use the CommLinks (LINKS) connection parameter if you need to specify TCP/IP protocol options other than HOST or ServerPort (PORT). Otherwise, use the Host connection parameter. See Host connection parameter.

You cannot specify both CommLinks and Host in the connection string.

The Host connection parameter is different from the HOST protocol option. The HOST protocol option is used by the CommLinks connection parameter. See Host (IP) protocol option (client side only).

A SQL Anywhere client attempting to find a server over TCP/IP using the CommLinks 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 protocol option but not the ServerName connection parameter, the LocalOnly protocol option is set to YES, or the DoBroadcast protocol option is set to NONE, then the SQL Anywhere client attempts a direct TCP/IP connection. That is, the SQL Anywhere client does not use the database server address cache or the LDAP server. See Step 3: Attempt a TCP/IP connection to the address(es) specified in the HOST protocol option.

    The client checks its sasrv.ini file for an entry that matches the database server name specified in the ServerName connection parameter. If the connection string also includes the HOST protocol option, then the cache entry must also match the host address specified.

    If no matching cache entry is found, the client attempts to find the database server using LDAP. See Step 2: Check the LDAP server for the server name.

    When a matching cache entry is found, the client attempts a TCP/IP connection to the IP address listed in the cache.

    • If the client connects to the database server using this IP address and the VerifyServer protocol option is set to No, the connection is successful. See VerifyServerName (VERIFY) protocol option (client side only).

    • If the client connects to the database server using this IP address and VerifyServer is set to Yes (the default), the client compares the database server's name to the value specified by ServerName. If the database server name matches, the connection is successful. If the database server name does not match, the client removes the entry from its sasrv.ini file, and the client attempts to find the database server using LDAP. See Step 2: Check the LDAP server for the server name.

    • If the client cannot connect, it removes the entry from its sasrv.ini file and attempts to find the database server using LDAP. See Step 2: Check the LDAP server for the server name.

    Note

    The database server address cache file name on Unix is .sasrv.ini.. See Caching database server address information in sasrv.ini for faster connections.

    • 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 CommLinks=TCPIP(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: Check the LDAP server for the server name   A SQL Anywhere client queries the LDAP server for an entry that matches the ServerName connection parameter when the SQL Anywhere client and database server computers are configured to use an LDAP server. See Connecting using an LDAP server.

  • Step 3: Attempt a TCP/IP connection to the address(es) specified in the HOST protocol option   If the HOST protocol option is not specified, the SQL Anywhere client attempts to find the Server using UDP find server requests. See Step 4: Send out UDP find database server requests.

    The SQL Anywhere client attempts to connect over TCP/IP to the addresses specified in the HOST protocol option. When multiple addresses are specified, the client attempts to connect to each address in the order that they are specified in the HOST protocol option. The client attempts connections until it connects successfully or it has tried all the addresses.

    When the connection string includes a port (in either the HOST protocol option or the ServerPort connection property), 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 using the specified address and the VerifyServer protocol option is set to No, the connection is successful. See VerifyServerName (VERIFY) protocol option (client side only).

    • If the client connects to the database server using the specified address, the client compares the database server's name to the value specified by ServerName. If the database server name matches, the connection is successful and the client updates its sasrv.ini file. If the database server name does not match, the client attempts to connect using UDP find server requests. See Step 4: Send out UDP find database server requests.

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

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

    • 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 CommLinks=TCPIP(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 4: 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 DoBroadcast protocol option is set to DIRECT or ALL.

    • When DoBroadcast=DIRECT or the HOST protocol option is specified, the client sends UDP find server packets to the address(es) specified. When a port is specified (in either the HOST protocol option or the ServerPort protocol option), the UDP find server request is sent to the specified port; otherwise, the request is sent to the default port, 2638.

    • When DoBroadcast=ALL and no HOST protocol option is specified, the client determines the subnet's broadcast address for each of its IP addresses. If the ServerPort protocol option is specified, the client sends UDP broadcast find server packets to the specified port; otherwise, the UDP broadcast packets are sent to the default port, 2638.

    Unless the -sb 0 option has been specified when the database server started, then all the database servers 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 request packet. 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 address (including the port number) of the database server in the HOST protocol option should allow the client to connect successfully.

    • Step 4: 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. The connection is being attempted from a computer on the same subnet as kangaroo, and the broadcast address for this subnet is 10.25.13.255.

      For the connection string CommLinks=TCPIP;ServerName=joey, the client sends UDP find server broadcast requests to the broadcast address 10.25.13.255: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.