Home

	Expand Search

Server Administration Guide for DirectConnect

Chapter 5 Using service name redirection

Chapter 5

Using service name redirection

Service name redirection is an optional feature that lets you route client requests for a service to alternative service names. This chapter explains how you can set up and use the service name redirection feature.

This chapter covers the following topics:

• How service name redirection works

• Using the command line to edit a snrf table

• Precedence rules

• The validation utility

• Implementing a service name redirection file

How service name redirection works

When a client application accesses a service, it specifies a service name. The name must correspond to the name of an actual service or to an entry in the service name redirection file.

You activate the service name redirection file by configuring the ServiceRedirectionFile property. With service name redirection, you control access to services according to individual user profiles. The profile consists of the requested service, user ID, and application name.

You can assign each user profile to any service supported by a service library. The DirectConnect Server attempts to match the client request with an entry in the service name redirection file before connecting directly with the service.

Different users who request the same general service name can be routed to different actual services. For example, three individuals requesting "AS400" could receive completely different services, such as:

• One for decision support

• One for copy management

• One for online transaction processing (OLTP)

Thus, you can manage multiple sets of clients with a single service library. You must still configure the sql.ini (NT) or interfaces (UNIX) file to connect clients to the DirectConnect Server.

For instructions on editing the sql.ini or interfaces file, see the appropriate Open Client Installation and Administration guide for your operating system..

You can use DirectConnect Manager or a command line to edit a snrf table.

Using DirectConnect Manager to edit snrf tables

Using DirectConnect Manager, you can perform editing tasks interactively on the Service Name Redirection Editor (SNRF) dialog box, shown next:

To use DirectConnect Manager to edit snrf tables:

• Start up DirectConnect Manager.

• Right click on the server name, and select Edit SNRF Table from the menu options.

  The Service Name Redirection Editor dialog box appears.

• Edit the existing fields on the SNRF table by selecting the appropriate field (cell), editing the contents, and saving the changes.

• Click one of these buttons:

  • Save, to commit all changes made to the table to the DirectConnect server. The entire table is sent and updated at the same time.

  • Add Row, to open a row within the table so an additional entry can be made to the table. The added row will not be added to the DirectConnect server until Save is selected.

  • Delete Row, to delete the selected row.

  • Reset, to reset the table to the same values as those of the DirectConnect Server.

    Reset is useful in case you modify the table and then decide not to commit the changes.

Using the command line to edit a snrf table

The following sections contain information you need to edit the snrf table using a command line.

Service name redirection file format

The service name redirection file is a text file consisting of four columns separated by tabs, with as many rows as you require to define the redirections. Using a text editor or DirectConnect Manager, you can change the name of the file.

If you use a text editor, be sure that it inserts actual tabs, not merely spaces that simulate tabs.

The following table shows the format of a service name redirection file.

Service name redirection rules are as follows:

• Columns must be separated by a single tab character.

• Wild cards (asterisks) are allowed in the requested_service, user_id, and application_name columns.

• Comments are not allowed.

• Blank lines can be added for easier viewing.

• Only the user_id column is case-sensitive.

If used, a service name redirection file must be valid for the server to start successfully. A valid file has exactly four columns on each line.

To use DirectConnect Manager to edit the SNRF table for a DirectConnect server:

• From the Sybase Central viewer (left panel), highlight the DirectConnect plug-in or an existing server in the tree beneath DirectConnect.

• Right-click the mouse.

• Select Edit SNRF Table in the pop-up menu that appears.

From the Edit SNRF Table dialog, you can:

• Select any of the rows or columns and edit them directly.

• Add or delete a row.

• Save your changes. (Otherwise, they will not take effect.)

• Undo your changes, by either using the reset key to reset the table with the server's current SNRF table, or clicking the Close button without saving.

Null service names

Some DB-Library(TM) versions do not provide a remote server name for service routing, so requests from these DB-Library applications contain null service names. If you run multiple services with a single server, you must use service name redirection to connect such clients. In particular, consider the following:

• Microsoft DB-Library requests contain null service names, because the specified service name is not passed to Open Server in the internal login record. You must use service name redirection to connect such clients.

• Sybase Open Client DB-Library versions 4.2 and earlier do not provide a remote server name. You must use service name redirection to connect such clients.

• Sybase Open Client DB-Library versions 4.3 and above provide the server name. With such clients, you can use direct routing or service name redirection.

If the requested_service name is a null or empty string, the service name redirection file line for routing that service must begin with a tab character. The following table shows an example of a service name redirection file with a null requested_service name.

Precedence rules

You may inadvertently create a service name redirection file in which an assigned service name is not uniquely specified. Should this situation occur, the system uses the following precedence rules to resolve the problem. The first rule defines the highest precedence, the eighth one the lowest.

A null requested service is treated as any other explicitly specified service.

To see how the precedence rules work, assume that you set up the service name redirection file shown in the following table.

Based upon the preceding table, the following are true:

• If Bob requests service AS400 using isql, he is redirected to service "as1."

• If anyone other than Bob requests AS400 using isql, that person is directed to service "as2."

• Anyone who requests service AS400 using Omni is directed to service "omniA."

• Anyone who requests service AS400 using PowerBuilder is redirected to service "powerB."

• Anyone who requests service AS400 using any other application is not redirected. Such requests are connected directly to service "AS400."

• Anyone who requests service DB2 using Omni is directed to service "db2omni."

• Anyone who requests service DB2 using any other application is redirected to service "db2gen."

• All Microsoft and earlier Sybase DB-Library clients for which the requested service name is blank are directed to service "as3."

• Finally, all other clients are routed to service "as4."

The validation utility

Sybase provides a validation utility called snrfck that lets you validate the format of the service name redirection file. The snrfck command uses the following syntax:

• snrfck [-v][-?]|-h] [-t[-oresult]]
   [-Ssvc -Uuser -Aappl] -ifile

or

snrfck -c -Ssrv -Uuser -Ppwd -ifile

where

-v displays the program version only.

-? or -h displays this message.

-t tests the update capability.

-oresult outputs the file for results of the update test (this has no effect if you do not specify -t).

-ifile indicates the service name redirection file to be tested.

-Ssvc, -Uuser, an d -Aappl are optional arguments used to test the redirection search.

-c submits the file to the server srv for an immediate update, using the specified login pwd.

-Ssrv indicates the server name.

-Uuser indicates the user name.

-Ppwd indicates the password for the user name .

The snrfck basic command requires only the -i option. When you use this option, snrfck reads the redirection file, validates each line, and flags the first incorrect line it encounters.

For example, suppose you enter:

snrfck -ic:\cfg\testfile

where

• cfg is the directory containing the service name redirection file.

• testfile is the service name redirection file.

The path cfg\testfile is shown as a PC-based system in this example and in the remainder of the examples in this chapter.

Next, assume the redirection file contains the entries shown in the following table.

In this example, snrfck returns:

c:\cfg\testfile: line3: duplicate/ambiguous row

If the file does not contain errors, the rows are sorted in the order used in the redirection operation and printed to the screen.

An example of a correctly formatted service name redirection file, as output by snrfck, is shown in the following table. snrfck adds line numbers for clarity.

You can test the redirection process by supplying values for requested_service, user_id, and application_name, subject to the following restrictions:

• You must specify values for user_id and application_name.

• You can use a null argument for requested_service to allow matching on a null service.

When you supply these values, snrfck displays the sorted entries and the assigned service to which the request would be directed.

For example, suppose you use the preceding sample file and enter the following:

snrfck -itestfile -Sdb2 -Ujane -Aisql

where

db2 is the requested service.

jane is the user ID.

isql is the application name.

You receive the match shown in the following table.

If the service redirection comparison does not find a match, the value returned for assigned_service is simply the requested_service value.

For example, suppose you use the preceding sample file and enter:

snrfck -itestfile -Sdb2 -Uramon -Aisql

where

• db2 is the requested service.

• ramon is the user ID.

• isql is the application name.

You receive the failed entry match shown in the following table.

You can add lines to the service name redirection file list by specifying the -t option.

When you use this option, snrfck displays the normal redirection file and prompts you to enter new lines consisting of "service," "user," "application," and "assigned_service," each separated by a tab character. snrfck reads the lines, validates them, adds them to the output file, and displays the amended file.

For example, suppose you use the preceding sample file and enter:

snrfck -itestfile -t -onewfile

where

• -t activates the test or update capability.

• -onewfile specifies the output file. To save changes to the redirection file, you must use this option.

If you use -t without using -o, your additions are displayed, but not saved.

You receive a file with instructions for adding lines, as shown in the following table.

Then, suppose you add the following lines in response to the prompt (snrfck supplies the line numbers):

8: db2 rachel * svc_db2gen
 9: .

snrfck produces a new service name redirection file, as shown in the following table.

snrfck adds the new entry and sorts the file.

Other snrfck options include displaying a version number and displaying help text.

Version number

You can display the snrfck version by using the -v option.

For example, suppose you enter the following line:

snrfck -v

A line similar to the following returns:

Service Name Redirection Check Utility, $Revision: 1.2 $

Help text

You can display help text in either of the following ways:

• Type snrfck -h.

• Type snrfck and press Enter.

For example, suppose you enter the following line:

snrfck -h

The following line returns:

snrfck [-v] [-? | -h] [-t [-ofile] ]
 [ -Ssvc -Uusr -Aappl ] -ifile

where

-v displays the program version only.

-? or -h displays this help text.

-t activates the test or update capability.

-ofile specifies the output file (this has no effect if -t is not used).

-Ssvc (service), -Uusr (user), -Aappl (application) are optional arguments to test the redirection search.

-ifile specifies the input service redirection file.

In UNIX systems, escape the -? argument as follows:

snrfck -\?

Implementing a service name redirection file

After you use snrfck to create or update a service name direction file, you can implement the modified file on the DirectConnect Server, as described in the following paragraphs.

You can implement a new service name redirection file or copy a modified file by performing the following steps:

• Use snrfck to create a new file or modify the existing file and validate it.

• Stop the DirectConnect Server.

• Copy or rename the file, as applicable.

• Restart the server.

You can use snrfck to create or update a service name redirection file, validate the file, and send it to a running DirectConnect Server.

Using this method allows you to replace the contents of the snrf.tbl that is read at server start, write the contents to disk, and update the memory table so that the changes take effect immediately.

To update to a running server using snrfck, perform the following steps:

• Use snrfck to create a new file or modify the existing file and validate it.

• Send the file to the server using the syntax described in "The validation utility" .