Home

	Expand Search

System Administration Guide Supplement for OS/2

Chapter 3: Network Configuration Files

Chapter 3

Network Configuration Files

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 stored in the network configuration files, sql.ini and libtcl.cfg . Together, the network configuration files are like an address book. They list the name and address of every SQL Server to which a user might connect. Network configuration files are automatically created, verified, and appended when you install SQL Server.

This chapter explains the sql.ini and libtcl.cfg files and provides instructions for altering the files to accommodate multiple SQL Servers. Topics covered include:

• How SQL Server and clients communicate with each other

• How SYBASE software uses the network configuration files

• How to edit configuration files using the sqledit utility

How Clients Connect to SQL Server

When OS/2 client (front-end) software needs to connect to a SQL Server, it performs the following steps:

1. It determines the name of the SQL Server, usually by finding the value of the DSQUERY environment variable or by using a commandline option.

2. It looks in the sql.ini file for an entry whose name matches the name of the SQL Server. If the entry is not found, the connection fails.

3. It looks in the libtcl.cfg file for an entry that matches the Net-Libraryä driver name associated with the SQL Server entry in the sql.ini file. If no entry is found, the connection fails.

4. It loads the specified Net-Library determined by the query field of the server entry.

5. It uses the network connection information provided by the sql.ini file to connect to the SQL Server.

Figure 3-1 summarizes the client connection process.

Figure 3-1: Connecting to a SQL Server

How SQL Server Listens for Client Connections

SQL Server uses the sql.ini file to determine the address at which it should listen for clients. When you start a SQL Server, it performs the following steps:

1. It determines the server name it should use, usually by finding the value of the DSLISTEN environment variable or by using a command-line option.

2. It looks for the sql.ini file it will use. It will use the sql.ini file specified by the command line option -i . If that option is not given, it will try to use %SYBASE%\INI \ sql.ini . If there is no such file, it will try to use C:\sql10\INI\sql.ini .

3. It looks in the sql.ini file for an entry whose name matches the specified server name.

4. It looks in the libtcl.cfg file for an entry that matches the Net-Library driver name associated with the SQL Server entry in the sql.ini file.

5. It loads the specified Net-Library determined by the master field of the server entry.

6. It uses the information from the MASTER entry in the sql.ini file to determine the address at which it should listen for client connection requests.

sql.ini File Components

The sql.ini configuration file contains information about SQL Server's connections. Client applications read the sql.ini file to determine how to connect to the specified SQL Server. SQL Server reads sql.ini to determine the address at which it will listen for client connections.

Figure 3-2 shows the basic components of a sql.ini entry via the sqledit utility. The sections below describe each component.

Figure 3-2: Components of the sql.ini file

Server Name

The SQL Server name is the name of the SQL Server to which clients will connect. The first 8 characters of the name uniquely identify the SQL Server. Although the name within Sybase products is case-sensitive, OS/2 is case-insensitive. If you plan to use the run_server file from OS/2, which is composed of the SQL Server name , OS/2 will interpret lower and uppercase as the same. Therefore, Sybase recommends that Server names be case-sensitive and unique for the first 8 characters.

Service Type

The service type describes the type of service the entry defines. There are two possible service types : QUERY and MASTER:

• QUERY represents the service that a client application, such as isql , uses to log into SQL Server. A QUERY entry is required if you plan to access a SQL Server from your local machine. (Generally speaking, a QUERY entry is always required.)

• MASTER defines the service SQL Server uses to listen to login requests from clients. A MASTER entry is required if you plan to start a SQL Server on your local machine. It is not required in a sql.ini file for a machine that is running clients only.

Network Driver

The network driver specifies the name of the Net-Library driver to use for the connection. The driver name must correspond to a valid entry in the libtcl.cfg file. See "libtcl.cfg File Components" for information on libtcl.cfg entries.

Connection Information

The connection information defines the complete network address where SQL Server listens for client connections. The format of the connection information depends on the network driver SQL Server uses. The following Net-Driver libraries are supported:

Table 3-1: Net-Library DLLs

DLL	Library Name
Named Pipes	nlos2nmp.dll
IBM TCP	nlibmtcp.dll
Novell IPX/SPX	nlnovspx.dll

Named Pipes Format

For the Named Pipes Driver, the connection information consists of the unique pipe name for the SQL Server. Valid pipe names begin with \pipe and follow the same naming conventions as MS-DOS file names. The default pipe name for SQL Server is \pipe\sql\query .

To avoid conflicts, always use unique pipe names of the same "length" for all Sybase products on your PC. For example, you might select \pipe\sql\query for SQL Server and \pipe\backup\query for Backup Server. Do not use pipe names such as \pipe\sql and \pipe\sql\query as these names would not necessarily be unique on the system.

If you are accessing a Server on a remote, networked machine (not the local machine), preface the pipe name for the QUERY service with \\machine_name , where machine_name is the name of the PC running the server.

Warning! Do not preface the pipe name with \\machine_name when entering connection information for the MASTER service. The master field is used by the server, which boots on a local machine. If you include the \\machine_name prefix, you cannot boot SQL Server.

See "Server Connection Example" below for an example of valid pipe names.

TCP/IP Protocol

You can select TCP/IP as your connection protocol. Select a port number between 1024 and 65535, or use the default number 5000. Before choosing a port number, make sure that it is not 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 SQL Server is on a different machine.

Novell NetWare SPX/IPX Protocol

Three arrangements are available for setting up your SPX/IPX protocol:

1. Net number, node number, socket number.

   Net number is Netware specific, node number is the machine node number, and the socket number is in hexadecimal format. For example: 16, 1, 83BD.

2. Machine name, socket name (not available for query entry).

   Machine name should be your local machine name; socket number is in hexadecimal. For example: bobcat, 83BD.

3. Machine name

   Use the machine name only. For example: bobcat.

   Note: Master entries can accept all three methods; query entries can accept only methods 1 and 3.

libtcl.cfg File Components

The libtcl.cfg configuration file contains information about available Net-Library drivers. It specifies which drivers have been installed on your system.

The libtcl.cfg file lists each available driver by its DLL name and driver description. For example:

 NLOS2NMP=Named Pipes Drivers 

When viewed from the sqledit utility, only the installed driver descriptions are displayed, as shown in Figure 3-2: Components of the sql.ini file on page 3-3.

Server Connection Example

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

Figure 3-3: Three servers

A client program on "harpo" can access any SQL Server on any network. If the program itself does not specify the Server name, then the program's user can do so by changing the value of the DSQUERY environment variable. For example, after a user issues the operating system command:

 SET DSQUERY=CONNECT50 

the client would connect to the machine named "gummo" using Named Pipes.

Note: In the example in Figure 3-3: Three servers , "harpo" is assumed to have connections to two different networks. "harpo" would need a Net-Library driver installed for each network. Also, a client application on "harpo" would ignore the MASTER service entries, as they are used only by SQL Server.

Constructing a Master sql.ini File

A master sql.ini file contains entries for all SQL Servers on the network; it can be used with every SQL Server and every user connected to the network (as shown in Figure 3-1). Distributing copies of a master sql.ini file is the easiest way to ensure that all of the SYBASE products on the network can communicate with each other. To maintain consistency in the sql.ini files on a network, make all changes to one version of the file, and then copy the updated file to the rest of the machines on the network. You can also maintain consistency by having all the machines using the same sql.ini file and keeping it on a shared file system.

Creating and Editing Configuration Files Using sqledit

Use the sqledit utility provided with your software to create a new sql.ini file or to add, edit, or delete entries to your existing sql.ini and libtcl.cfg configuration files. Using sqledit will avoid creating erroneous file entries.

Launching sqledit

sqledit can be launched automatically or manually, as follows:

• Automatically, from pmco nfig , when you click the Interface Entry button in the Configure New SQL Server window.

• Automatically, from s ybinit , when you choose Configure Server's Interfaces File Entry from the SQL Server Configuration menu.

• Automatically, from the se tup installation utility, after the software has been loaded.

• Manually, from the OS/2 prompt.

Running sqledit From the Command Line

To run sqledit from the OS/2 prompt, change to the %SYBASE%\bin directory and type:

 sqledit 

Creating a New sql.ini File

To create a new sql.ini file, enter the sql.ini file name in the text field in the Open Window. Click Cancel to accept the entry. A new sql.ini file with the file name you have chosen is created.

Warning! When creating a new sql.ini file, you must click the Cancel button, not the Open button.

Editing the sql.ini File

When you install SQL Server, the installation program loads a sql.ini configuration file in the %SYBASE%\ini directory. At least one entry (specifying network connection information for the default SQL Server, SYBASE) is in the default sql.ini file.

When you first start-up sqledit , the Open window appears, displaying the contents of the %SYBASE%\INI directory, which is where the setup program originally loaded the sql.ini file:

If you have renamed the sql.ini file, or moved the file to a different location, or if you maintain multiple sql.ini configuration files at various locations, choose File ® Open , and specify the name and location of the configuration file you want to edit.

Once you open the sql.ini file, sqledit displays a list of SQL Servers for which sql.ini file entries exist, which contain the network connection information. Server names may refer to either SQL Servers or Open Servers.

Figure 3-4: SYBASE SQL address editor

Editing libtcl.cfg

When you install SQL Server, the installation program loads a libtcl.cfg configuration file in the %SYBASE%\INI directory. An entry is in the file for each installed Net-Library driver.

Unlike the sql.ini configuration file, libtcl.cfg must remain in the %SYBASE%\INI directory, and its file name must not be changed. Therefore, you should have only one copy of libtcl.cfg on your machine.

When you run sqledit , it is not necessary to specify either the name or the location of libtcl.cfg .

To add, edit, or delete driver entries from libtcl.cfg , choose
Edit ® Drivers . A new window appears, listing the descriptions of the Net-Library drivers installed on your machine and for which libtcl.cfg entries exist:

Figure 3-5: Edit Drivers

Adding Net-Library Driver Entries

The DLL drivers are located in the %SYBASE%\DLL directory. Following are examples of names for the available drivers:

IBM TCP/IP	NLIBMTCP
Named Pipes	NLOS2NMP
SPX/IPX	NINOVSPX

Enter this file name when sqledit prompts you. Choose the OK button; the Add Service dialog box disappears. Repeat this process for any additional services.

To add a driver entry to libtcl.cfg :

1. Choose Edit ® Add Driver from the Edit Drivers window. The Add New Driver dialog box appears:

2. Enter the file name of the driver's DLL.

   Note: Do not append the . dll extension to the file name when you enter it in the text box. For example, if your driver file name is NLOS2NMP.dll , enter "NLOS2NMP" in the text box.

3. Enter a brief description of the Net-Library driver. The first word of the description must be different from the first word of the other Net-Library driver descriptions.

4. Click OK.

5. Select Exit®Exit Edit Driver s to go back to the SYBASE SQL Address Editor window.

   Note: Net-Library must be installed before you add its corresponding entry to libtcl.cfg .

Editing Net-Library Driver Entries

To edit a driver entry in libtcl.cfg :

1. Select the driver's description.

2. Choose Edit®Edit Driver from the Edit Drivers window (or double-click on the driver's description.) The Edit Driver dialog box appears:

3. Edit the description of the Net-Library driver.

4. Click OK.

5. Select Exit®Exit Edit Drivers to go back to the SYBASE SQL Address Editor window.

Deleting Net-Library Driver Entries

To delete a driver entry from libtcl.cfg :

1. Highlight the driver's description.

2. Select Edit® Delete Driver from the Edit Drivers window. A dialog box appears:

3. Click Yes to delete.

4. Select Exit®Exit Edit Drivers to go back to the SYBASE SQL Address Editor Window.

Adding Server Entries

If you want client applications to connect to a SQL Server whose network connection information is not included in the sql.ini file, you must add an entry for that SQL Server. See "Network Driver" and "Connection Information" for information on entering networking data.

To add a SQL Server entry to the sql.ini file:

1. Select Edit®Add Server from the SYBASE SQL Address Editor window. The Add New Server dialog box appears:

2. Enter the name of the SQL Server whose sql.ini file entry you want to add, and click OK. The server entry window appears, displaying network connection information for the SQL Server. The server name is displayed on the window's title bar:

   Figure 3-6: Server connection information
   

3. Select Edit®Add Service. from the new server entry window. The Add Service dialog box appears:

4. Enter the connection's service type ("query" or "master")

5. Enter the network driver used for the connection
   (TCP/IP, Named Pipes, or SPX/IPX)

6. Enter the connection's address-related information.

7. Click OK to return to the server entry window.

8. Select Exit®Exit Edit Services to return to the SYBASE SQL Address Editor window.

9. To save the current interfaces file, select File®Save.

10. If you want to exit sqledit , select Exit®Exit SQLEDIT .

    Note: If the SQL Server for which the new entry is added uses a network protocol that is not supported by the installed Net-Library drivers, you must install the proper Net-Library driver before using the server entry.

Editing Server Entries

To edit a server entry in the sql.ini file:

1. Click on the server name whose entry you wish to edit in the SQL SYBASE Address Editor window, highlighting the server name.

2. Select Edit®Edit Server.

   The Server Entry window appears, displaying network connection information for the server:

   Figure 3-7: Network connection information
   

3. If more than one service entry appears, click on the entry you wish to edit, highlighting the entry.

4. Select Edit®Edit Service from the server entry's menu. An Edit Services dialog box appears:

5. Edit the network driver used for the connection.

6. Edit the connection's address-related information.

7. Click OK .

8. Select Exit®Exit Edit Services to go back to the SYBASE SQL Address Editor window.

9. To save the current interfaces file, select File®Save.

10. If you want to exit sqledit , select Exit®Exit SQLEDIT.

Deleting Server Entries

To delete a server entry from the sql.ini file:

1. Click on the server name whose entry you wish to delete in the SYBASE SQL Address Editor window, highlighting the server name.

2. Select Edit®Delete Server.

3. To save the current interfaces file, select File®Save.

4. To exit sqledit , select Exit®Exit SQLEDIT.

Guidelines for Editing the sql.ini File

When entering a server name, keep the following guidelines in mind:

• The first 8 characters of the server name must be unique on your LAN server. Although SQL Server names are case-sensitive within SYBASE products, the OS/2 operating system is case-insensitive. The run_server filename is constructed from the SQL Server name. If you intend to start SQL Server by executing the run_server file from the OS/2 command prompt, you must have unique Server names. For example, do not use "SYBASE," "Sybase," or "sybase" to name different SQL Servers. OS/2 interprets those three names as the same.

• From the Service Type drop-down menu, select either "MASTER" or "QUERY".
  • If you plan to access the SQL Server from a client machine, you need only a QUERY line. However, if the sql.ini file is to be used by all clients and SQL Servers on your network, you need to add both service types.

• From the Network Driver drop-down menu, select TCP/IP Driver, Named Pipes Driver, or Netware SPX/IPX depending on the network protocol you want to support. You can add an additional service later to support more than one protocol.

• In the Connection Information text box, type the connection information for the Backup Serverä, according to the network driver you selected.
  • For the Named Pipes Driver, enter the unique pipe name for the SQL Server. If you are adding a query, begin the pipe with \\machine_name . For example, a possible entry for a SQL Server on the machine "harpo" is \\harpo\pipe\sql\query . Do not add the \\machine_name prefix if you are creating a MASTER entry. Master entries are used by the server, which always boots a local machine.

Verifying Server Connections Using sybping

After you finish configuring your system, use the sybping utility to verify that you can connect to a SQL Server. sybping is a network diagnostic utility included with your Net-Library release 10.0 software. It is located in the bin subdirectory of the SYBASE root directory. sybping checks to see if a process is listening at the specified address. See Appendix A, "Troubleshooting Network Connections," for more information about using sybping .

What's Next?

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