System Administration Guide Supplement for SunOS Release 4.x (BSD)

Home

System Administration Guide Supplement for SunOS Release 4.x (BSD)

Chapter 2: The Interfaces File

Chapter 2

The Interfaces File

SYBASE SQL Server must be able to communicate with a variety of software products on the same network. This communication occurs through the interfaces file, usually named $SYBASE/interfaces . The interfaces file is like an address book. This file contains an entry for each SQL Server or Backup Server to which a client might connect.

Note: This chapter discusses interfaces file entries for and client communication with SQL Servers. Backup Servers also have interfaces file entries and can communicate with clients. The material in this chapter also applies to Backup Servers, although it does not always refer to them.

You can use the sybinit utility to create, verify or modify interfaces file entries for SQL Server or Backup Server. This chapter provides instructions for using sybinit to create an interfaces file entry.

You can also edit the interfaces file manually, but do so only if you are an experienced user, and always make a copy of the file first.

Topics covered in this chapter include:

Communication between SYBASE clients and SQL Server
Formatting the interfaces file entries
Functions of different parts of an interfaces file entry
Using sybinit to create interfaces file entries
Altering the interfaces file to accommodate multiple SQL Server installations
Note: The term $SYBASE refers to the location of the SYBASE home directory.

How SQL Server Communicates with Clients

When client (front-end) software, or a server acting as a client by executing remote procedure calls (RPCs), needs to communicate with SQL Server, it performs the following steps:

It determines the name of the SQL Server, usually from the value of the environment variable DSQUERY or from the value given through a command-line option.
In the interfaces file, it looks for an entry that has a SQL Server name matching the value of DSQUERY or of the command line option.
It connects to the SQL Server running on the combination of the machine and port listed for that entry. If the client is unable to connect the first time, it makes additional attempts according to the delay and retry numbers in the interfaces file. (If no matching entry is found, an error message is written to the client's standard error file.)

The client can connect to any server correctly listed in the interfaces file, as long as the matching server name is supplied via DSQUERY or a command line option. If no server name is supplied, the software looks for an interfaces file entry with the default server name SYBASE. You can use this feature if you always connect to a single SQL Server named SYBASE.

If you plan to use more than one SQL Server referenced from the same interfaces file, choose a different name for each SQL Server. For clarity, you should choose different names for each SQL Server connected to your network. You may want to choose SQL Server names that describe your applications in order to help you remember them.

Warning! Do not use SQL Server names that are the same as other computer names on your network. Using the same name for SQL Server and your computer can cause serious problems on some networks.

Interfaces File Format

When you successfully install SQL Server, sybinit creates an entry for it in the interfaces file. Examine this entry for an example of the proper syntax of the interfaces file entry elements described in the following sections.

Each SQL Server that you plan to use should have only one entry, although there may be multiple lines in the entry. Each interfaces file entry has the following format:

 # put comments here<newline> 
 SERVERNAME<tab>retry_attemps<tab>delay_interval<newline> 
 <tab>service_type protocol network machine port<newline> 
 <blank lines or comments between entries for different SQL Servers>

Warning! Each entry line that follows the " SERVERNAME " line must begin with a space or a <tab> character. The entry does not work without a space or a <tab> at the beginning of each line. Use a single space between each element on an entry line.

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

SERVERNAME

SERVERNAME is the name of the SQL Server or Backup Server. Server names can be no more than 31 characters long. The initial character of a server name must be a letter (ASCII a-z, A-Z). The characters that follow must be letters, numbers, or the underscore ( _ ).

retry_attempts and delay_interval

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

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

When you install SQL Server, sybinit prompts you for the delay interval and the number of retry attempts for that SQL Server. You can use sybinit to change these values at a later date. You can also manually edit your interfaces file using an operating system editor, if you are an expert user. If you manually edit the interfaces file, be sure to insert tabs or spaces between the values.

service_type

service_type describes the type of service the entry defines. The values associated with service_type are: "query", "master", "console", "commit" and "debug".

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 environment variable described earlier.
A line beginning with ''master'' defines the service SQL Server uses to listen to login requests from clients. This entry corresponds to the value of the DSLISTEN environment variable. This line is not necessary in an interfaces file for a machine running clients only.
A line beginning with the word "debug" represents a connection for use by Sybase Technical Support.

protocol

protocol is the name of the network protocol.

network

network is the name of the network. Although SQL Server does not currently use this column, sybinit enters a network name as a place holder when creating interfaces file entries. For SunOS 4.x, sybinit enters ''ether" as the network name.

machine

machine is the network name of the machine on which SQL Server is running. You can use either the host name or internet address as the machine name.

To determine the host name of a machine, log in on that machine and use the following command:

 % /bin/hostname

The first 32 bytes of the machine name must be unique on the network; SYBASE software reads a maximum of 32 bytes for a machine name in an interfaces file entry.

port

port is a port number between 1025 and 65535. The combination of a machine name and port number uniquely identifies a SQL Server.

The port number you select for your SQL Server must not be used for any other purpose on the machine where SQL Server is located. More than one SQL Server can have the same port number if each server is on a different machine. Check the /etc/services file on each machine on the network to see a list of port numbers in use.

You do not need this entry for the operating system to function properly, but the presence of the port number will alert other users that this port number is in use. Following is an example for a SQL Server named TEST:

 # 
 # Sybase specific services 
 # 
 TEST query 4067/tcp

Interfaces File Example

The following figure illustrates an environment with three SQL Servers, each on a different machine. The interfaces file shown is a "master" interfaces file that works for each server and the client on the four machines shown in Figure 2-1.

Figure 2-1: An Interfaces File for Three SQL Servers

Network and machine names for three SQL Servers

SQL Server Name Network Machine Name

TEST TCP/IP gummo

PRACTICE TCP/IP chico

PRODUCTION TCP/IP groucho

**Network and machine names for three SQL Servers**
SQL Server Name	Network	Machine Name
TEST	TCP/IP	gummo
PRACTICE	TCP/IP	chico
PRODUCTION	TCP/IP	groucho

The user on a client can access any SQL Server on the network by specifying the name of the server. The user can change the value of the DSQUERY environment variable with the appropriate command for the shell in use:

For C shell:

 setenv DSQUERY   server_name

For Bourne shell:

 DSQUERY="  server_name  "; export DSQUERY

After the user sets DSQUERY, any client that the user runs connects to the SQL Server with the name specified as the value of DSQUERY.

Using sybinit to Create Interfaces File Entries

You can use the sybinit utility to create or edit interfaces file entries. This section provides instructions for using sybinit to create a new interfaces file entry. For more information on sybinit , see the SQL Server Installation Guide .

If you have more than one SQL Server installation, see "Creating One Interfaces File for Multiple Installations".

Use the following instructions to run sybinit on each of the machines where you plan to run SYBASE clients.

Starting sybinit

Start sybinit from the shell prompt by typing:
```
 $SYBASE/install/sybinit 
```
At the main menu, select "Edit / View Interfaces File". sybinit displays the "Interfaces File Top Screen."
Select "Add a new entry." sybinit displays the "Create New Interfaces File Entry" menu.
Select "Server name". At the prompt, enter the name of the server for which you want to create an entry.

Note: You can enter the name of a Backup Server if you want to create an interfaces file entry for a Backup Server.

When sybinit displays the correct server name at the "Create New Interfaces File Entry" menu, press Ctrl-a to accept it. sybinit displays the "Server Interfaces File Entry Screen":

 SERVER INTERFACES FILE ENTRY SCREEN

 Server name: SYBASE

 1. Retry Count: 0 
 2. Retry Delay: 0

 3. Add a new listener service

 Ctrl-a Accept and Continue, Ctrl-x Exit Screen, ? Help.

 Enter the number of your choice and press return:

Entering Connection Information (Optional)

Select "Retry Count". At the prompt, enter the retry count value. sybinit returns to the "Server Interfaces File Entry Screen."
Select"Retry Delay". At the prompt, enter the retry delay value. sybinit returns to the "Server Interfaces File Entry Screen."
The "Server Interfaces File Entry Screen" now displays the retry count and delay values you entered (or 0 if you did not enter any values). You can change either of these values by reselecting the appropriate menu item and entering a new value at the prompt.

Adding a TCP Entry

Select "Add a new listener service". sybinit moves to the "Edit TCP Service" menu:

 EDIT TCP SERVICE

 1. Hostname/Address: harpo 
 2. Port: 
 3. Name Alias:

 4. Delete this service from the interfaces entry

sybinit displays the current machine's host name after the "Hostname / Address" item. To change the host name, select "Hostname/Address". At the prompt, enter the new host name. sybinit returns to the "Edit TCP Service" menu and displays the new host name.
Select "Port" and enter the 4- or 5-digit port number at the prompt. sybinit returns to the "Edit TCP Service" menu and displays the port number you entered.
To enter an optional alias for this entry, select "Name Alias" and enter an alias. sybinit returns to the "Edit TCP Service" menu and displays the alias.
When you specify a name alias, sybinit places a duplicate query service identified with the new alias into the interfaces file. This duplication enables you to use either the actual server name or the alias to connect to a server.

Accepting the New Entry

Verify that all entries in the "Edit TCP Service" menu are correct. If necessary, reselect an item to correct the entry.
Press Ctrl-a to accept the displayed information. sybinit asks you if the information is correct, displaying the default "n":
```
 Is this information correct? n 
```
Type "y" to proceed with the installation. sybinit returns to the "Server Interfaces File Entry Screen."
```
 SERVER INTERFACES FILE ENTRY SCREEN  
```
```
    Server name: SYBASE  
```
```
 1. Retry Count: 5 
 2. Retry Delay: 5 
```
```
 3. Add a new listener service  
```
```
 Modify or delete a service  
```
```
 Listener services available:  
```
```
    Protocol  Address    Port    Name Alias   Type  
 4. tcp       harpo      2500    HQ  
```
Notice that sybinit displays the listener information you just entered under "Listener services available." You can modify or delete this information at any time by selecting the item number of the listener service (item 4 in the example above).
You can also add listener entries for the server by selecting "Add a new listener service" once again. This ability is especially useful for SQL Servers that operate on networks with multiple protocols.
Press Ctrl-a to accept the new interfaces file entry. sybinit prompts you to write the changes to the file:
```
 Write the changes to the interfaces file now? n 
```
Type "y" to write the information to the interfaces file.

Creating One Interfaces File for Multiple Installations

Distributing copies of one interfaces file with entries for all SQL Servers is the easiest way to ensure that all SYBASE products on a network can communicate. 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.

For example, the interfaces file in Figure 2-1: An Interfaces File for Three SQL Servers was created by copying the "groucho" version and "chico" version of the interfaces file to "gummo", and then using a text editor to merge the three files. The file containing all three definitions was then copied to "groucho" and "chico".

Using sybinit to Create a Master Interfaces File

To maintain one consistent interfaces file (a "master" file) in an environment with multiple SQL Server installations, follow these steps:

Select the interfaces file that contains the most complete, up-to-date information.
Begin a sybinit session in your latest SYBASE installation to edit this interfaces file. If the file is not in the same installation from which you are running sybinit , change the release directory item in the main menu to the file's location.
Follow the instructions for Using sybinit to Create Interfaces File Entries to create entries for any SQL Servers and Backup Servers from other installations that are not listed in the interfaces file.
Copy this interfaces file to all appropriate SYBASE directory trees.

Creating a Master Interfaces File Manually

If you are already familiar with SYBASE software, you may find it is faster to create an interfaces file by using a text editor such as vi . Always make a copy of the original, unedited interfaces files first, and be extremely careful when editing this file. Do so only if you are very familiar with the correct format.

Before you create a master interfaces file manually, be sure that the values you use for the different elements in the interfaces file on each machine are correct for that machine. You can check the new values you enter by comparing them with values for existing entries.
Create a complete interfaces file by copying the contents of all the interfaces files from all machines with SQL Server installations into one file.
Use a text editor like vi to edit this merged file so that there is one entry for each SQL Server and each Backup Server. Do not try to use an application program to edit the interfaces file; you must use a text editor.
Copy this interfaces file to all appropriate SYBASE directory trees.

Warning! If you manually edit an interfaces file, be sure that for each entry, the line following the first line begins with a space or a <tab> character.

What's Next?

Chapter 3 discusses selecting and initializing database devices.


	Expand Search