Home

	Expand Search

System Administration Guide Supplement for Novell NetWare

Chapter 3: The Interfaces File

Chapter 3

The Interfaces File

In order for SYBASE products to interact with one another, each product needs to know where the others reside on the network. This information is generally stored in the interfaces file. The interfaces file is like an address book. It lists the name and address of every SQL Server to which a user might connect. The interfaces file is automatically created, verified, or appended during installation. It is possible to edit it by hand, but you should do so only if you are an experienced user and only after making a copy of it. Under NetWare, the interfaces file is named interfac and is stored in the SYBASE release directory.

This chapter explains the interfaces file and provides instructions for altering the file to accommodate multiple SQL Servers. This chapter also explains how to use bindery services to connect clients with SQL Servers. Topics covered include:

• How SYBASE clients communicate with SQL Server

• How SYBASE software uses the interfaces file

• How the interfaces file is formatted and what each part of an interfaces file entry does

• How to make a "master" interfaces file

• How to bypass the interfaces file using the NetWare Service Advertising Protocol (SAP)

  Note: This chapter uses the term "client" to refer to a NetWare client machine (a PC running a client application, such as isql , under NetWare version 3.12 or 4.01). SYBASE clients on other platforms, such as DOS and Windows, may use different methods to locate and access SQL Servers. Refer to the documentation that came with your client software for more information.

How Clients Connect to SQL Server

When NetWare client (front-end) software needs to communicate with SQL Server, it performs the following steps:

1. It determines the name of the SQL Server, usually by finding the value of the sys:system\sybenv.dat value DSQUERY or by using a command-line option.

2. It looks in the local interfaces file, interfac (provided it exists), for an entry whose name matches the name of the server.

3. If the interfaces file entry exists, the client uses the provided network address to attempt a connection to the server.

4. If no interfaces file entry exists, the client can use SAP, as described below. See "How Clients Use Service Advertising Protocol (SAP)".

The connection can be completed only if the named SQL Server listens at the same address that is defined in the client's interfaces file. See "How SQL Server Listens for Client Connections" for more information.

Note: SYBASE clients on other platforms may perform the address dictionary function using methods other than the interfaces file. See your client documentation for more information.

How Clients Use Service Advertising Protocol (SAP)

Clients attempt to locate the specified server using SAP, provided that the following conditions are met:

• An interfaces file entry for the specified server is not located. (This may be because the interfaces file does not contain an entry for the server or because the interfaces file does not exist.)

• The sys:system\sybenv.dat value USE_DEFAULT_SPX is set to TRUE.

For further information on setting values in the sybenv.dat file, see "Using sybenv.dat Variables".

How SQL Server Listens for Client Connections

Just as client applications use the interfaces file to locate servers, SQL Server uses the interfaces file to determine the address at which it should listen for clients.

When you start SQL Server, it performs the following steps:

1. It determines the server name it should use, usually by finding the value of the sys:system\sybenv.dat value DSLISTEN or by using a command-line option.

2. It looks in the local interfaces file, interfac (provided it exists), for an entry whose name matches the specified server name.

3. If the interfaces file entry exists, SQL Server listens for client connections at the provided network address. SQL Server also advertises that address via SAP.

4. If no interfaces file entry exists, SQL Server dynamically generates and allocates a network address using SAP, provided that the following conditions are met:
   • An interfaces file entry for the specified server is not located. (This may be either because the interfaces file does not contain an entry for the specified server or because the interfaces file does not exist.)

   • The sys:system\sybenv.dat value USE_DEFAULT_SPX is set to TRUE.

For further information on setting sy benv.dat values, see "Using sybenv.dat Variables".

Interfaces File Format

The interfaces file consists of a series of entries, usually one per server. The entries are separated by blank lines.

During the installation of a Sybase product, you can specify one or more entries in the interfaces file for servers to which clients will connect. The installation program, sybinit , creates these entries in the proper format. Examine these entries for examples of the proper syntax of the interfaces file entry elements described below. Since the installation process creates interfaces file entries for you, you may not need to edit the interfaces file at all. The following discussion is for your information, in case you do need to modify the file.

Each interfaces file entry has the following format:

 #   put comments here  <newline>  
 SERVERNAME[<tab>  retry_attempts  <tab>  delay_interval  ]<newline> 
 <tab>  service_name     network protocol device address  <newline> 
 ... 
 <blank lines between entries for different servers> 

Warning! The first word of each line must be preceded by a tab or a space.

The following sections describe each element in an interfaces file entry:

Comment Line

The comment line that precedes each interfaces file entry is automatically generated by sybinit .

SERVERNAME

The first line of an interfaces entry contains the name of the server, the number of retry attempts, and the delay interval.

Server names can be no more than 11 characters long. The initial character of a server name should be a letter (ASCII a-z, A-Z). The characters that follow may be letters, numbers, or the underscore character (_).

retry_attempts and delay_interval

retry_attempts and delay_interval are values that determine how many times, and how often a client tries to connect to a server after an initial failure to connect.

Clients try to connect to a server using each QUERY line in the interfaces file entry. If the client has tried unsuccessfully to establish a connection to the server, it checks the retry_attempts and delay_interval values in the interfaces file. The retry_attempts value specifies how many times the client should attempt a connection after an initial failure to connect. The delay_interval specifies how many seconds to wait between retries.

service_name

service_name describes the type of service the entry defines. There are two possible values for service_name: QUERY and MASTER:

• A line beginning with "query" represents the service that a client, such as Data Workbench®, uses to log into SQL Server. The QUERY entry in an interfaces file corresponds to the DSQUERY value described earlier.

• A line beginning with "master" defines the service SQL Server uses to listen to login requests from clients. This line is not necessary in an interfaces file for a machine running clients only.

sybinit does not distinguish between client and server interfaces file entries. As a result, both QUERY and MASTER lines are always generated.

network

network is the name of the network interface. For NetWare, the only network interface is TLI (Transport Layer Interface), represented by the letters "tli" in the interfaces file entry.

protocol

protocol is the name of the network protocol. When creating server entries at installation time, sybinit prompts you for the name of the network protocol. The value of protocol must be either "tcp" or "spx." If no protocol is specified, "tcp" is used as the default value.

device

device is the device name supplied for the network, and can be either /dev/tcp or /dev/nspx.

address

address is a composite entry whose format depends on which protocol is used by the server. sybinit automatically creates the correct address format by examining entries in the NetWare bindery.

TCP Address Format

For TCP, address is represented as

 0200ppppaaaaaaaa0000000000000000 

where:

0200 - represents the AF_INET packet type. This value must remain constant.

pppp - represents the port number in hexadecimal notation, and must be between xFF and xFFFF. The port number is determined when the server is installed. Port numbers for the MASTER and QUERY entries are the same, because the server listens for login requests on the same port that clients use to request logins.

aaaaaaaa - represents the network node address, or internet address , of the machine on which the server runs. If the machine's internet address is encoded in sys:etc\hosts , then sybinit uses that information to determine the network node address.

0000000000000000 - represents a TCP-specific initialization string used to initialize an internal data structure. This value must remain constant.

SPX Address Format

For SPX, address is represented as

 nnnnnnnn000000000001pppppp 

where:

nnnnnnnn - represents the internal IPX network number (in hexadecimal format) for the NetWare server on which the server runs. Every NetWare server is assigned a unique internal network number when it is installed. You can display the network number by using the slist utility from a DOS client machine. See your Novell documentation for more information on slist .

000000000001 - represents the virtual node address of the NetWare server on which the server runs. This value must remain constant.

Note: Beginning with NetWare version 3.0, the internal network number is used as a unique identifier to address the NetWare server. The node address value should remain set to the value shown above, as SQL Server release 10.0 does not support versions of NetWare earlier than 3.12.

pppppp - represents the socket number in hexadecimal notation. Novell has reserved 10 socket numbers for SQL Server use. They are: 0x83bd(default), 0x83be, 0x83da, 0x83db, 0x83dc, 0x83dd, 0x83de, 0x83df, 0x83e0, and 0x83e1. Socket numbers for the MASTERand QUERY entries are the same, because the server listens for login requests on the same socket that clients use to request logins.

An Interfaces File Example

Figure 3-1 illustrates an environment with three servers, each on a different machine. The interfaces file shown is on "harpo." It allows a client on "harpo" to connect with any of the three servers.

The interfaces file was created by combining the entries originally created for each of the servers when they were installed on their own machines. The client ignores the MASTER line and uses only the QUERY line.

Entries for server connections using both TCP and SPX protocols are illustrated. The servers TEST and PRACTICE (running on the machines "gummo" and "chico", respectively) connect using TCP; the server PRODUCTION (running on the machine "groucho") connects using SPX.

Figure 3-1: An interfaces file for three servers

A client program on "harpo" can access any server on the network.
If the program itself does not specify the server name, then the program's user can do so by changing the value of DSQUERY.

For example, after a user has set the value of DSQUERY in sybenv.dat as follows:

 DSQUERY = PRACTICE 

the user would connect to the PRACTICE server on "chico." Note that the server name is case-sensitive.

Constructing a Master Interfaces File

A master interfaces file contains entries for all SYBASE servers on the network; it can be used with every server and every user connected to the network. Distributing copies of a master interfaces file is the easiest way to ensure that all Sybase products on the network can interact with each other. To maintain consistency in the interfaces files on a network, make all changes to one version of the file. Then copy the updated file to the rest of the machines on the network.

The easiest way to construct a master interfaces file is by using sybinit to add the necessary entries. This ensures that all address entries are of the proper format.

Guidelines for Creating an Interfaces File Manually

If your system already contains several interfaces files, you may find it easier to use your operating system editor to merge the files into a master interfaces file. When merging interfaces files, however, be aware of the following:

• Each entry in the interfaces file must have a unique name. If, after merging several interfaces files, you find you have duplicate entries for any server name, be sure to rename the entries so that their names are unique.

• The network addresses in each entry must be in the correct format for the client machine and network. If the client machine's addressing method is different from that of the server machine, do not merge the entry from the server machine into the client's interfaces file. Instead, use the sybinit utility on the client machine to append a new entry for the server.

  Warning! Do not attempt to edit individual interfaces file entries manually. Always use sybinit to create or modify entries.

Using SAP to Bypass the Interfaces File

As mentioned earlier in this chapter, you can use SAP to dynamically allocate an SPX network address for SQL Server. Using SAP in this manner bypasses the need to maintain an interfaces file. However, using SAP exclusively does not guarantee that SQL Server names will be unique on the network.

If you want to use SAP in place of an interfaces file, you must ensure that neither the SQL Server machine nor the client machines accessing SQL Server reference an interfaces file. The sections that follow explain the required steps.

Starting SQL Server to Use SAP

To ensure that SQL Server creates a dynamic network address using SAP, follow these steps:

1. Use sybinit to set the USE_DEFAULT_SPX sybenv.dat value to TRUE. Refer to "Using sybenv.dat Variables" for instructions.

2. If you use a startserver file to start your SQL Server, edit that file to remove the -i option. The -i option designates the path to the SQL Server interfaces file.

3. Edit the sys:system\sybenv.dat file to comment out the SYBASE_INTERFAC value, if one exists. The commented line should look like this:

    #SYBASE_INTERFAC=sys:sybase\interfac 

4. Start SQL Server as you normally would.

Connecting to SQL Server Using SAP

To ensure that you can connect to a SQL Server that is advertising a dynamic network address, follow these steps:

1. On the NetWare file server machine that acts as the client, use sybinit to set the USE_DEFAULT_SPX sybenv.dat value to TRUE. Refer to "Using sybenv.dat Variables" for instructions.

2. Edit the client's sybenv.dat file to comment out the SYBASE_INTERFAC value, if one exists. The commented line should look like this:

    #SYBASE_INTERFAC=sys:sybase\interfac 

3. When starting the client tool, do not specify the name of an interface file at the command line. For example, if you are using isql , do not use the -l option.

   Be sure to use the same server name that was used to start SQL Server. The server name may be specified either at the command line or with the DSQUERY value in sybenv.dat.

What's Next?

Chapter 4 contains information about routine tasks, maintenance, and troubleshooting for SQL Server.