Sender: usenet@sybase.com
Organization: Sybase, Inc.

Technical bulletin              January 1993                Benjamin von Ullrich
                                              
       SYBASE Customer Service & Support

Many current versions of SYBASE Servers and front-end software support more
than the default single network listener per server.  In previous releases,
a SQL or Open Server had only one NETWORK HANDLER process, and could listen on
only one port on a single network interface on its host computer.

With the new availability of multiple network protocols on many SYBASE
platforms, and additionally the option for multiple network controllers
on many platforms (for other protocols or backup for the default,
"built-in" network controller), SYBASE has added the capability to
configure your "interfaces" file to prompt SQL Server to automatically
spawn multiple NETWORK HANDLER processes to listen on more than one
interface and/or protocol on its host machine.  MORE INFO NEEDED: Open
Server may operate similarly, if the programmer adds code to sense and
create the additional network listeners.

Front-end software may be directed to any of the configured network ports by
assigning clients to specific DSLISTEN server names, and allowing for backup
network ports in the event of failure of the primary port for whatever reason.

This feature became available on ABI (Application Binary Interface)
platforms in SQL Server 4.2 .  It does not work on non-ABI platforms until
SYBASE release 4.8 .

To use this feature in your environment, the following steps must be 
completed on your host machine and/or network:

o       A unique hostname for each network interface must be defined in your
operating system's host database (UNIX's /etc/hosts or NIS/DNS; VMS's
NCP, or the like).  Thus, if your computer has two network interfaces,
you need to issue a unique hostname on each network, so the
different interface pathways may be uniquely identified in your
SYBASE interfaces file.

o       The interface must be known to the operating system kernel or network
driver.  On UNIX machines, this means the interface must have been configured
for use by the ifconfig utility.  In VMS, the interface must be configured in
NCP for the network to be up and available on DECnet.  This insures that the
operating system will be listening on the respective networks, when clients
request connections, and when SYBASE servers open ports for listening.

In general, any secondary network interface (in addition to the default one
already in use on your SYBASE server(s)) must pass all tests and requirements
set forth in the Open Server or SQL Server Installation Guide for your version
of this software.  All instances of NETWORK HANDLER operate on the same
principles of an exact set of supported protocols over mediums that may be
tested with operating system utilities before utilization in SYBASE server
software.  Please be sure to test any network interface with the steps given in
the install guide before configuring it in your interfaces file.  This helps
flush out any network configuration problems before SYBASE attempts to use the
interface(s).


Steps to Configure your SYBASE server for Multiple Network Listener Ports

In your $SYBASE/interfaces file, add clones of the "master" line for
the SQL Server, one additional for each interface you want SQL Server
to listen on.  Be sure to include a unique hostname on each line to
configure a NETWORK HANDLER for each network interface.  Port numbers
within the interface need not be the same, but may be.  They fall under
the same rules for naming and numerical range as are required for the
primary network interface.

The easiest way to safely add "master" lines is to use a text editor to copy
the existing master line for your server, and re-insert a copy of it next to
the original one.  Next change the hostname on the new line to the hostname
corresponding to your machine's identity on the new network interface.  Since
the port numbers may be the same (they are on different interfaces),
this is all that need be done.

** NOTE:  Be certain that the leading whitespace tabulation on all interfaces
component lines is a TAB (^I) character, NOT spaces.  SYBASE software will not
find any entries which are prefixed by any other character.

The next time SQL Server boots, it will spawn a NETWORK HANDLER process for
each "master" line in the entry corresponding to the server's DSLISTEN value.
Connections made on each interface will be handled equally (peers).


Setting up interfaces for Client Connections

The client side of this is a bit less straightforward.  You must add
additional file entries to interfaces for each interface that SQL
Server will be listening on.  This is because when scanning the
interfaces file for a hostname and port number to open a connection on
the network, SYBASE client software uses the first "query" line it
finds in the corresponding DSQUERY server entry in the file.  Since
only one hostname may be listed on a line, additional file entries are
necessary to get the desired "query" lines at the top of the list.
Think of the additional file entries as aliases of the original entry,
giving you access to the same server, but simply through another
communications channel.  Multiple query lines in one interfaces entry
are allowed, but this arrangement is only useful for setting up backup
network facilities to the primary network port (discussed later in this
article).  The sequential nature of the file scanning still takes
priority, and virtually no client connections will make it past the
first "query" entry.

Unfortunately, this results in a different DSQUERY for each interface.
This reality is not so much a hardship, as separate networks and differing
protocols often force client configuration to be separate anyway, so the
differing DSQUERY values can in fact easily be different from the primary,
still leading the clients to the same SQL Server, which is the ultimate win.
There is also an alternative method for configuring the interfaces file, if
your SYBASE software installations are discrete on each network you are
interfacing on your server: you can encode the varying "query" hostnames
in each of the interfaces files.  See the section, "Alternate Implementation
Choice," later in this chapter, for complete information.

Steps for Setting up Client Interfaces Entries

1. To formulate a name for each network's DSQUERY connection to your SQL Server,
concatenate the interface's hostname with the original DSQUERY name.
You may, of course, use any name you wish, but this makes the
association of these names clearer.  Use a text editor to insert this
name at the beginning of a new line in your interfaces file.

2.  Copy the corresponding "master" line (for the same network) from the
existing entry for the SQL Server, and insert it under the server entry
name, changing the "master" word to "query".  To assure that the hostname and
port number are the same as the listener, don't change anything else on the
line.  Don't copy any other lines (such as "console"), since having many of
these will serve only to confuse the server at startup time.

** NOTE:  Be certain that the leading whitespace tabulation on all server
component lines is a TAB (^I) character, NOT spaces.  SYBASE software will not
find any entries which are prefixed by any other character.

3. Repeat the above steps for each network interface, forming a new entry for
the clients on each one.  Clients on each network must use the DSQUERY
corresponding to the network the client is on.

The following is an example interfaces file for a SQL Server with two network
interfaces, each connected to a different network.  The SQL Server host
machine is known as 'sunserv_corpnet' on the 'corporate' network, and
'sunserv_engnet' on the 'engineering' network.  On the corporate network,
clients use the DSQUERY "PRODUCTION_CORPNET" to connect to the interface on
this network.  Likewise, on the engineering network, clients use the DSQUERY
"PRODUCTION_ENGNET".

# master entry for SQL Server.  doubles as client entry for corporate network.
PRODUCTION_CORPNET
        query tcp sun-ether sunserv_corpnet 1040
        master tcp sun-ether sunserv_corpnet 1040
        master tcp sun-ether sunserv_engnet 1040
        console tcp sun-ether sunserv_corpnet 1041
# client entry for PRODUCTION server, engineering network.
PRODUCTION_ENGNET
        query tcp sun-ether sunserv_engnet 1040


Alternate Implementation Choice: Use of a Single, Network-Independent DSQUERY.

If uniform client DSQUERY naming is important, one can mask the necessary
difference in the network addressing of the clients in the interfaces file.
This may be done by installing separate $SYBASE installation directories on
client fileservers on each network, and making the necessary changes to the
interfaces file on each installation to allow it to connect to the correct
network address for that network.  Instead of altering the $DSQUERY name the
clients use, you maintain one DSQUERY name on all clients on all networks, and
simply alter each network's interfaces file accordingly.

This method assumes you have complete control over what $SYBASE installation
clients see on each network, that the interfaces file (at the very least) is
NOT shared or copied among SYBASE installations on the different networks.
If a given network's SYBASE software installation(s) which include an
interfaces entry for the SQL Server in question may be seen on any other
network (via NFS, a multi-network VAX cluster, or DFS file service),
then you run the risk of a client attempting a connection using the
wrong network address.  Certainty regarding the use and visibility of
your SYBASE installations is required to be sure clients will always attempt
the proper connection from their respective network.

This method is also a bit more cryptic in general, and has the potential for
confusing the uninformed.  If your site endeavours to keep a single,
universal interfaces file on all SYBASE hosts, this practice of having a server
entry vary internally with the network it serves will likely be erased by an
interfaces file distribution or simple unwitting copy.  Take steps to guard
against these possibilities should you choose this configuration.

Thus, the preceding interfaces file example adapted for this "single DSQUERY"
method would look like this:

interfaces file on "corporate" network:

# PRODUCTION server via corporate network.
PRODUCTION
        query tcp sun-ether sunserv_corpnet 1040
        master tcp sun-ether sunserv_corpnet 1040
        master tcp sun-ether sunserv_engnet 1040
        console tcp sun-ether sunserv_corpnet 1041


interfaces file on "engineering" network:
# PRODUCTION server via engineering network
PRODUCTION
        query tcp sun-ether sunserv_engnet 1040
        master tcp sun-ether sunserv_corpnet 1040
        master tcp sun-ether sunserv_engnet 1040
        console tcp sun-ether sunserv_engnet 1041

Note that the server reverts to the simple DSQUERY name in common use.  The
difference here is of course the "query" host, which is different in the two
files.

Note also that the full server entry is present in both files.  This is allowed
because only SQL Server will use the "master" and "console" lines.  Assuming
the server host machine can see both networks (both hostnames are
interchangeable), it doesn't matter which interfaces file is used for SQL Server
startup.  The only thing that does change between the files (that makes a
difference to SQL Server) is the "console" line.  The choice of interfaces file
determines which network will host interactions between SQL Server and the
console utility.  Since console is always used on the same machine as the
SQL Server, it too has access to both networks, and will function fine on
either network.


Sequential Query Port Backup
One can in fact have multiple "query" lines in a server entry in the interfaces
file.  Clients looking for a hostname and a port number for a connection to
a SYBASE server will try the port on each "query" line in order, until a
connection is established.  The vast majority of the time, the first "query"
line affords a connection, since nearly only a network overload or general
failure, or a network interface
failure would disable one network port on a server while preserving another.
The most common reason for a denied connection is the SYBASE server being
unavailable (shut down/not running).
However, if your environment includes volatile network interfaces,
suffers from poor network availability, or has some backup mechanism
that would be gainful to utilize, you may wish to combine the first
example set of server entries into one exhaustive entry used by both
clients and server.

Such a configuration, following our model, would look like this:

PRODUCTION
        query tcp sun-ether sunserv_corpnet 1040
        query tcp sun-ether sunserv_uwave_backup 1040
        master tcp sun-ether sunserv_corpnet 1040
        master tcp sun-ether sunserv_uwave_backup 1040
        console tcp sun-ether sunserv_corpnet 1041

This arrangement sets up two NETWORK HANDLERs on the SQL Server, as expected.
But since there are two "query" lines in this entry, the second entry for the
microwave backup network will only be used in the event that a
connection to the port on the preceding corporate network is
unsuccessful.  A connection on this secondary port will only take place
if the corporate network is disabled in some way, or the corporate
network interface on the host machine fails or is shut down.  The point
is that the failure would have to be network-related.  If there were a
general system problem on the host computer, the SQL Server itself may
be disabled, causing BOTH network interfaces to be unavailable.

If your site has backup network facilities that allow you another pathway to
your SYBASE server host when the primary interface is down, setting up
multiple "query" lines in the server's interfaces file entry will allow
your SYBASE server to take advantage of these facilities automatically, without
any reconfiguration.

Companion Servers on VMS operate in the exact fashion as just described.  If
the primary SQL Server fails on one VMS cluster node, the Companion Server on
another node takes over, accepting connections on its port (on another host
machine).  For clients to achieve their connection to the Companion Server,
they must be set up similarly to the preceding example, to take connections
on the secondary "query" port after a connection to the primary fails or times
out.

-- 
---------------------------------------------------------------------
| Bret Halford                     bret@sybase.com               ___|
| Sybase Technical Support                                    __|
| 6475 Christie Avenue                                       |__
| Emeryville, CA 94608 USA                                      |___
| fax: (510)-922-3911              exec sp_realitycheck()           |
#####################################################################