Sybase Adaptive Server, Adaptive Server Enterprise 15.0 Configuration Manual

Configuration Guide

Adaptive Serv er® Enterprise

15.0

[ UNIX ]

DOCUMENT ID: DC35823-01-1500-04
LAST REVISED: March 2007

Copyright © 1987-2007 by Sybase, Inc. All rights reserved.
This publication pertains to Sybase software and to any subsequent release until otherwise indicated in new editions or technical notes.

Information in this document is subject to change without notice. The software described herein is furnished under a license agreement,
and it may be used or copied only in accordance with the terms of that agreement.

To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at [phone], fax [phone].
Customers in other countries with a U.S. license agre eme nt ma y conta c t Custom er Fulfi llme nt via the above fax number. All other

international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled
software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic,
mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc.

Sybase, SYBASE (logo), ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive Server, Adaptive Server
Anywhere, Adapt ive Server E nterprise , Adaptive Se rver Ent erprise Monitor , Adaptive Server Enterpris e Replication, Adaptive Se rver Everywhere, Advantage
Database Server, Afaria, Answers Anywhere, Applied Meta, Applied Metacomputing, AppModeler, APT Workbench, APT-Build, APT-Edit, APT-Execute,
APT-Translator, APT-Library, ASEP, Avaki, Avaki (Arrow Design), Avaki Data Grid, AvantGo, Backup Server, BayCam, Beyond Connected, Bit-Wise,
BizTracker, Certified PowerBuilder Developer, Certified SYBASE Professional, Certified SYBASE Professional Logo, ClearConnect, Client-Li bra ry, Client
Services, CodeBank, Column Design, ComponentPack, Connection Manager, Convoy/DM, Copernicus, CSP, Data Pipeline, Data Workbench, DataArchitect,
Database Analyzer, DataExpress, DataServer, DataWindow, DataWindo w .NET, DB-Library, dbQueue, Dejima, Dejima Direct, Developers Workbench,
DirectConnect Anywhere, DirectConnect, Distribution Director, Dynamic Mobility Model, e-ADK, E-Anywhere, e-Biz Integrator , E-Whatever , EC Gateway ,
ECMAP, ECRTP, eFulfillment Accelerator, EII Plus, Electronic Case Management, Embedded SQL, EMS, Enterprise Application S tudio, Enterprise Client/
Server, Enterprise Connect, Enterprise Data Studio, Enterprise Manager, Enterprise Portal (logo), Enterprise SQL Server Manager, Enterprise Work
Architecture, Enterprise Work Designer, Enterprise Wor k Modeler, eProcurement Accelerator, eremote, Everything Works Better When Everything Works
Together , EWA, ExtendAssist, Extended Systems, ExtendView , F inancial Fusion, Financial Fusion (and design), Financial Fusion Server, Formula One, Fusion
Powered e-Finance, Fusion Powered Financial Destinations, Fusion Powered STP, Gateway Manager, GeoPoint, GlobalFIX, iAnywhere, iAnywhere Solutions,
ImpactNow, Industry Warehouse Studio, InfoMaker, Information Anywhere, Information Everywhere, InformationConnect, InstaHelp, Intelligent Self-Care,
InternetBuilder, iremote, irLite, iScript, Jaguar CTS, jConnect for JDBC, KnowledgeBase, Legion, Logical Memory Manager, M2M Anywhere, Mach
Desktop, Mail Anywhere Studio, Mainframe Connect, Maintenance Express, Manage Anywhere Studio, MAP , M-Business Anywhere, M-Business Channel,
M-Business Network, M-Business Suite, MDI Acces s Se rver, MDI Database Gateway, media.splash, Message Anywhere Server, MetaWorks, MethodSet,
mFolio, Mirror Activator, ML Query, MobiCATS, MobileQ, MySupport, Net-Gateway, Net-Library , New Era of Networks, Next Generation Learning, Next
Generation Learning Studio, O DEVICE, OASiS, OASiS logo, ObjectConnect, ObjectCycle, OmniConnect, OmniQ, OmniSQL Access Module, OmniSQL
Toolkit, OneBridge, Open Biz, Open Business Interchange, Open Client, Open ClientConnect, Open Client/Server, Open Client/Server Interfaces, Open
Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++, Partnerships that Work, PB-Gen, PC APT Execute, PC DB-Net, PC Net Library,
Pharma Anywhere, PhysicalArchitect, Pocket PowerBuilder, PocketBuilder, Power++, Power Through Knowledge, power.stop, PowerAMC, PowerBuilder,
PowerBuilder Foundation Class Library, PowerDesigner, PowerDimensions, PowerDynamo, Powering the New Economy, PowerScript, PowerSite,
PowerSocket, Powersoft, PowerStage, PowerStudio, Pow erTips, Powersoft Portfolio, Powersoft Professional, PowerWare Desktop, PowerWare Enterprise,
ProcessAnalyst, Pylon, Pylon Anywhere, Pylon Application Server, Pylon Conduit, Pylon PIM Server, Pylon Pro, QAnywhere, Rapport, Relational Beans,
RemoteW are, RepConnector, Report Workbench, Report-Execute, Replication Agent, Replication Driver, Replication Server, Replication Server Manager,
Replication Toolkit, Resource Manager , RFID Anywhere, RW-DisplayLib, RW-Librar y, SAFE, SAFE/PRO, Sales Anywhere, Search Anywhere, SDF, Search
Anywhere, Secure SQL Server, Secure SQL Toolset, Security Guardian, ShareSpool, ShareLink, SKILS, smart.partners, smart.parts, smart.script, SOA
Anywhere Trademark,SQL Advantage, SQL Anywhere, SQL Anywhere Studio, SQL Code Checker, SQL Debug, SQL Edit, SQL Edit/TPU, SQL Everywhere,
SQL Modeler, SQL Remote, SQL Server, SQL Server Manager, SQL SMART, SQL Toolset, SQL Server/CFT, SQL Server/DBM, SQL Server SNMP
SubAgent, SQL Station, SQLJ, Stage III Engineering, Startup.Com, STEP, SupportNow, S.W.I.F.T . Message Format Libraries, Sybase Central, Sybase Client/
Server Interfaces, Sybase Development Framework, Sybase Financial Server, Sybase Gateways, Sybase IQ, Sybase Learning Connection, Sybase MPP , Sybase
SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase Synergy Program, Sybase Virtual Server Architecture, Sybase User Workbench,
SybaseWare, Syber Financial, SyberAssist, SybFlex, SybMD, SyBooks, System 10, System 11, System XI (logo), SystemT ools, Tabular Data Stream, The
Enterprise Client/Server Company, The Extensible Software Platform, The Future Is Wide Open, The Learning Connection, The Model For Client/Server
Solutions, The Online Information Center, The Power of One, TotalFix, TradeForce, Transact-SQL, Translation Toolkit, Turning Imagin ation I n to Realit y,
UltraLite, UltraLite.NET, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Viafone, Viewer, VisualWr iter, VQL,
WarehouseArc hitect, W arehouse Control Center , W arehouse Studi o, W arehouse WORKS, W a tcom, W atcom SQL, W atcom SQL Server, Web Deployment Kit,
Web.PB, Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, XA-Server, XcelleNet, XP Server, XTNDAccess and XTNDConnect are
trademarks of Sybase, Inc. or its subsidiaries. 01/06

Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.
All other company and product names used herein may be trademarks or registered trademarks of their respective companies.
Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-7013

for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies.
Sybase, Inc., One Sybase Drive, Dublin, CA 94568.

Contents

About This Book.......................................................................................................................... vii

CHAPTER 1 Introduction..................................................................................... 1

About Adaptive Server ..................................................................... 1

System-specific issues..................................................................... 2

System user roles ............................................................................ 3

Environment variables...................................................................... 3

Adaptive Server devices and system databases.............................. 5

The master device..................................................................... 5

The sybsystemdb device........................................................... 6

The sysprocsdev device............................................................ 6

Optional devices and databases............................................... 6

dsync option on by default for database device files................. 8

Determining the location, type, and size of a database device. 9

Client/server communication.......................................................... 11

Changing Adaptive Server configuration........................................ 12

Languages other than U.S. English ............................................... 13

Adaptive Server specifications....................................................... 13

CHAPTER 2 Starting and Stopping Servers .................................................... 17

Configuration Gu ide iii

Overview ........................................................................................ 17

Requirements for starting servers ........................................... 17

Starting servers.............................................................................. 18

Server start-up parameters ..................................................... 18

Using a RUN_server_name file............................................... 19

Using the startserver command .............................................. 20

Using the monserver and backupserver commands............... 20

Starting servers when the operating system restarts..................... 20

For HP-UX............................................................................... 21

For IBM RS/6000..................................................................... 21

For Sun Solaris and Linux....................................................... 22

Starting XP Server after initial installation...................................... 24

Stopping servers ............................................................................ 24

Contents

Stopping Adaptive Server........................................................ 24

Stopping Backup Server.......................................................... 25

Stopping Monitor Server.......................................................... 26

Using the kill command........................................................... 26

Shutdown and shared memory files........................................ 27

CHAPTER 3 Configuring the Operating System .............................................. 29

Setting environment variables........................................................ 29

Configuring new servers with srvbuild............................................ 30

Using the stty setting...................................................................... 33

Restoring correct permissions ........................................................ 34

File descriptors and user connections............................................ 34

For HP-UX............................................................................... 34

For AIX.................................................................................... 34

For Linux ................................................................................. 35

For Sun Solaris........................................................................ 35

Displaying current soft and hard limits .................................... 35

Increasing the soft limit............................................................ 35

Increasing the hard limit.......................................................... 36

Sample program...................................................................... 37

Enabling asynchronous disk I/O..................................................... 38

Adjusting the client connection timeout period............................... 41

For HP-UX............................................................................... 41

For IBM RS/6000..................................................................... 41

For Sun Solaris........................................................................ 42

For Linux ................................................................................. 42

Checking for hardware errors......................................................... 42

For HP-UX............................................................................... 42

For IBM RS/6000..................................................................... 43

For Sun Solaris........................................................................ 43

For Linux ................................................................................. 43

Monitoring the use of operating system resources ........................ 43

For HP-UX............................................................................... 43

For IBM RS/6000..................................................................... 44

For Sun Solaris and Linux....................................................... 44

A sample C shell maintenance script............................................. 45

CHAPTER 4 Adaptive Server Default Configuration........................................ 47

Default settings .............................................................................. 47

CHAPTER 5 Setting Up Communications Across the Network...................... 49

How Adaptive Server determines which directory service entry to use

iv

Adaptive Server Enterprise

Contents

50

How a client uses directory services.............................................. 51

Creating a directory services entry................................................. 51

Supported directory drivers............................................................ 52

Contents of an interfaces file.......................................................... 52

Heterogeneous and homogeneous environments......................... 53

Understanding the format of the interfaces file .............................. 55

Components of an interfaces file entry.................................... 56

Creating a master interfaces file .................................................... 58

Using dsedit or dscp to create a master interfaces file............ 58

Using a text editor to create a master interfaces file............... 58

Configuring interfaces files for multiple networks........................... 59

Configuring the server for multiple network handlers.............. 59

Configuring the client connections .......................................... 60

Configuring for query port backup........................................... 62

IPv6 support................................................................................... 63

Understanding IPv6................................................................. 63

IPv6 infrastructure................................................................... 64

Starting Adaptive Server Enterprise as IPv6-aware................ 65

Troubleshooting ............................................................................. 66

Server fails to start .................................................................. 66

Error when executing an ESP................................................. 67

CHAPTER 6 Using the Lightweight Directory Access Protocol as a Directory

Service..................................................................................... 69

Overview........................................................................................ 69

LDAP directory services versus the Sybase interfaces file............ 70

The libtcl*.cfg file............................................................................ 73

Enabling LDAP directory services.................................................. 74

Adding a server to the directory services....................................... 76

Multiple directory services.............................................................. 77

Encrypting the password................................................................ 78

Performance................................................................................... 78

Migrating from the interfaces file to LDAP...................................... 79

CHAPTER 7 Customizing Localization for Adaptive Server........................... 81

Overview of localization support .................................................... 81

Language modules.................................................................. 82

Default character sets for servers ........................................... 83

Supported character sets ........................................................ 84

Character set conversion ............................................................... 89

Conversions between server and client .................................. 89

Sort orders ..................................................................................... 90

Configuration Guide v

Contents

Available sort orders................................................................ 90

Language modules......................................................................... 93

Installing a new language module........................................... 93

Message languages................................................................ 93

Localization.................................................................................... 94

Localization directories............................................................ 94

About the directory.................................................................. 95

About the charsets directory.................................................... 95

About the locales.dat file......................................................... 95

Changing the localization configuration ......................................... 97

Adaptive Server localization.................................................... 98

Backup Server localization...................................................... 99

Sort orders............................................................................. 100

Character sets....................................................................... 101

charset utility ......................................................................... 102

CHAPTER 8 Logging Error Messages and Events ........................................ 105

Adaptive Server error logging ...................................................... 105

Enabling and disabling error logging..................................... 106

Setting error log paths.................................................................. 106

Setting the Adaptive Server error log path............................ 106

Managing messages.................................................................... 107

Logging user-defined messages........................................... 107

Logging auditing events ........................................................ 108

CHAPTER 9 Managing Adaptive Server Databases....................................... 109

Managing database devices ........................................................ 109

Device requirements ............................................................. 109

Creating files for database devices....................................... 110

CHAPTER 10 Adding Optional Functionality to Adaptive Server................... 113

Adding auditing ............................................................................ 113

Audit system devices and databases.................................... 113

Overview of audit installation................................................. 114

Pre-installation tasks for auditing devices............................. 115

Installing auditing................................................................... 115

Installing online help for Transact-SQL syntax............................. 121

Online syntax help: sp_syntax............................................... 121

Default device for the sybsyntax database............................ 122

Installing sybsyntax............................................................... 122

Index ........................................................................................................................................... 125

vi

Adaptive Server Enterprise

About This Book

This manual, the Configuration Guide, provides instructio ns for
performing specific configuration tasks for Sybase® Adaptive Server®
Enterprise on UNIX platforms.

The operating system release levels for the UNIX platforms on which
Adaptive Server is certified to execute is in the installation documentation
or release bulletin for your platform.

This manual covers the following topics:

• Instructions for reconfiguring certain attributes of your existing

• Creating network connections .

Sybase Adaptive Server Enterprise, Backup Server™, Adaptive
Server Enterprise Monitor™, and XP Server™ to meet yo ur specific
needs.

Audience

How to use this book

• Configuring optional functionality.

• Performing operating system administration tasks.

• Working with system administration issues that are relevant to
Adaptive Server running on UNIX platforms. This manual
supplements the System Administra tion Guide and the Performance
and Tuning Guide.

Note Before configuring Ad aptive Server according to the instr uctions in

this book, you s hould have a newly install ed or upgraded Adaptive Server
on your system. If you do not, follow the installation and upgrade
instructions in the installation documentation for your p latform.

This manual is for System Administrators or other qualified installers who
are familiar with their system’s environment, networks, disk resources,
and media devices.

This manual contains the following chapters:

• Chapter 1, “Introduction” is an overview of Adaptive Server an d the
configuration changes you might want to make to Adaptive Server
after installing or upgrading the server.

Configuration Gu ide vii

• Chapter 2, “Starting and Stopping Servers” describes how to start and
stop Adaptive Server, Backup Server, Monitor Server, and XP Server.

• Chapter 3, “Configuring the Operating System” describes how to set up
your operating system to work with Adaptive Server.

• Chapter 4, “Adaptive Server Default Configuration” provides
information about the default parameter settings of Adaptive Server.

• Chapter 5, “Setting Up Communications Across the Network” describes
how to use the interfaces file to establish network connections for servers
and clients.

• Chapter 6, “Using the Lightweight Directory Access Protocol as a
Directory Service” provides information about using LDAP directory
services to establish connections.

• Chapter 7, “Customizing Localizat ion for Adaptive Server” provides
background information about Sybase’s localization support as well as
task information for reconfiguring character sets, sort orders, and language
modules.

Related documents

• Chapter 8, “Logging Error Me ssa ges and Events” describes how to use
the error logging features of Adaptive Server.

• Chapter 9, “Managing Adaptive Server Databases” provides information
about the administration of Adaptive Server databases, i ncluding both
routine tasks and performance and tuning considerations.

• Chapter 10, “Adding Optional Functionality to Adaptive Server”
provides instructions for adding optional functio nality, su ch as auditing
and the sample databases.

The Sybase® Adaptive Server® Enterprise documentation set consists of the
following:

• The release bulletin for your platform – contains last-minute information
that was too late to be included in the books.

A more recent version of the release bulletin may be available on the
World Wide Web. To check for critical product or document information
that was added after the release of the product CD, use the Sybase
Technical Library.

•The Installation Guide for your platform – describes inst allation, upgrade,
and configuration procedures for all Adaptive Server and related Sybase
products.

viii Adaptive Server Enterprise

About This Book

• What’s New in Adaptive Server Enterprise? – describes the new features

in Adaptive Server version 15.0, the system changes added to support
those features, and changes that may affect your existing applications.

• ASE Replicator User’s Guide – des cribes ho w to us e the Adaptive Server

Replicator feature of Adaptive Server to implement basic replication from
a primary server to one or more remote Adaptive Servers.

• Component Integration Services User’s Guide – explains how to use the

Adaptive Server Component Integration Services feature to connect
remote Sybase and non-Sybase databases.

•The Configurati on Gui de for your platform – provides instructions for

performing specific configuration tasks for Adaptive Server.

• Full-T ext Sear ch Specialty Data S tor e User’ s Guid e – describes how to use

the Full-Text Search feature with Verity to search Adaptive Server
Enterprise data.

• Glossary – defines technical terms used in the Adaptive Server

documentation.

• Java in Adaptive Server Enterprise – describes how to install and use Java

classes as data types, functions, and stored procedures in the Adaptive
Server database.

• Messaging Service User’s Guide – describes how to useReal Time

Messaging Services to integrate Java Message Service and IBM
WebSphere MQ messaging services with all Adaptive Server database
applications.

• Monitor User's Guide, Historical Server – descri bes how to us e Historical

Server to obtain performance information for SQL Server

®

and Adaptive

Server.

• Monitor Client Library Programmer’s Guide – describes how to write

Monitor Client Library applications that access Adaptive Server
performance data.

• Monitor Server User’s Guide – describes how to use Monitor Server to

obtain performance statistics from SQL Server and Adaptive Server.

• Performance and Tuning Guide – is a series of four books that explains

how to tune Adaptive Server for maximum performance:

• Basics – the basics for understanding and investigating performance
questions in Adaptive Server.

Configuration Gu ide ix

• Locking – describes how the various locki ng schemas can be used for
improving performance in Adaptive Server.

• Optimizer and Abstract Plans – describes how the optimizer
processes queries and how abstract plans can be used to change some
of the optimizer plans.

• Monitoring and Analyzing – exp lains how statistics are obtained and
used for monitoring and optimizing performance.

• Quick Reference Guide – provides a comprehensive listing of the names
and syntax for commands, functions, system procedures, extend ed system
procedures, datatypes, and utilities in a pocket-sized book.

• Refer ence Ma nual – is a series of four books that contains the following
detailed Transact-SQL

®

information:

• Building Blocks – Transact-SQL datatypes, functions, global

variables, expressions, identifiers an d wildcar ds , an d r eser ved word s.

• Commands – Transact-SQL commands.

• Procedures – Transact-SQL system procedures, catalog stored

procedures, system extended stored procedures, and

dbcc stored

procedures.

• Tables – Transact-SQL system tables and

dbcc tables.

• System Administratio n Guide – provides in-depth information about
administering servers and databases. This manual includes instructions
and guidelines f or managing physical r esources, s ecurity, user and system
databases, and specifying character conversion, international language,
and sort order settings.

• System Tables Diagram – illustrates system tables and their entity
relationships in a poster format. Available only in print version.

• Transact-SQL User ’s Guid e – documents Transact-SQL, Sybase’s
enhanced version of the relati onal datab ase lang uage. This man ual serves
as a textbook for beginning users of the database management system.
This manual also contains descriptions of the

pubs2 and pubs3 sam ple

databases.

• Using Adaptive Server Distributed Transaction Management Features –
explains how to configure, use, and troubleshoot Adaptive Server DTM
features in distributed transaction processing environments.

x Adaptive Server Enterprise

About This Book

• Using Sybase Failover in a High Availability System – provides

instructions for using Sybase’s Failover to configure an Adaptive Server
as a companion server in a high availability system.

• Unified Agent and Agent Management Console – Describes the Unified

Agent, which provides runtime services to manage, monitor and control
distributed Sybase resour ces.

• Utility Guide – documents the Adaptive Server utility programs, such as

isql and bcp, which are executed at the operating system level.

• Web Services User’s Guide – explains how to configure, use, and

troubleshoot Web Services for Adaptive Server.

• XA Interface Integration Guide for CICS, Encina, and TUXEDO –

provides instructions for using the Sybase DTM XA interface with
X/Open XA transaction managers.

• XML Services in Adaptive Server Enterprise – describes the Sybase native

XML processor and the Sybase Java-based XML support, introduces
XML in the database, and documents the query and mapping functions
that comprise XML Services.

Other sources of
information

Use the Sybase Getting S tarted CD, the SyBooks CD, and the Sybas e Product
Manuals Web site to learn more about your product:

• The Getting Started CD contains release bulletins and installation guides

in PDF format, and may also contain other documents or updated
information not included on the SyBooks CD. It is included with your
software. To read or print documents on the G etting S tarted CD, yo u need
Adobe Acrobat Reader, which you can download at no charge from the
Adobe Web site using a link provided on the CD.

• The SyBooks CD contains product manuals and is included with your

software. The Eclipse-based SyBooks browser allows you to access the
manuals in an easy-to-use, HTML-based format.

Some documentation may be provided in PDF format, which you can
access through the PDF directory on the SyBooks CD. To read or print the
PDF files, you need Adobe Acrobat Reader.

Refer to the SyBooks Installation Guide on the Getting Started CD, or the
README.txt file on the SyBooks CD for instructions on installing and
starting SyBooks.

Configuration Gu ide xi

• The Sybase Produ ct Manuals W eb si te is an online versi on of the SyBooks
CD that you can access using a standard Web browser. In addition to
product manuals, you will find links to EBFs/Maintenance, Technical
Documents, Case Management, Solved Cases, newsgroups, and the
Sybase Developer Network.

Sybase certifications
on the Web

T o access the Sybase Product Man uals Web site, go to

http://www.sybase.com/support/manuals/

.

Product Manuals at

Technical documentation at the Sybase Web site is updated frequently.

v Finding the latest information on product certifications

1 Point your Web browser to Technical Documents at

http://www.sybase.com/support/techdocs/

.
2 Select Products from the navigation bar on the left.
3 Select a product name from the product list and click Go.
4 Select the Certification Report filter, specify a time frame, and click Go.
5 Click a Certification Report title to display the report.

v Finding the latest information on component certifications

1 Point your Web browser to Availability and Certification Reports at

http://certification.sybase.com/

.

2 Either select the product family and product under Search by Product; or

select the platform and product under Search by Platform.

3 Select Search to display the availability and certification report for the

selection.

v Creating a personalized view of the Sybase Web site (including support

pages)

Set up a MySybase profile. MySybase is a free service that allows you to create
a personalized view of Sybase Web pages.

1 Point your Web browser to

http://www.sybase.com/support/techdocs/

Technical Documents at

.
2 Click MySybase and create a MySybase profile.

xii Adaptive Server Enterprise

Sybase EBFs and
software
maintenance

About This Book

v Finding the latest information on EBFs and software maintenance

1 Point your Web browser to the Sybase Support Page at

http://www.sybase.com/support

.

2 Select EBFs/Maintenance. If prompted, enter your MySybase user name

and password.
3 Select a product.
4 Specify a time frame and click Go. A list of EBF/Maintenance releases is

displayed.

Padlock icons indicate that you do not have download authorization for

certain EBF/Maintenance releases because you are not registered as a

Technical Support Contact. If you have not registered, but have valid

information provided by your Sybase representative or through your

support contract, click Edit Roles to add the “Technical Support Contact”

role to your MySybase profile.
5 Click the Info icon to display the EBF/Maintenance report, or click the

product description to downl oad the softw are.

Conventions

The following sections describe conventions used in this manual.
SQL is a free-form languag e. There are no rules about the numb er of words you

can put on a line or where you must break a line. However, for readability, all
examples and most syntax statements in this manual are formatted so that each
clause of a statement begins on a n ew line. Clauses that have more than on e part
extend to additional lines, which are indented. Complex commands are
formatted using modified Backus Naur Form (BNF) notation.

T able 1 shows the conventions for syntax statements that appear in this manual:

Table 1: Font and syntax conv enti ons for this manua l

Element Example

Command names, procedure names, utility names,
and other keywords display in sans serif font.

Database names and datatypes are in sans serif font. master database
Book name s, file nam es, variables , and path n ames are

in italics.

select
sp_configure

System Administra tio n Guid e
sql.ini file
column_name
$SYBASE/ASE dir ect o ry

Configuration Gu ide xiii

Element Example

Variables—or words that stand for values that you fill

select column_name

in—when they are part of a query or statement, are in
italics in Courier font.

Type parentheses as part of the command.
Double colon, equals sign indicate s that the synta x is

compute row_aggregate (column_name)

::=

written in BNF notation. Do not type this symbol.
Indicates “is defined as”.

Curly braces mean that you must choose at least one

{cash, check, credit}

of the enclosed options. Do not type the braces.
Brackets mean that to choose one or more of the

[cash | check | credit]

enclosed options i s optional. Do n ot type the br ackets.
The comma means you may choose as many of the

cash, check, credit

options shown as you want. Separate your choices
with commas as part of the command.

The pipe or vertical bar( | ) means you may select only

cash | check | credit

one of the options sh ow n .
An ellipsis (...) means that you can repeat the last unit

as many times as you like.

buy thing = price [cash | check |
credit]
[, thing = price [cash | check |
credit] ]...

Y ou must buy at least one thing and give its price. You may
choose a method of payment: one of the items enclosed in
square brackets. You may also choose to buy additional
things: as many of them as you like. For each thing you
buy, give its name, its price, and (optionally) a method of
payment.

from table_name
where search_conditions

• Syntax statements (displaying the syntax and all options for a command)
appear as follows:

For a command with more options:

In syntax statements, keywords (commands) are in normal font and
identifiers are in lowercase. Italic font shows user-supplied words.

• Examples showing the use of Transact-SQL commands are printed like
this:

xiv Adaptive Server Enterprise

sp_dropdevice [device_name]

select column_name

from table_name
where search_conditions

select * from publishers

• Examples of output from the computer appear as follows:

pub_id pub_name city state

------- --------------------- ----------- ----­0736 New Age Books Boston MA
0877 Binnet & Hardley Washington DC
1389 Algodata Infosystems Berkeley CA

(3 rows affected)

In this manual, most of the examples are in lowercase. However, you can
disregard case when typing Transact-SQL keywords. For example,

Select, and select are the same.

Adaptive Server’s sensitivity to the case of database objects, such as table
names, depends on the sort order installed on Adaptive Server . You can change
case sensitivity for single-byte character sets by reconfiguring the Adaptive
Server sort order. For more information, see the System Administration Gu id e.

About This Book

SELECT,

Terms

Accessibility
features

The following terms appear repeatedly throughout this book. For more detailed
information about these and other terms, see the Glossary.

• /work/sybase – is given as an example o f the Sybase installation directory.

• T ext ed itor – refers to an ASCII text editor or an y editor that can save files

to text format.

This document is available in an HTML version that is specialized for
accessibility. You can navigate the HTML with an adaptive technology such as
a screen reader, or view it with a screen enlarger.

Adaptive Server Enterprise and the HTML documentation have been tested for
compliance with U.S. government Section 508 Accessibility requirements.
Documents that comply with Section 508 generally also meet non-U.S.
accessibility guidelines, such as the World Wide Web Consortium (W3C)
guidel in e s fo r Web site s.

The online help for this product is also provided in HTML, which you can
navigate using a screen reader.

Note You might need to configure your accessibility tool for optimal use.

Some screen readers pronounce text based on its case; for example, they
pronounce ALL UPPERCASE TEXT as initials, and MixedCase Text as
words. You might find it helpful to configure your tool to announce syntax
convent ions. Consult the documentation for your t o ol.

Configuration Gu ide xv

For information about how Sybase supports accessibility, see Sybase

Accessibility at http://www.sybase.com/accessibility

. The Sybase Accessibility

site includes links to information on Section 508 and W3C standards.

If you need help

Each Sybase install ation that has pur chased a support contract has one or more
designated people who are authorized to contact Syb ase Technical Support. If
you cannot resolve a probl em using the manuals or onlin e help, please have the
designated person contact Sybase Technical Support or the Sybase subsidiary
in your area.

xvi Adaptive Server Enterprise

CHAPTER 1

Introduction

Sybase Adaptive Server Enterprise for UNIX is a full-featured Adaptive
Server that runs on the following platforms:

• HP-UX

•IBM AIX

•Sun Solaris

• Linux 32 -bit

Note The instructions in this book assume that Adaptive Server is

installed and running. For information about installing and starting
Adaptive Server, as well as for an overview of Adaptive Server, see the
Adaptive Server Installation Guide for your platform.

This chapter provides an overview of how to configure Adaptive Server
and the steps you need to take to customize it for your use.

Topic Page

About Adaptive Server 1
System-specific issues 2
System user roles 3
Environment variables 3
Adaptive Server devices and system databases 5
Client/server communication 11
Changing Adaptive Server configuration 12
Languages other than U.S. English 13
Adaptive Server specifications 13

About Adaptive Server

Adaptive Server performs data management and transaction functions,
independent of client applications and user interface functions.

Configuration Gu ide 1

System-specific issues

Adaptive Server also:

• Manages multiple databases and multiple users

• Keeps track of the data’s location on disks

• Maintains the mapping of logical data des cripti on to physical data storage

• Maintains data and procedure caches in memory

Adaptive Server uses these auxiliary programs to perform dedicated tasks:

• Backup Server manages database load, dump, backup, and restoration
activities.

• Monitor Server keeps track of performance data.

• Historical Server obtains performance data f rom Monitor Server and saves
the data in files for use at a later time.

• XP Server stores the extended stored procedures (ESPs) that allow
Adaptive Server to run operating-system and user-defined commands.

System-specific issues

Adaptive Server runs on a variety of hardware an d operating system plat forms.
System-specific issues do not affect the basic functionality of Adaptive Server ,
but there are differences among platform implementations. These differences
may include:

• Adaptive Server configuration

• Changes to the operating system that enable or enhance Adaptive Server
performance

• The structure of entries in the interfaces file

• Options for selecting database devices

• Operating system commands or utilities that simplify or automate routine
system administration tasks

• Operating system utilities for monitoring Adaptive Server performance

System-specific issues are described in this document. For more information
about system-specific issues, see the Installation Guide and release bulletin for
your platform.

2 Adaptive Server Enterprise

System user roles

The Adaptive Server installation and setup process defines various user roles.
Different user roles have different responsibilities and privileges. These user
roles clarify the way Adaptive Server is to be integrated into your system:

• Operating system administrator – the individual who maintains the

operating system. This individual has superuser or “root” privileges.

• System Administrator – the indivi du al in charge of Adaptive Server

system administration, creating user accounts, assigning permissions on
databases, and creating new databases. At installation tim e, the System
Administrator’s login name is “sa”. The “sa” login is not a UNIX login.
The “sa” login is specific to Adaptive Server and is used to log in to
Adaptive Server using the

• “sybase” login – the “sybase” login is a UNIX login that owns all the

Sybase installation directories and files, sets permissions on those
directories and files, and performs the installation and upgrading of
Adaptive Server. This login is preferred, but not required.

CHAPTER 1 Introduction

isql command.

Environment variables

It is crucial to the operation of Sybase products that the system environment
variables be set correctly.

Environment variables are set in the user’ s environmen t either interactively or
by including them in the user’s .login and .cshrc files (for C shell) or .profile
file (for Bourne shell). The installation instructions in this guide explain when
to set these variables.

Note As part of the installation, the installer setup these environment variables

in SYBASE.csh and SYBASE.sh files. You can source the file to set their
environment.

• DSLISTEN – defines the name Adaptive Server uses to listen for client

connections if no name is given during the Adaptive Server start-up. If
DSLISTEN is not set, and no name is given during the Adaptive Server
start-up, the Adaptive Server name defaults to SYBASE.

Configuration Gu ide 3

Environment variables

• DSQUERY – defines the Adaptive Server name that client programs
attempt to connect to if no Adaptive Server is specified with a command
line option. If DSQUERY is not set, and you do not supply the Adaptive
Server name with a command line option, clients attempt to connect to
SYBASE.

• SYBASE – defines the path of the Sybase installation directory. The
installation program sets up the variable SYBASE to point to th e release
directory specified during installation.

• SYBASE_ASE – defines the subdirectory of the Adaptive Server
component.

• SYBASE_OCS – defines the subdirectory to which Open Client™ is set.

• SYBASE_ FTS – defines the subdirectory for the full-text search
components.

• SYBASE_SYSAM – points to the license-management software
directory.

• PATH – specifies directory path to search for executables. The Sybase
executables are located in the installed_components /bin directory. When
using the source files SYBASE.csh or SYBASE.sh, the following paths are
prepended to PATH:

$SYBASE/$SYBASE_ASE/bin:$SYBASE/$SYBASE_OCS/bin

• LD_LIBRAR Y_PATH – this variable specifies the directory to search for
shared libraries. The Sybase shared libraries are located in the installed
component’s /lib directory.

When using the source files: SYBASE.csh or SYBASE.sh, the following
paths are prepended to the LD_LIBRARY_PATH environment variable:

$SYBASE/$SYBASE_ASE/lib:$SYBASE/$SYBASE_OCS/
lib:$SYBASE/SYBASE_FTS/lib,etc.

• LIBPATH – on the IBM RS/6000 platform, this variable specifies which
directory to search for libraries.

When using the source files: SYBASE.csh or SYBASE.sh, the following
paths are prepended to the LIBPATH environment variable:

$SYBASE/$SYBASE_ASE/lib:$SYBASE/$SYBASE_OCS/
lib: $SYBASE/SYBASE_FTS/lib, etc.

• SHLIB_PATH – on HP-UX platforms, this variable specifies which
directory to search for libraries.

4 Adaptive Server Enterprise

CHAPTER 1 Introduction

When using the source files: SYBASE.csh or SYBASE.sh, the following
paths are prepended to the LIBPATH environment variable:

$SYBASE/$SYBASE_ASE/lib:$SYBASE/$SYBASE_OCS/
lib: $SYBASE/SYBASE_FTS/lib, etc.

Adaptive Server devices and system databases

Devices are files or portions of a disk that are used to store databases and
database objects. You can initialize d e vi ces using raw disk partitions or
operating system files.

Adaptive Server requires the following devices:

•

master – to store system databases.

•

sybsystemdb – to store inform at ion about distributed transaction.

•
The master, sybsystemdb, and sysprocsdev devices are created when you

create a new Adaptive Server.

The master device

The master device contains the following databases:

•

•

•

sysprocsdev – to store system procedures.

master – controls the operation of Adaptive Server as a whole and stores

information about all users, user databases, devices, objects, and system
table entries. The

master database is contained entirely on the master

device and cannot be expanded onto any other device.

model – provides a template for new user databases. The model database

contains required system tables, which are copied into a new user database
with the

tempdb – the work area for temporary databases in Adaptive Server.

Adaptive Server supports multiple

create database command.

tempdbs. See “create temporary

database” in the T-SQL User’s Guide. Each time Adaptive Server is
started, the

tempdb database is cleared and rebuilt from the model

database.

Configuration Gu ide 5

Adaptive Server devices and system databases

• The sample databases, pubs2 and pubs 3, are stored on the master device
at installation, but should be moved to a user-defined device after
installation.

Note For recovery purposes, Sybase recommends that you do not create

other system or user databases or user objects on the master device.

The sybsystemdb device

For new installations the master device also contains the sybsystemdb
database. T he
stores information abou t transactions in progress, and which is also used dur ing
recovery.

The

sybsystemdb database is required to support distributed transaction

management (DTM) features. B efore inst allation, mak e sure you have eno ugh
space available on the default segment to support

sybsystemdb device stores the sybsystemdb database, which

sybsystemdb.

The sysprocsdev device

The sybprocsdev devices stores the sybsystemprocs database, which contains
most of the Sybase-supplied system procedures. System procedures are a
collection of SQL statements and flow-of-control statements that perform
system tasks, for example,

The system procedur es that are need ed durin g recovery situations are stored in
the

master database.

Note sysprocsdev is the default system name for this device. Howev er, it is

frequently referred to as the

sybsystemprocs database.

Optional devices and databases

The devices and databases described in the following sections are optional.

The sample
databases

The sample databases are:

sp_configure.

sybsystemprocs device, since it stores the

6 Adaptive Server Enterprise

CHAPTER 1 Introduction

•

pubs2 and pubs3 – provided as learning tools for Adaptive Server. pubs2

is used for most of the examples in the Adaptive Server documentation;
other examples use the

pubs3 database. Both are available in U.S. English

versions of Adaptive Server.

•

interpubs – contains French and German data.

•

jpubs – contains Japanese data.

For information about installing the sample databases, see the Installation
Guide for your platform, Chapter 3, “Post-Installation Tasks.”

For information about the contents of the sample databases, see the
Tr ans act -S Q L User’s Guide.

The sybsecurity
device and databa se

dbccdb databa se

The sybsecurity device is created as part of the auditing installation process.
The

sybsecurity device stores the sybsecurity database and the auditing system

procedures with which you can configure au diting for your system.
The auditing system records system s ecurity information in an Adaptive Server

audit trail. Y ou can use this audit trail to monitor the use of Adaptive Server or
system resource s .

For instructions on configuring Adaptive Server for auditing, see Chapter 10,
“Adding Optional Functionality to A daptive Server.” For information about
installing and using the auditing system, see Chapter 12, “Auditing,” in the
System Administration Guide.

The database consistency checker (dbcc) provides commands for checking the
logical and physical consist ency of a dat abase. Th e
results of

dbcc checkstorage records consistency information for the target database,

dbcc when dbcc checkstorage or dbcc check verify i ng is used.

operation activity, and the results of the operation in the
Stored in the database are

dbccdb and for generating reports on the results of dbcc checkstorage

dbcc stored procedures for creating and maintaining

dbccdb database stores the

dbccdb database.

operations.
For information on installing and using

Database Consistency,” in the System Administration Guide.

sybmgmtdb database

Configuration Gu ide 7

sybmgmtdb is a Job Scheduler database.

dbccdb, see Chapter 25, “Checking

Adaptive Server devices and system databases

All the job, schedule, and scheduled job information, and data needed by the
Job Scheduler task for internal processing is stored in the
Most access to data in the
stored procedures make the data available to the GUI, the JS Agent and the
command-line interface. Only the Job Scheduler task accesses data directly
from the

sybmgmtdb database.

sybmgmtdb database.

sybmgmtdb database is via stored procedures. The

For more informati on ab ou t

sybmgmtdb and Job Scheduler , see Job Scheduler

User’s Guide.

dsync option on by default for database device files

The dsync option ensures Adaptive Server can recover data from devices on th e
file systems. By default, Adaptive Server enables
However,
that experience high write activity. The
the

disk init, disk reinit, and sp_deviceattr commands.

Note The dsync option is ignored for raw devices.

dsync may cause performance degredation for file system devices

dsync option can be set or reset using

When installing a new Adaptive Server, by default
system devices.

When upgrading from ASE 12.0 or earlier releases on a UNIX server that
stored databases on UNIX file system devices, by default

•

on for the master device

dsync for file system devices.

dsync is set on for all file

dsync is set:

•

off for all other devices

Immediately after upgrade, set the
also

sp_deviceattr and sp_helpdevice in the Reference Manual

Warning! Data corruption may occur if dsync option is no t set im mediately

after upgrade.

8 Adaptive Server Enterprise

dsync option for the file system devices. See

CHAPTER 1 Introduction

Determining the location, type, and size of a database device

Adaptive Server requires several database devices. Table 1-1 below shows

baseline values for each of the devices. See the release bulletin for any last
minute changes to these values.

Table 1-1: Adaptive Server database devices

Minimum

Device Purpose

master Stores system

databases

sysprocsdev

(also called the

sybsystemprocs

device)

Stores the

sybsystemprocs

database

size

24MB for 2K pages
45MB for 4K pages
89MB for 8K pages
177MB for 16K

pages
120MB 120MB (plus any

Minimum
recommended size

30MB
60MB
120MB
240MB

space for holding
stored procedures that
you have created)

sybsystemdb Transaction

processing

sybsecurity (optional) Required for

auditing

For Solaris, HP-UX, IBM AIX, and Linux

For all databases you can use either a raw partition or a file.
Sybase Adaptive Server supports the database devices on NFS- and

CIFS-mounted devices with Network Appliance Filers for storing data.
Network appliance filers provide the same performance and data integrity as
raw devices. There are no changes need ed to the operating system or to Sybase
Adaptive Server to use network appliance filers.

NFS mounted devices have been tested on Solaris, HP-UX, IBM AIX, and
Linux.

3MB for 2K pages
6MB for 4K pages
12MB for 8K pages
24MB for 16K pages
5MB 7MB; more for

5 – 24MB

specialized auditing

For All Platforms

You may need to repartition the disk you choose. Contact your operating
system administrator for assistance.

Configuration Gu ide 9

Adaptive Server devices and system databases

When preparing a raw partition device, follow these guidelines:

• Do not initialize a database device on the partition that contains your
Sybase installation software. Doing so destroys all exis ting files on that
partition.

• A raw partition designated for use by Sybase cannot be mounted for use
by the operating system for any other purpose, such as for file systems or
swap space.

• After a Sybase configuration utility or the

disk init command has initialized

a portion of a partition as a database device, the entire partition cannot be
used for any other purpose . Any space left on the partition beyond the s ize
specified for the device becomes inaccessible, unless you drop and re­create the device.

• For best performance, place the Sybase software and all disk devices,
including the

master device, on the same machine.

• T o avoid any possibility of using a partition that contains the partition map,
do not use cylinder 0.

v Choosing a raw partition

1 Determine which raw partitions are available.
2 Determine the sizes of the raw partitions.
3 From the list of available raw partitions, select a raw partition for each

device, based on the size recommendations in Table 1-1 on page 9.

4 Verify with the operating System Administrator that the partition you have

chosen is available.

5 Make sure the “sybase” user has read and write privileges to the raw

partition.

Note For more information on choosing a raw partition, see your

operating system documentation.

10 Adaptive Server Enterprise

Client/server communicati on

Adaptive Server communicates with other Adaptive Servers, Open Server™
applications (such as Backup Server), and client software on your network.
Clients can talk to one or more servers, and servers can communicate with
other servers by remote procedure calls.

For Sybase products to interact with one another, each product needs to know
where the others reside on t h e net work . N ames and addr ess e s of every known
server are listed in a directory services file. This information can be stored in a
directory services file two different ways:

• In an interfaces file, named interfaces on UNIX platforms, located in the

$SYBASE installation directory, or

• In an LDAP server
After your Adaptive Server or client software is installed, it can connect with

any server on the network that is listed in the directory services.

CHAPTER 1 Introduction

When you are us ing a client p rogram, and you want to connect with a particular
server, the client program looks up the server name in the directory services
and connects to that server, as shown in Figure 1-1. You can supply the name
of the server by using the DSQUERY environment variable.

On TCP/IP networks, the port number gives clients a way to identify the
Adaptive Server, Open Server , Backup Server , or Monitor Server to which they
want to connect. It also tells the server where to listen for incoming connection
attempts from clients. The server uses a single port for these two services
(referred to as query service and listener service).

Configuration Gu ide 11

Changing Adaptive Server configuration

Figure 1-1: Communicating with a server using interfaces file

During installation, you use the srvbuild utility to create and configure a new
server. The

srvbuild process adds entries to the interfaces file for your new

Adaptive Server, Backup Server, Monitor Server, and XP Server.
For instructions on how to modify existing interfaces file entries using

and

dscp or to create new interfaces file entries for existing servers, Chapter 6,

“Using the Lightweight Directory Access Protocol as a Directory Service.”

Changing Adaptive Server configuration

Use sp_configure to change the configuration of Adaptive Server. To change
the configuration of several servers, enter the
script. For details on us ing

sp_configure, see the System Administ ra t i on Gui de

and the Reference Manual.
For information about configuring languages, character sets, and sort orders,

see Chapter 7, “Customizing Localization for Adaptive Server.”
For information about configuring Adaptive Server to use high availability

features, see Using Sybase Failover in a High Availability Environment.
For information about configur ing Adap tive Server for distributed transaction

management (two-phase commit), see the Using Adaptive Ser ver Dist ri bu t ed
T ransaction Management Features.

sp_configure information in a

dsedit

12 Adaptive Server Enterprise

Languages other than U.S. English

If you are running srvbuild in a langu age other than U.S. English, veri fy that any
input you provide uses a character set that is supported by the us_english
character set.

Note The us_english character set does not support accent marks, such as

tildes (~) and umlauts (ü). This prevents
sets that use these characters.

For more information about languages, character sets, and sort orders , see the

Installation Guide for your platform. For more information on srvbuild, see the
Utility Guide.

CHAPTER 1 Introduction

srvbuild from supporting the character

Adaptive Server specifications

Database specifications

Databases per Adaptive
Server

Maximum database size • 2K page server – 4TB

Minimum allowable

sybsystemprocs database

Maximum size of a
database device (disk
partition)

Maximum number of
database devices per server

Maximum number of
devices or device pieces
per database

Maximum number of
segments per data ba s e

Maximum number of login
IDs per server

A maximum of 32,767
databases per server

• 4K page server – 8TB

• 8K page server – 16TB

• 16K page server – 32TB
124MB Required for an upgrade

24

2
(4TB)

31

2

Unlimited Limited by available memory

31

2147516416

If the Operating System supports
file sizes up to 4TB, th en Adaptive
Server supports file system devices
up to 4TB

Configuration Gu ide 13

Adaptive Server specifications

Maximum number of users

2146484223

per database
Maximum number of

1032193

groups per database

Table specifications

User object s pe r da ta ba s e 2

31

– 255
Indexes per table 250 (one clustered index)
Rows per table Limited by available

storage

Columns per composite

31

index
Creation of clustered i nd ex 1.2*(x + y)

x = total data space in
table,
y = sum of space of all
nonclustered indexes on
table,
and 20 percent overhead
for logging

Maximum siz e of ob je ct

255

name

Maximum 2

32

For sorted data, approximately 20
percent of the table size needed

Query specifications

Maximum number of tables
participating in a query, for a
query without a union, or for
each side of a union in a qu ery

64 Maximum of 50 user t abl e s ,

including result tables, tables
referenced by views (the view
itself is not counted) correlations
and self-joins; maximum of 14
worktables

Maximum number of tables in a
“union” query

256 Includes up to 50 user tables and 14

work tables on every side of the
union, for a total of u p to 256 tables
across all sides of the union.

Maximum number of databases
participating in one transaction

Unlimited Includes database where

transaction began, all database s
changed during tr ansaction, and

tempdb, if it is used for results or

worktables

14 Adaptive Server Enterprise

CHAPTER 1 Introduction

Practical number of databases
participating in one query

Maximum number of tables with
referential integrity constraints
for a query

Procedure specifications

Number of buffers and
procedure buffers

Minimum memory required per
stored procedur e

Maximum number of parameters
per stored procedure

Adaptive Server extended-limit capabilities vary by type of table and the
database logical page size. Table 1-2 lists the column and row limits for
allpages-locked (APL) tables.

16 Includes each occu rrence of each

database queri ed and
is used for results or worktables

192

Configurable Limited by amount of RAM an d

maximum size of shared memo ry
segment

2K

2048

tempdb, if it

Table 1-2: Allpages-locked (APL) tables

Maximum APL table
limits

Fixed-leng th co lu mn 1024 1960 bytes 4008 bytes 8104 bytes 16296 bytes
Variable-length column 254 1948 bytes 3988 bytes 8068 bytes 16228 bytes

Number of
columns

Column size
2K page

Column size
4K page

Column size
8K page

Column s ize
16K page

Table 1-3 lists the column and row limits for data-only-locked (DOL) tables.

Table 1-3: Data row and data page tables.

Maximum DOL table
limits

Fixed-leng th column 1024 1958 bytes 4006 bytes 8102 bytes 16294 bytes
Variabl e-length column 1024 1954 bytes 4002 bytes 8089 bytes 16290 bytes

Number of
columns

Column size
2K page

Column size
4K page

Column size
8K page

Column size
16K page

Database space requirements depend upon the log ical page size of the server.If
your

model database is larger than the minim size listed below, then the

minimum size of the database is equal to the

model database. Table 1-4 lists the

minimum size for each database.

Table 1-4: Database requirements for varying page sizes

Databases 2K page 4K page 8K page 16K page

master database 13MB 26MB 52MB 104MB

Configuration Gu ide 15

Adaptive Server specifications

Databases 2K page 4K page 8K page 16K page

model database 3MB 6MB 12MB 24MB
tempdb databa se 4MB 6MB 12MB 24M B
sybsystemdb database 3MB 6MB 12MB 24MB

Larger logical page sizes can contain more data. Table 1-5 lists the maximum
data for each logical page size.

Table 1-5: Data limits for tables according to page size

Tables 2K page 4K page 8K page 16K page

Bytes per index key 600 1250 2600 5300
User-visible row length

DOL table
User-visible row length

APL table

1958 4006 8102 16294

1960 4008 8104 16296

16 Adaptive Server Enterprise

CHAPTER 2

Overview

Starting and Stopping Servers

This chapter describes how to start and stop Adaptive Server, Backup
Server, Monitor Server, and XP Server.

Topic Page

Overview 17
Starting servers 18
Starting servers when the operating system restarts 20
Starting XP Server after initial installation 24
Stopping servers 24

The methods described in this chapter are used to start Adaptive Server,
Backup Server, and Monitor Server after a shutdown for database
maintenance, because of an operating system crash, or for other reasons.

XP Server is not started by the installation process. XP Server is started by
Adaptive Server when an XP command is issued through

You can use Sybase Central to start and stop servers manually or
automatically. For more information about Sybase Central, see “Chapter
1, Overview of System Administration,” in the System Administration
Guide.

Requirements for starting servers

To start a server, your user account must have:

• Anyone with access to the database servers (execute privileges) and
database devices (read/write privileges).

• Access to Adaptive Server distribution files

isql.

Configuration Gu ide 17

Starting servers

• The system envi ron ment v ari able s dis c us sed in Chapter 1, “Introduction”

• Access to SySAM licenses. For more information, see the Sybase Softwar e

The installation program creates the interfaces file and system environment
variables when you install servers on your computer.

Starting servers

You can start Adaptive Server, Backup Server, or Monitor Server from the
command line by usin g RUN _server_name files and
You can customize the starting options.

You can also customize the start up options by editing the RUN_server_name.

Asset Management User’s Guide.

startserver commands.

Server start-up parameter s

The default start-up parameters are stored under
$SYBASE/$SYBASE_ASE/install/RUN_server_name, where server_name is
the name of the server you installed.

Backup Server, Monitor Server, and Hi storical Server server names are
appended with “_back”, “_mon”, and “_hs”, respectively.

Ta ble 2-1 lists the default star t- up parameters for Adaptive Server.

Table 2-1: Default Adaptive Server start-up parameters

Switch Description

-d $SYBASE/data/master.dat Location of the master device file

-s server_name Name of the Adaptive Server

-e $SYBASE/$SYBASE_ASE

/install/errorlog

-M $SYBASE/$SYBASE_ASE Directory that stores shared memory files

-N$SYBASE/$SYBASE_ASE/sysam/

<srv_name>.properties

Location and name of the error log file

Location and name of li cense cache file.

18 Adaptive Server Enterprise

Changing start-up parameters

Y ou cannot change any of these default start-u p parameters unless you directly
edit the $SYBASE/$SYBASE_ASE/install/RUN_ server_name file. You can
also specify additional start-up parameters within the
$SYBASE/$SYBASE_ASE/install/RUN_ server_name file.

Additional start-up parameters include any valid server command line options
listed for the

databaserver and backupserver descriptions in the Utility Guide.

For a description of start-up parameters for Monitor Server and Historical
Server, see the Adaptive Server Enterprise Monitor documentation.

Using a RUN_server_name file

Each time a new Adaptive Server, Backup Server , or Monitor Server is created,
the

srvbuild program creates a RUN_server_name file that contains the

information required to restart that server. RUN_server_name files are created
in the $SYBASE/$SYBASE_ASE/install directory. For Adaptive Server, the
RUN_server_name file is na med RUN_server_name, where servername is the
name of the server.

CHAPTER 2 Starting and Stopping Servers

For example, the RUN_server_name file name for an Adaptive Server named
TEST is RUN_TEST.

For Backup Server and Monitor Server , the RUN_server_name files are named

RUN_servername_back and RUN_servername_mon, respectively, where
servername is the name of the server.

Warning! Do not delete the RUN_server_name file that is created in

$SYBASE/$SYBASE_ASE/install. This file is used to restart servers when you

customize your installation. If you need the RUN_server_name file in another
location, make a copy of the original RUN_server_name file in the new
location.

The RUN_server_name file for a server named SYBASE is named
RUN_SYBASE. If the RUN_server_name file for your current Adaptive Serv er
is named RUN_server_name, you must change the name to RUN_SYBASE
during the upgrade process.

Configuration Gu ide 19

Starting servers when the operating system restarts

Using the startserver command

To start a server from the command line, enter:

$SYBASE/$SYBASE_ASE/install/startserver [ -f RUN_server_name file ]

where $SYBASE/$SYBASE_ASE/install/startserver is the full path name of the

startserver utility, and RUN_server_name file is the full path name of the

RUN_server_name file (usually
$SYBASE/$SYBASE_ASE/install/RUN_server_name).

If your Adaptive Server is named SYBASE, the RUN_server_name file
specification is optional.

Y ou mus t have read and write permiss ions on the master device for an Ad aptive
Server to start it with
the Adaptive Server Utility Guide.

startserver. For more information about startserver, see

Using the monserver and backupserver commands

Use the monserver command to start Monitor Server from the UNIX command
line. For details, see the Adaptive Server Enterprise Monitor Server User’s
Guide.

Starting servers when the operating system restarts

This section describes how to configure your operat ing system for automatic
restart of Adaptive Server and Backup Server.

On production systems, Adaptive Server, Backup Server, and Monitor Server
should restart automatically when the UNIX operating system starts. This is
accomplished by making an entry for the server in the operating system start­up script. Monitor Server must be listed after Adaptive Server in the start-up
script.

For more information on starting Monitor Server at operating system restart,
see the Monitor Server User’s Guide.

Note The startup script must set up all the required Sybase environment

variables, or source SYBASE.csh or SYBASE.sh, before starting the server.

20 Adaptive Server Enterprise

For HP-UX

CHAPTER 2 Starting and Stopping Servers

In HP-UX versions 10.0 and later , you cannot edit comman ds in the /etc/rc file,
so the System Administrator must create a script that executes when the
operating system starts or shuts down.

For more information about

rc (1M), see the HP-UX manual page. You can

model your script after the HP-UX template file /sbin/init.d/template.
After creating the start-up and shutdown script, place it in the directory

/sbin/init.d. Execution scripts placed in this directory have symbolic links to
directories /sbin/rcn.d where n is the system run level. The linked scripts in
/sbin/rcn.d are used to control the sequencing order of the execution scripts.

For IBM RS/6000

On production systems, you can restart Adaptive Server automatically
whenever the UNIX operating system restarts. T o have Adaptive Server restart
automatically, place the

Here is a suggested format for an Adaptive Server start- up command to add to
/etc/inittab:

"sybase:2:wait:/release_directory/install/startserver -f \ RUN_servername
/dev/console 2>&1"

Where release_directory is the full path to the Sybase installation directory
(specified as the SYBASE environment variable), and RUN_servername is the
RUN_server_name file for the server you are starting.

startserver command in the /etc/inittab file.

Make sure that the entry for starting Adaptive Server follows any entry for
/etc/rc.tcpip and /etc/rc.nf s in the /etc/inittab file. All network resources must

be available before you start Adaptive Server; otherwise, Adaptive Server does
not start. Also, your server does not start if the network is not running.

Slow start-up of network operations can also prevent Adaptive Server from
starting, even when the commands in the /etc/rc.tcpip file are in the correct
order. You can designate a period of time for Adaptive Server to wait before
starting by inserting a
the RUN_server_name file. The

Configuration Gu ide 21

sleep command before the server start-up command in

sleep command is in the form:

Starting servers when the operating system restarts

sleep seconds_of_rest

Note To enable restart of a Backup Server when the operating system starts,

add a Backup Server start-up command to /etc/inittab. Use the path of the
Backup Server RUN_server_name file in this command.

For Sun Solaris and Linux

Before you set Adaptive Server o r B acku p Server to start automatically, make
sure that all network resources are available. Your server does not start if the
network is not running. Be sure that the entry for restarting the server follows
any commands in the rc directo ry for starting netw ork operat ions. Slow start­up of network operations may prevent servers fro m starting, even if commands
are in the correct order in the rc directory . You may want to designate a period
of time for your server to wait before starting by inserting a
the beginning of the l inked RUN_server_name file you created.

sleep command at

To configure your operating system for automatic restart of Adaptive Server
and Backup Server:

1 Create a start-up script file with contents like the following:

$SYBASE/$SYBASE_ASE/install/startserver

-f

$SYBASE/$SYBASE_ASE/install/RUN_servername

where $SYBASE/$SYBASE_ASE/install/startserver is the full path name
of the

startserver utility, and

$SYBASE/$SYBASE_ASE/install/RUN_servername is the full path name
of the RUN_server_name file for the server.

2 C opy the script to the /etc/init.d directory, using syntax like the following:

cp script_name /etc/init.d/script_name

3 Review the contents of the /etc/inittab file to determine the default run

level for your operating system. The
run level, which is usually 2 or 3 for Sun Solaris and 5 for Linux

4Use the

ln command to create a hard link from the RUN_server_name file

to the appropriate run contr ol (r c) d irectory , rc#, where # is the default run
level obta ined in step 2.

initdefault entry specifies the default

Use syntax like the following for Sun Solaris:

22 Adaptive Server Enterprise

CHAPTER 2 Starting and Stopping Servers

ln /etc/init.d/script_name /etc/rc#.d/S##script_name

For Linux:
Use

ln -s to create symbolic links from the script name to the appropriate

run control (rc) directory, rc# where # is the run level. Use syntax like the
following:

ln -s /etc/init.d/script_name /etc/rc#.d/S##script_name

When you type the command to create this link, add an uppercase “S” and
a two-digit sequence number preceding the name of the script file. “S”
indicates a start-up file. The s equence number is necessary becaus e files in
the rc directory are executed in order of their numbers . This file should be
executed last, so you should use a sequence number that follows all
existing numbers in A SCII order.

You can perform an

ls command on the rc directory to view existing

sequence numbers. For example:

ls /etc/rc3.d/S*

returns:

/etc/rc3.d/S10syslog
/etc/rc3.d/S15nfs.server
/etc/rc3.d/S21rfs

If your scr ipt is named sybstart, type the following:

ln /etc/init.d/sybstart /etc/rc3.d/S77sybstart

In this example, you can use any number greater than 27 in place of 77.
For Linux:
You can perform an ls comman d on th e r c d irectory to view existing sequence

numbers. For example:

ls /etc rc5.d/S*

returns:

/etc/rc5.d/S12syslog

/etc/rc5.d/S14nfslock

/etc/rc5.d/S27ypbind

and so on. If your script is named sybstart, type the following:

In this example, you can use any number greater than 27 in place of 99.

Configuration Gu ide 23

ln -s /etc/init.d/sybstart /etc/rc5.d/S99sybstart

Starting XP Server after initial installation

Starting XP Server after initial installation

If you install Adaptive Server and XP Server in the same build session, srvbuild
automatically adds information about the XP Server to the
Adaptive Server. If you install XP Server in a different build session than the
Adaptive Server installation, you are prompted during the XP Server
installation process to supply the name of the related Adaptive Server and the
System Administrator ’s name and password. This information is required by
Adaptive Server to start XP Server.

If you do not su pply this informa tion during the i nstallation process , XP Server
cannot run. When yo u execute an exte nded stored pro cedure (ESP), you see an
error message similar to the following:

Msg 11018, Level 16, State 1:
Procedure 'xp_cmdshell', Line 2
XP Server must be up for ESP to execute.

To add this required information to the sysservers table manually, enter:

sysservers table of

sp_addserver servername_XP, NULL, servername_XP

where servername is the name of the Adaptive Server.

Stopping servers

Only the System Admini strator has permissio n to issu e a shutdo wn command.
Using a shutdown command minimizes the amount of work that automatic
recovery needs to do when the servers are restarted.

The preferred method of stopp ing Adap tive Server o r Backup Server is to us e
the Transact-SQL

sms_shutdown command.

Stopping Adaptive Server

To shut down Adaptive Server:

shutdown command. For Monitor Server, use the

1Use

Administrator privileges:

24 Adaptive Server Enterprise

isql to log in to an Adaptive Server account with System

isql -Usa -Ppassword -Sserver_name

CHAPTER 2 Starting and Stopping Servers

2Enter:

1> shutdown
2> go

The default for shutdown uses the with wait option, which allows Adaptive
Server to finish executing SQL statements or procedures, perf orm a checkpoint
in each database, disable new logins, and perform other shutdown tasks.

Issuing the

Server SHUTDOWN by request.The SQL Server is terminating

this process.

CT-LIBRARY error:

This is normal behavior. If the message indicates that Adaptive Server is
waiting for processes to complete, and you must stop Adaptive Serv er
immediately, you can use
currently executing statements to finish, nor performs checkpoints in every
database.

Note Using the shutdown with nowait command is not recommended; use it

only when necessary.

Stopping Backup Server

To shut down a Backup Server:
1Use

shutdown command prints a message like this to the sterr file:

shutdown with nowait which neith er waist f or

isql to log in to a server with System Administrator privileges.

2Enter:

After you shut down a Backup Server, you must wait at least 30 seco nds before
restarting it.

Issuing the
stderr file:

Configuration Gu ide 25

1> shutdown SYB_BACKUP
2> go

shutdown command prints a message similar to the following to the

Backup Server: 3.48.1.1: The Backup Server will go down

immediately.

Terminating sessions.

Stopping servers

This is normal behavior . I f a message indicates that Adaptive Server or Backup
Server is waiting for processes to complete, and you must stop Adaptive Server
or Backup Server immediately, use

shutdown with nowait, which neither waits

for currently executing statements to finish, nor perfo rms checkpoints in every
database.

Using

shutdown with nowait for Backup Server can cause inconsistent or

incomplete dumps and loads. Use this command only when necessary.
For more information on the

Stopping Monitor Server

To release resources, you must shut down Monitor Server before you restart
Adaptive Server. If Adaptive Server stops, make sure that Monitor Server is
shut down before you restart Adaptive Server . Otherwise, Adaptive Server may
not be able to allocate enough resources to restart.

If the Monitor Server heartbeat feature is in effect, Monitor Server
automatically detects the termination of Adaptive Server within th e specified
period and shuts itself down. Therefore, before attempting to restart Adaptive
Server after a shutdown, either wait for the automatic shutdown of Monitor
Server to occur, or explicitly stop Monitor Server.

For more information on stopping Monitor Server, see the Monitor Server
User’s Guide.

shutdown command, see the Reference Manual.

Using the kill command

Warning! Use the kill command to stop Adaptive Server and Backup Server

only as a last resort.

When possible, use the Transact-SQL
command. Do not use
running a checkpoint to ensure that all database changes are written to the
database device. Adaptive Server may also exit without removing associated
shared memory files and network handlers.

Because Adaptive Server and Backup Server are background processes, they
can be killed from the operating system by their owner or by “root” with the
UNIX

26 Adaptive Server Enterprise

kill command. The syntax is:

shutdown or shutdown with nowait

kill with the -9 flag, because it exits the server without

CHAPTER 2 Starting and Stopping Servers

kill pid

where pid is the process identification of any dataserver or backupserver
process, as determined by the

showserver command. Killing one engine for a

particular Adaptive Server kills all engines for that server.
If more than one Adaptive Server is running on the same system, be careful that

the engine you kill is associated with the correct Adaptive Server. If your
Adaptive Server is configured to use multiple engines (CPUs), each engine has
an associated operating system process. The correct way to kill a multi-engine
server is to specify the process ID for engine 0.

This

showserver output shows the processes for a four-engine server:

showserver

UID PID PPID C STIME TTY TIME COMD
jorge 3320 1 80 10:31:40 pts/4 302:15 dataserver -dteamster
jorge 3321 3320 80 10:31:45 pts/4 324:47 dataserver -ONLINE:1
jorge 3322 3320 80 10:31:45 pts/4 326:02 dataserver -ONLINE:2
jorge 3323 3320 80 10:31:45 pts/4 328:56 dataserver -ONLINE:3

This example shows four running dataserver processes with operating system
process identifications (PID) 3320, 3321, 3322, and 3323 (
executable form of the Adaptive Server program.)

Child engine processes for the dataserver have the
Each child engine has a parent process identification (PPID) that is equal to the

process identification (PID) of the paren t. In the example abo ve, the PID of the
parent server is 3320. The other three engines spawned by the parent process
have the same PPID.

If the PPIDs appear to be unrelated, and there is more than one
process, then more than one Adaptive Server is running on the system.

Shutdown and shared memory files

When Adaptive Server starts, it creates SERVER_NAME.krg file in
$SYBASE/$SYBASE_ASE dir ecto ry to store information about shared memo ry

segments that it uses.

dataserver is the

-ONLINE: argument.

dataserver

Configuration Gu ide 27

Stopping servers

If Adaptive Server is configured with a memory size that is greater than the
MAXSHMSEGSIZE parameter in the operating system then Adaptive Server
may create additional shared memory segments and for every additional shared
memory segment that it creates, an additional file with

SERVER_NAME.srg[N] (where N ranges from 0 – N), is created under
$SYBASE/$SYBASE_ASE.

When Adaptive Server is shut down in a normal manner, the shared memory
files are automatically removed. If Adaptive Server crashes or is stopped with
the

kill -9 command, these files are not deleted. You need read and write

permissions on these files to restart Adaptive Server after a crash or a

kill -9

command, because Adaptive Server must be able to overwrite the previously
created shared memory files.

If Adaptive Server or Backup Server is killed abnormally it also leaves shared
memory segments. Use the

ipcs and ipcrm commands to identify and r emo ve

these shared memory segments that have “NATTACH” count as “0”.
See the UNIX man pages for more information about

ipcs and ipcrm.

28 Adaptive Server Enterprise

CHAPTER 3

Configuring the Operating
System

This chapter discusses the operating system configuration settings that
you can adjust after installing or upgrading Adaptive Server . Unless stated
otherwise, the information pertains to all supported UNIX platforms.

Topic Page

Setting environment variables 29
Configuring new servers with srvbuild 30
Using the stty setting 33
Restoring correct permissions 34
File descriptors and user connections 34
Enabling asynchronous disk I/O 38
Adjusting the client connection timeout period 41
Checking for hardware errors 42
Monitoring the use of operating system resources 43
A sample C shell maintenance script 45

Setting environment variables

Configuration Gu ide 29

Note As part of the installation, the installer creates SYBASE.sh and

SYBASE.csh files in $SYBASE directory f or user to source to s etup all the

environment variables.

It is crucial to the operation of Sybase products that the system
environment variables be set correctly. Environment variables are set in
the user’s environment either interactively or by including them in the
user’s .login and .cshrc files (for C shell) or .profile fi le (for Bourne shell ).

Only the file owner or the “root” user can edit a user’s .login, .cshrc, or
.profile file.

Configuring new servers with srvbuild

You may want to verify that the Adaptive Server environment variables in
Table 3-1 are set correctly.

To check the current value of environment variables, enter the following
command at the operating system prompt:

env

Table 3-1 describes the system environment variables for Adaptive Server.

Table 3-1: System environment variables

Variable Sample value Function

DSLISTEN TEST Used at Adaptive Server start-up ; enables the

DSQUERY TEST Defines the Adaptive Server to which local

PATH /usr/bin:/etc:

/usr/sbin:
/usr/ucb:
/usr/bin/X11:/sbin

specified Adaptive Server to listen for inp ut
from front-end software.

client applications connec t.
Appends the full path to the Adaptive Server

bin subdirectories.

Configuring new servers with srvbuild

To configure new servers with srvbuild:
1 Source SYBASE.csh or SYBASE.sh file in $SYBASE to setup the

environment variables.

2Run $SYBASE/$SYBASE_ASE/bin/srvbuild.
3 Th e Select Servers to Build window display s. Choose the servers you want

to configure by clicking t he boxes o n the lef t. When yo u select eac h of t he
boxes, the server name text field is enabled wh ere you can enter the server
name.

Note The list of “Server type” available for you to choose depends on

what you have installed in $SYBASE.

4 W hen yo u have s elect ed the s ervers you w ant to build , click OK The next

screen or screens displays information depending on what you chose to
configure.

30 Adaptive Server Enterprise

CHAPTER 3 Configuring the Operating System

5 In the Adaptive Server type screen, select the:

• Server page size

• Master device path

• Master device size

• Master database size

• Sybsystemprocs device path

• Sybsystemprocs device size

• Sybsystemprocs database size

•Error log

• Transport type

• Host name

•Port number

In the Edit Advance Adaptive Server Attributes tab, enter:

• Adaptive Server configuration file

• Sybsystemdb device path

• Sybsystemdb device size

• Sybsystemd b database size

• Share memory file directory

• Default backup server

6 To configure Backup Server, in the Backup Server configuration screen,

select the:

•Error log

• Tape configuration file

• Language

• Character set

• Maximum number of network connections

Configuration Gu ide 31

• Maximum number of server connections

• Transport type

• Host name

Configuring new servers with srvbuild

• Port number

7 To configure Monitor Server, select the following information in the

Monitor Server screen:

• Maximum number of connections

•Error log

• Configuration file

• Shared memory directory

• Tr ans port type

• Host name

• Port number

8 In the XP Server type screen, select:

• Tr ans port type

• Host name

• Port number

9 In the Full-Text Search SDS type screen, select:

•Error log

• Collection directory

• Default database

• Language

•Character set

• Minimum number of sessions

• Maximum number of sessions

• Tr ans port type

• Host name

• Port number

10 To configure Job Scheduler, enter the following information in the Job

Scheduler type screen”

• Sybmgmtdb device path

• Sybmgmtdb device size

32 Adaptive Server Enterprise

CHAPTER 3 Configuring the Operating System

• Sybmgmtdb database size

• Transport type

• Host name

•Port number

11 In the “Configure Self Management...” screen, you can enter:

• Enable Self Management

• Self Management user name

• Self Management user password

If you cha nge the Self Management user password after configuring the

Self Management, you need to rerun:

sp_addexternlogin loopback, <Self Management user
name>, <Self Management user name>, <new Self
Management user password>

12 Click Build Servers! to proceed with the servers configuration. srvbuild

displays the configuration status as it builds the servers you selected.
13 After the server configuration com pletes, click Exit to quit

Using the stty setting

Setting the stty tostop option causes a background Adaptive Server to stop as
soon as it tries to write to the terminal. To avoid this error, execute the
following command before starting Adaptive Server:

stty -tostop

If you are redirecting all Adaptive Server output to files, you do not have to
change the

stty setting.

srvbuild.

Configuration Gu ide 33

Restoring correct permissions

Restoring correct permissions

Sybase software files and directories are installed with the correct access
permissions. If you notice that the permissions are no longer correct, you can
restore the correct permissions with the script
$SYBASE/$SYBASE_ASE/install directory.

File descriptors and user connections

The number of user connections used by Adaptive Server cannot exceed the
number of file descriptors available to Adaptive Server on the operating
system. When configuring user connections on Adaptive Server, the System
Administrator should take into account the number of file des criptors available
per process. Although most of the open file descriptors are available for user
connections, a few are used by Adaptive Server for opening files and devices.

setperm_all, located in the

For HP-UX

For AIX

The kernel parameters maxfiles and maxfiles_lim control the number of file
descriptors available to any one process. The limit is 10,000 for HP-UX on a
32-bit system, and 60,000 on a 64-bit system.

T o obtain the current values on the file descriptors use the Korn or Bourne shell

ulimit command: ulimit -n

The number of file descriptors per process is determined by the operating
system paramete r
Adaptive Server can use a maximum of 2000 file descriptors per engine,
regardless of the value of

open_max, see the AIX operating system documentation.

T o obtain the current value of the
shell ulimit command:

ulimit -n

open_max. The default value of open_max is 32767.

open_max. For more information on setting

open_max parameter, use th e Korn or Bourne

34 Adaptive Server Enterprise

For Linux

For Sun Solaris

CHAPTER 3 Configuring the Operating System

The number of file descriptors per process is limited to 10,000. Y ou can set the
number of file descriptors using

For Sun Solaris, you can set both soft and hard limits for file descriptors. The
soft limit can be increased up to the hard limit by the user, but the hard limit
can be increased only by someone with “root” permissions. The soft limit
determines the number of open file descriptors av ailable to an Adaptive Server
engine. The limit is 10,000.

Although most of the open file descriptors are available for user connections,
a few are used by Adaptive Server engines for opening files and devices.

See the System Administr ation Guide for additional information on user
connections.

ulimit.

Displaying current soft and hard limits

To display the current soft limit, for C shells, enter:

limit descriptors

For Bourne shells, enter:

ulimit -n

To display the current hard limit for C shells, enter:

limit -h descriptors

For Bourne shells, enter:

ulimit -Hn

Increasing the soft limit

To increase the soft limit for C shells, enter:

limit descriptors n

For Bourne shells, enter:

Configuration Gu ide 35

File descriptors and user connections

ulimit -Sn new_value

where n is the current value for the soft limit, and new_value is the value to
which you want to increase the soft limit.

Note You can use the preceding commands in your RUN_server_name file to

increase the hard and soft limits. The RUN_server_name file is a Bourne shell
script, be sure to use the Bourne shell versions of these commands in the
RUN_server_name file.

Increasing the hard limit

To increase the hard limit, use a program like the sample program shown in
“Sample program” on page 37.

v Setting up the sample program to increase the hard limit

1 Create file_name.c (where file_name is the name you give the file), by

using an ASCII text editor. Type the text shown in the sample in “Sample
program” on page 37.

2 Compi le th e file:

cc file_name.c -o program_name

where file_name is the name of the source file you created, and
program_name is the name you want to give the program.

3 Change the program’s permissions and ownership so that it will execute as

“root”:

chmod 755 program_name

chown root program_name

where program_name is the name of the compiled program.

4 The “root” user can use the program to start Adaptive Server with

increased user connections by typing the following command at the
operating system prompt:

# program_name dataserver -d master_device_name

36 Adaptive Server Enterprise

CHAPTER 3 Configuring the Operating System

where program_name is the name of the compiled program, and

master_device_name is the full path of Adaptive Server’s master device.

Instead of typing the command at the operating system prompt, you can

add program_name preceding the dataserver command line in the

Adaptive Server RUN_server_name file.

Sample program

Note This is an sample script; modify it as necessary.

The following example shows the sour ce code that you can use to increase the
hard limit:

#include <sys/time.h>
#include <sys/resource.h>
#include <sys/types.h>
/*
** define MAX_CONNECTIONS to a number less than
** 10000. The number defined will then become the maximum
** number of connections allowed by an Adaptive Server.
*/
#define MAX_CONNECTIONS 9999
extern int errno;

main(argc,argv)
char **argv;
{
struct rlimit rlp;
uid_t uid;

rlp.rlim_cur = MAX_CONNECTIONS;
rlp.rlim_max = MAX_CONNECTIONS;

/* set the number of open file desriptors to
MAX_CONNECTIONS */
if (setrlimit (RLIMIT_NOFILE,&rlp) == -1)
{
perror("setrlimit");
exit(1);
}

/* reset the user id to disable superuser
privileges */
uid = getuid();

Configuration Gu ide 37

Enabling asynchronous disk I/O

setuid(uid);

/* run the program indicated as arguments to
this program */
execv(*++argv, argv);
}

For additional information on user connections, see the System Administra tion
Guide.

Enabling asynchronous disk I/O

For HP-UX

This step is mandatory for HP users.
To improve I/O performance on character or raw and block devices, enable

asynchronous I/ O by installing the HP asynchron ous I/O driver from SAM. For
help with installing this driver, contact your operating system administrator or
HP technical support.

Note Before executing the following instructions, shut down Adaptive Server

(or SQL Server).

To enable asynchronous I/O:
1 From the SAM Kernel Configuration menu, choose Drivers and set the

Pending State for asyncdisk to In by adding the driver.
An alternate step could be done by adding the asyncdsk subsystem

keyword to /stand/system.
2 Rebuild the kernel, and reboot the system.
3 Execute the following commands using the

#/etc/mknod/dev/async c 101 4
#chmod 0660/dev/async
#chown <uid> /dev/async
#/etc/setprivgrp <ugrp> MLOCK

userid root:

Where:

<uid> is the identification (user ID)used by the user that is booting

Adaptive Server.

<ugrp> is the user group for the <uid> user ID.

38 Adaptive Server Enterprise

CHAPTER 3 Configuring the Operating System

4 At the UNIX prompt, execute the following statements as “root”. The user

ID of the user who is starting Adaptive Server and Backup Server m ust be
the owner of the /dev/async directory.

HP-UX 11.23

This step is mandatory for HP users.

To improve I/O performance on character or raw block devices, enable

asynchronous I/O by installing the HP asynchronous I/O driver from SAM. For

help with installing this driver, contact your operating system administrator or

HP technical support.

Note Before executing the following instructions, shut down Adaptive Server

(or SQL Server).

1 To launch the Kernel Configuration use

kcweb -F.

2 Select Modules.

3 Select

asyncdsk and change the next boot to static.

4 Rebuild the kernel, and reboot the system.

5 Execute the following commands using the

#/etc/mknod/dev/async c 101 4
#chmod 0660/dev/async
#chown <uid> /dev/async
#/etc/setprivgrp <ugrp> MLOCK

userid root:

Where:
<uid> is the identification (user ID) used by the user that is booting

Adaptive Server .
<ugrp> is the user group for the sybase userid.

6 At the UNIX prompt, execute the following statements as “root”. The user

ID of the user who is starting Adaptive Server and Backup Server m ust be
the owner of the /dev/async directory.

HP-UX on Itanium

To verify that the async I/O is active on the Itanium machine:

1 Log in as root.

2 Issue the command:

# kcmodule -a | grep aync

Result: asyncdsk static required
or you can also use the following:

Configuration Gu ide 39

Enabling asynchronous disk I/O

# ls /dev/asyn*
idev/async /dev/asyncdsk

For IBM AIX

Enable asynchronous disk I/O.
This step is mandatory for IBM users.
Enable asynchronous I/O by adjusting the kernel parameters , using the System

Management Interface Tool (SMIT):
1 Enter “smit” at the UNIX prompt.
2 From the Devices menu, select Asynchronous I/O.
3 Select Change/Show Characteristics of Asynchronous I/O.
4 Enter the values from Table 3-2:

Table 3-2: SMIT parameters for asynchronous I/O

Values for RS/6000 AIX

SMIT parameter

MINIMUM number of servers 1
MAXIMUM number of servers 10
MAXIMUM numbe r of REQUESTS I/O 4096
Server PRIORITY 39
ASYNC I/O STATE

(to be configured at system restart)

4.3.3

Available

If your system uses more than seven disks at th e same time for Asynchro nou s
I/O, increase the MAXIMUM number of servers value by 1 for every active
device.

Note Setting the minor device number on /dev/async to 4 reduces or eliminates

transient 605 errors in Adaptive Server.
If you are using LVM mirroring, set the minor device number to 0x0.

40 Adaptive Server Enterprise

CHAPTER 3 Configuring the Operating System

Adjusting the client connection timeout period

Adaptive Server uses the KEEPALIVE option of the TCP/IP protocol to detect

clients that are no longer active. When a connection to a client is inactive fo r a

period of time (the timeout period), the operating system sends

packets at regular intervals. If it does not receive a response from the client

machine for any of these packets, the operating system notifies Adaptive

Server that the client is no longer responding. Adaptive Server then terminates

the client’s connection.

The

KEEPALIVE default timeout period is 2 hours (7,200,000 ms). To display

the current time value, use the command for your platform as shown in the

following sections.

For HP-UX

To display the current timeout period, enter:

KEEPALIVE

For IBM RS/6000

/usr/contrib/bin/nettune -l

Note The switch is a lowercase “L”, not the number one (1).

tcp_keepstart parameter specifies the length of time (measured in seconds)

The

to keep an idle connection active before the system checks to see if the

connection died.

To change the timeout period, use the

nettune -s command.

To display the current timeout value, enter:

/usr/sbin/no -o tcp_keepidle

The tcp_keepidle parameter specifies the length of time (measured in half

seconds) to keep an idle connection active before the system checks to see if

the connection died. The default is 14,400 half seconds (7200 seconds, or 2

hours).

IBM recommends a value of at least 15 minutes.

Configuration Gu ide 41

Checking for hardware errors

For Sun Solaris

To disp lay the timeout value, enter:

/usr/sbin/ndd -get /dev/tcp tcp_keepalive_interval

To reduce the timeout period to 15 minutes (900,000 ms.), enter:

/usr/sbin/ndd -set /dev/tcp tcp_keepalive_interval 900000

For Linux

To disp lay the timeout value, enter:

/sbin/sysctl -e net.ipv4.tcp_keepalive_time

To reduce the timeout period to 15 minutes (900 seconds,) enter:

/sbin/sysctl -w net.ipv4tcp_keepalive_time=900

Checking for hardware errors

The following types of hardware error messages indicate problems that may
lead to database cor ruption:

• Disk read, write, or retry errors

•Timeouts

• System panics

• Memory problems of any type

For HP-UX

Check the /var/adm/syslog/syslog.log file on a regular basis. You can v iew the
file directly, or you can use the HP-UX
system documentation for more information.

dmesg command. See your operating

42 Adaptive Server Enterprise

For IBM RS/6000

For Sun Solaris

CHAPTER 3 Configuring the Operating System

The errpt command includes several options for limiting the report to events

that match certain criteria. Use the

appear, use the diagnostic tool

System Management Interface Tool (SMIT) to run the

command may produce a lot of output.

Check the /var/adm/messages file on a regular basis. If any of the types of

hardware errors described in the beginni ng of t his section appear, use the Sun

Microsystems diagnostic to ol ,

operating system documentation for more information.

errpt command on a regular basis. If errors

diag to check your memory and dis ks. Or use the

errpt command. This

sundiag, to check memory and disks. See the

For Linux

Check the /var/log/messages file on a regular basis. See the operating system

documentation for more information.

Monitoring the use of operating system resources

The System Administration Guide di scusses maintaining the optimal num ber of

Adaptive Server engines for your workload and system configuration. To

determine the optimal number, monitor system and CPU usage.

For HP-UX

HP-UX supplies many tools to help monitor performance, some of wh ich are

described as follows:

•The

sar command reports relative and absolute I/O throughput rates to

each disk and controller.

•The

•The

Configuration Gu ide 43

vmstat command monitors virtual memory usage.
netstat command monitors netw ork status.

Monitoring the use of operating system resources

•The ps command provides a snapshot of accumulated CPU time and us age

for individual processes.

For IBM RS/6000

•The

time command can be us eful in determ ining t he various user, system,

and real-time resources used over a complete run.
For details about these tools, see your operating syst em documentation.

IBM RS/6000 supplies the following tools for monitoring performance:

•The

iostat command reports the amoun t of I/O on termi nals and hard dis ks

and how CPU time is spent.

•The

•The

vmstat command monitors virtual memory usage.
netstat comma nd monitors network s tatus.

•

netstart -v displays Transmit/Receive Statistics. It is also used to

determine if enough buffers have been configured for network traf fic.

•

no -a command displays current network options. It is also used for

tuning mbuf pools.

•The

ps command provides a snapshot of accumulated CPU time and us age

for individual processes.

•The

time command determines the various user, system, and real-time

resources during a complete run.
For details about these tools, see your operating syst em documentation.

For Sun Solaris and Linux

Sun Solaris and Linux supplies the following tools to help monitor
performance:

•The

•The

•The

44 Adaptive Server Enterprise

iostat command reports the amoun t of I/O on termi nals and hard dis ks

and how CPU time is spent.

vmstat command monitors virtual memory usage.
netstat comma nd monitors network s tatus.

CHAPTER 3 Configuring the Operating System

•The

ps command gives you an accurate snapshot of accumulated CPU

time and usage for individual processes. This can be very helpful in
determining the dataserver-, engine-, and process-specific loading.

•The

time command can be useful in determining the various user , system,

and real-time resources used over a complete run.

For details about these tools, see your operating system documentation.

A sample C shell maintenance script

Running dbcc checks and performing datab ase backu ps pro te ct the integr ity

and recoverability of your Adaptive Server databases. The following sample C

shell script calls several

#!/bin/csh -f
if ( -e dbcc_mail.out) then

rm dbcc_mail.out
endif
foreach i (*.dbcc)
isql -Usa -Ppassword < $i > dbcc_out
if ( ‘grep -c ‘Msg 25[0-9][0-9]’ dbcc_out’ ) then

echo "There are errors in" $i >> dbcc_mail.out

cat dbcc_out >> dbcc_mail.out
else

echo "Backing up " $i:r >> dbcc_mail.out

isql -Usa -Ppassword < $i:r.backup
endif
end
mail -s "Backup Report" jjones < dbcc_mail.out

isql scripts to help you do this:

The first set of scripts (one for each database with a file name appended with
.dbcc) runs
messages to an output file called dbcc_out.

For example, the script

The C shell script then runs the grep command to find 2500-level error
messages in the
file called dbcc_mail.out.

Configuration Gu ide 45

dbcc checkalloc and dbcc checkdb for each database and sends the

master.dbcc runs dbcc to check the master database:

dbcc checkalloc (master)
go
dbcc checkdb (master)
go

dbcc output. The results of the grep command go into an output

A sample C shell maintenance script

Next, the script invokes an isql backup script for each database for which no
2500-level errors occurred and adds the “Backing up database_name” line to
dbcc_mail.out. For example, the script
database:

use master
go
dump database master to master_dump
go

You may want to add appropriate dump transaction commands to your scripts.
If there are 2500-level error messag es, the script does not back up the database.

At the end of the script, dbcc_mail.out is mailed to the System Administrator
“jjones,” who then has a record of fatal

master.backup backs up the master

dbcc errors and successful backups.

You can tailor the sample shell and

isql scripts to suit the needs of your

installation.
T o have the scripts execute automatically, edit the crontab file, and add an ent ry

similar to this:

00 02 * * * /usr/u/sybase/dbcc_ck 2>&1

This example executes a C shell script called dbcc_ck every morning at 2:00
a.m.

46 Adaptive Server Enterprise

CHAPTER 4

Adaptive Server Default
Configuration

When you install or upgrade Adaptive Server, it includes some default
parameter settings and a few of its auxiliary programs.

After installing and testing this “default” Adaptive Server, you can
configure it to your system’s needs and install other optional features.

For information about configuring Adaptive Server, Backup Server, and
Monitor Server see the System Administration Guide.

For information about configuring languages, character sets, and sort
orders, as well as optional features, see the System Administration Guide.

Topic Page

Default settings 47

Default settings

After installation, Adaptive Server default settings are as listed in Table 4-

1. You may need to configure these settings to suit your computer and
database needs.

Table 4-1: Defaults for Adaptive Server parameter settings

Item Default value

Name Servername
Transport Type TCP/IP
Port number 5000
Error log path $SYBASE/$SYBASE_ASE/install/servername.log
Event logging Not configured
International support (Localization)

• Language us_english

Configuration Gu ide 47

Default settings

Item Default value

• Character set HP – Roman8
IBM – ISO 8859-1
Sun – ISO 8859-1
Linux – iso_1

• Sort order Linux – Binary ordering

Login securit y mode Standard

Table 4-2 lists the default setti ngs fo r the Backup Server, Monitor Server, and
XP Server. For more information about these servers, see “Introduction” on
page 1.

Table 4-2: Defaults for Backup, Monitor, and XP Servers

Server Item Default value

Backup Server Name AdaptiveServername_back

Network support (TCP/IP)
Socket number 5001
Error log path $SYBASE/$SYBASE_ASE/install/AdaptiveS

ervername_back.log

Monitor Server Name AdaptiveServername_mon

Network support (TCP/IP)
Socket number 5002
Error log path $SYBASE/$SYBASE_ASE/install/AdaptiveS

ervername_back.log

XP Server Name $SYBASE/$SYBASE_ASE/ADAPTIVESER

VERNAME_XP

Network support (TCP/IP)
Socket number 5003
Error log path N/A

48 Adaptive Server Enterprise

CHAPTER 5

Setting Up Communications
Across the Network

Adaptive Server can communicate with other Adaptive Servers, Open
Server applications, and client software across a network. Clients can
communicate with one or more servers, and servers can communicate
with other servers via remote procedure calls.

Topic Page

How Adaptive Server determines which directory service entry to
use

How a client uses directory services 51
Creating a directory services entry 51
Supported directory drivers 52
Contents of an interfaces file 52
Heterogeneous and homogeneous environments 53
Understanding the format of the interfaces file 55
Creating a master interfaces file 58
Configuring interfaces files for multiple ne tworks 59
IPv6 support 63
Troubleshooting 66

50

Configuration Gu ide 49

Directory services contains information about the network locations of
servers. Directory services contain entries for all Adaptive Servers,
Backup Servers, and other server products on the network.

In the Sybase client/server environment, a client can connect with
Adaptive Server if it knows where the server resides on the network and
if the server supports the client’s language or character set. When a client
initiates a connection, it looks in its directory services for the network
location of the target server.

Directory services list the name and address of every server, including
Backup Server, Monitor Server, and XP Server. When you are using a
client program, and you want to connect with a par ticular server , the client
program looks up the server name in the directory services and connects
to that server.

How Adaptive Server determines which directory service entry to use

Servers also need network information. When a server starts up, it looks in its
interfaces file to determine where to listen for client connection requests. In
addition, Adaptive Server can take on a client role when it makes remote
procedure calls to other Adaptive Servers.

T able 5-1 shows where to find more information on se rver and client interfaces
file tasks and topics.

Table 5-1: Where to find interfaces file tasks and topics

Type of
interfaces file Task or topic See

UNIX server or
client

Creating a master interfaces file

Reference information “Understa nding the format of the interfaces file” on

PC-client Configuring a client Installation Guide for your platform
Reference information and

Client platforms
not listed

Adding entries for multiple
Adaptive Server installations

for multiple installations
Configuring for multiple networ ks “Configuring interfaces files for multiple networks” on

instructions for advanced tasks

Configuring, reference
information, and instructions for
advanced tasks

Chapter 7, “Customizing Localization for Adaptive
Server”

“Creating a master interfaces file” on page 58

page 59.

page 55.

Open Client and Open Server Programmer’ s Supplement
for your PC-client platform, or the appropriate Open
Client documentation

Open Client and Open Server Programmer’ s Supplement
for your PC-client platform, or the appropriate Open
Client documentation

How Adaptive Server determines which directory
service entry to use

Adaptive Server uses directory services to determine the address at which it
should listen for clients. When you start Adaptive Server, it performs the
following steps:

1 It looks for the server name supplied in the command line

server name is not supplied in the command line:

2 It determines its own name by checking the value of the DSLISTEN

environment variable. If the DSLISTEN environment variable is not set,
then it assumes that the server name is SYBASE.

50 Adaptive Server Enterprise

-s option. If the

CHAPTER 5 Setting Up Communications Across the Network

3 Looks in directory services for an entry whose name matches the name

found in the steps above.

4 It uses the network infor mation provi ded by the di rectory se rvices entry it

has found to listen for client connections.

How a client uses directory services

When a client connects to a server it:

• Determines the name of the serv er either programmatically or by referring
to the DSQUERY environ ment variable. If the application user has not set
DSQUERY, the runtime value for the server name defaults to the SYBASE
environment variable.

• Looks in directory services for an entry whose name matche s the name of
the server.

• Uses the network information provided by the directory services entry to
connect to the server. If the client cannot connect the first time, it makes
additional attempts according to the delay and retry numbers indicated in
directory services. If no matching entry is found, an error message is
written to the client’s standard error file. If multiple networks are
supported, the client attempts to connect using the information in the
second network address entry for the server.

The Open Client documentation discusses client connections in much greater
detail. See the Open/Client Pr ogrammer’s Supplem ent for your cli ent platform
or the appropriate Open/Client documentation.

Creating a directory services entry

The installation program, srvbuild, automatically creates a directory services
entry for each server installation. You can also use the following Sybase
utilities to edit the network information in directo ry services:

•

dsedit – an X-Windows GUI utility.

•

For details on using these utilities, see the Adaptive Server Utility Guide.

Configuration Gu ide 51

dscp – a UNIX command line utility.

Supported directory drivers

Supported directory drivers

There are three supported drivers:

• interfaces driver

• Lightweight Directory Services driver.

• Cell Directory Service (CDS) provided by Distributed Computing
Environment (DCE)

This remainder of this chapter describes the interfaces file and provides
specific configuration information for each supported UNIX platform. For
information about LDAP drivers, Cell Directory Services, and for a
comparison between interfaces files and LDAP directory services, see the
Open Client/Server Configuration Guide for your platform.

Contents of an interfaces file

An interfaces file contains network information about all servers on your
network, including Adaptive Server, Backup Server, and XP Server, plus any
other server applications such as Monitor Server, Replication Server, and any
other Open Server applications.

The network infor mation in the fil e includes the s erver name, netwo rk name or
address of the host machine, and the p ort, object, or socket number (depen ding
on the network protocol) on which the server listens for queries. See
“Understanding the format of the interfaces file” on page 55 for the specific
makeup of the interfaces file entry.

Each entry in an interfaces file can contain two types of lines:

• Master lines, which are used by server applications to listen for queries
over the network. This information is called a listener service.

• Query lines, which are used by client applications to connect to servers
over the network. This information is called a query service.

The network information contained in the master and query lines for a server
is identical because a server listens for connection requests on the same port
that clients use to request connections.

A server needs both master and query lines in its interfaces file, since servers
sometimes ac t as clients to other se rvers.

52 Adaptive Server Enterprise

CHAPTER 5 Setting Up Communications Across the Network

A client’ s interfaces file does not need a master line. It functions correctly with
only a query line.

If your site has
multiple installations

If you have more than one Adaptive Server installation, each server’ s interfaces
file should contain information about all servers on the network.

If all of your server product s are running on th e same platfo rm, you can c reate
one master interfaces file and copy that file to each machine. For more
information, see “Creating a master interfaces file” on page 58.

If the host machine supports multiple networks, see “Configuring interfaces
files for multiple networks” on page 59.

Heterogeneous and homogeneous environments

You can run Adaptive Server and clients on the same platform or on different
platforms.

If the platforms are differ ent, each platform may require a d iff erent format and
configuration for its interfaces file. Figure 5-1 illustrates how a PC client uses
network information in its interfaces file (sql.ini) to connect to Adaptive Server
running under UNIX, and how Adaptive Server uses its interfaces file to
connect to another server during a remote procedure call.

Configuration Gu ide 53

Heterogeneous and homogeneous environments

Figure 5-1: Establishing network connections in a heterogeneous
environment

PC clients

Get Harpo’s
address and
connect.

PC clients

sql.ini

[Harpo]

xxxxx

[Chico]

Harpo SQL

server

Make a remote
procedure call to

Chico.

Chico SQL
server

interfaces

Harpo

xxxxx

Chico
xxxxx

Get Chico’s

xxxxx

address and
connect.

If both a client and a server are running under UNIX, the same interfaces file
is valid for both. Figure 5-2 illustrates how clients and Adaptive Servers
running in a homogen eous en vironment can use cop ies of th e interfaces file to
establish connections. Because the two Adaptive Server s are running under the
same operating system, they can use the same inter faces file or exact copies of
the same file.

54 Adaptive Server Enterprise

CHAPTER 5 Setting Up Communications Across the Network

Figure 5-2: Establishing network connections in a homogeneous
environment

Homogeneous

clients

Get Harpo’s
address and
connect.

Get Chico’s address
and connect.

Harpo SQL

server

Harpo

xxxxx

Chico
xxxxx

Chico SQL

server

Get Chico’s
address and
make an RPC.

Understanding the format of the interfaces file

The following rules apply to the format of interfaces file entries:

• Each Adaptive Server has only one entry, although there may be multiple

lines in the entry.

• Each line that follows the servername line must begin with a space or a

character tab.

• Each element on the line must be separated by a single space.

• Each entry is separated by a blank line.

• You can add comments to an interfaces file by adding a pound sign (#) at

the beginning of the line and a line break at the end.
There are two interfaces file entry formats, TLI and TCP.
A TLI style entry looks like:

Configuration Gu ide 55

Understanding the format of the interfaces file

servername retry_attempts delay_interval<newline>
<tab>service_type api protocol device address filter<newline>
<tab>ha_failover servername<newline>

A TCP style entry looks like:

servername retry_attempts delay_interval<newline>
<tab>service_type protocol network machine port filter<newline>
<tab>ha_failover servername<newline>

Components of an interfaces file entry

Table 5-2 describes the components of an interfaces file entry.

Table 5-2: Components of an interfaces file

Component Value

servername Name of Adaptive Server or Backup Server. Requirements for a server name are:

• The name cannot be more th an 30 characters long.

• The first character must be a letter (ASCII a through z, A through Z).

• The characters that follow must be letters, numbers, or underscores (_).

retry_attempts (optional) Number of times you want the client to try to connect to a server after initial

failure. Default is 0.

delay_interval (optional) Number of seconds between connection a ttempts. Default is 0.
service_type Type of service defined by entry. Must be one of the following:

•master

•query

api Application program ming int erface availa ble to th e network .The sup ported v alue

is tli.

protocol Name of the ne tw ork protocol. Pr oto c ol typ e s av a ila ble are:

• TCP/IP, represented by the letters “tcp”

network Name of the network; not currently used by Adaptive Server.

“ether” as a placeholder.

host Network name or address of server’s host machine.

• For TCP/IP, use eit her the host name or Internet address. Maximum size of
entry is 32 bytes.

To determine the host name of a machine, log in to that machin e and enter:

srvbuild enters

56 Adaptive Server Enterprise

/bin/hostname

CHAPTER 5 Setting Up Communications Across the Network

Component Value

machine Network name or address of server’s host machine.

You can use either the ho st name or Inte rnet address . Maxi mum s ize of e ntry is 32
bytes.

To determine the host name of a machine, log in to that machine and enter:

/bin/hostname

device The network device endpoint.

For TCP networks, the device varies according to the vendor supplying the
networking software. Check the vendor-specific documentation for the name of
the device. Your network may provide multip le stream devices cor responding to
different protocol s in the TCP protocol suite. Choose the TCP stre ams device.
Common TCP streams devices is /dev/tcp.

address for a TLI protocol
entry

Address consists of:

• Address prefix, “\x” for TLI.

• Network type, always 0002.

• Port number c onverted to four digits, hexadecimal. Must be a unique number
between 1025 an d 65535. Check the /etc/services file on each ma chine on the
network to see what port numbers are in use. Enter the Adaptive Server port
number in a new section o f /etc/services labeled “Sybase specific services.”
You do not have to make this entry for the operating system to function
properly , but the presence of th e port number in the file may preven t other users
from using the port number.

• IP network no de address of the host machine converted to 8 digits,
hexadecimal.

• Trailing zeros, optional, 16 digits.

port A unique port number between 1025 and 65535. Check the /etc/services file on

each machine on the net w ork to see what port numbers are in use. Enter the
Adaptive Server port number in a new section of /etc/services labeled “Sybase
specific services.” You do not have to make this entry for the operating system to
function properly, but the presence of the port number in the file may prevent other
users from usin g tha t port number.

ha_failover An entry created in directory services or the interfaces file for high availability.
filter Adaptive Server supports Secure Socket Layers (S SL) as a filter which is

appended to the master and query lin e s of the directory services. SSL is the
standard for securing the transmission of sensitive information.

Configuration Gu ide 57

Creating a master interfaces file

Creating a master interfaces file

A master interfaces file contains entr ies for all Syb ase servers on the network.
It can be used with every server and client connected to the network. By
distributing copies of a master interfaces file, you can ensure that all Sybase
products on the network interact with one another.

Distributing copies of one interfaces file (a master file) with entries for all
Adaptive Servers is the easiest way to maintain consistency in the interfaces
files in a homogeneous environment on a network.

You can make all changes to one version of the file and then copy the updated
master file to all appropriate Sybase directories.

You can make a master file in one of two ways:

• Using

• Using a text editor

dsedit or dscp

Using dsedit or dscp to create a master interfaces file

You can use the dsedit or dscp utility to create a master interfaces file, which
you can then distribute to all servers. If you are not an experienced Sybase user ,
you may find that using

dsedit or dscp also ensures that your interfaces file is consistent in format.

To create a master interfaces file with
1 Select the interfaces file that contains the most complete, up-to-date

information.

2 Begin a

interfaces file.

3 Add entries for any Adaptive Servers or Backup Servers tha t are not listed

in this file.

dsedit or dscp session in your latest Sybase installation to edit this

dsedit or dscp is easier than using a text editor. Using

dsedit or dscp:

For details on using these utilities, see the Adaptive Server Utility Guid e .

Using a text editor to create a master interfaces file

To construct a single mast er interfaces file from several individual interfaces
files:

58 Adaptive Server Enterprise

CHAPTER 5 Setting Up Communications Across the Network

1 Concatenate the individual interfaces files.
2 Make a copy of the file.
3 Use an ASCII text editor to modify the copy of the concatenated file.

Note When you manually edit an interfaces file, be sure that, for each

entry, each line following the first line begins with a <tab> character.

The following elements must be correct and unique in the resulting file:

• servername – each server entry in the interfaces file must be unique.
During the
name or accepting the default server name, SYBASE, for those
servers. If you accepted the default name, find any duplicate
SYBASE entries in your merged file, and rename them.

• A combination of the host machine’s network name or address and
Adaptive Server’s port or object number.

srvbuild session, you had the choice of entering a server

• If the original interfaces file was created when there was only one
machine on the network, its entries may have the word “loghost” in
place of the machine name (address). If loghost is present, replace it
with the machine name.

Configuring interfaces files for multiple networks

On some platforms, Adaptive Server can accommodate multiple networks.
This allows Adaptive Server to listen for clients over multipl e netwo r k
interfaces. You must add an entry for each network interface to the interfaces
file.

Configuring the server for multiple network handlers

To configure multiple network listeners:
1 Define a unique host name for each network interface in your operating

system’s host database.

Configuration Gu ide 59

Configuring interfaces files for multiple networks

2 In your interfaces file, use a text editor to add copies of the “master” line

for your Adaptive Server; one for each additional interface you want the
server to listen on.

3 Include a unique host name on each line to configure a network hand ler for

each network interface.

4 Port numbers within the interface need not be the same, but they can be.

They fall under the same rules for naming and numeric range as the
primary network interface.

Sample interfaces files for multiple network handlers

The following example shows an interfaces file for an Adaptive Server with
two network interfaces. The server host machine is known as
SERV_CORPNET on the corporate network and SERV_ENGNET on the
engineering network.

# PRODUCTION server with two network listeners
PRODUCTION<tab>3<tab>3<newline>
<tab>master tcp ether SERV_CORPNET 4559
<tab>master tcp ether SERV_ENGNET 5479
<tab>query tcp ether SERV_CORPNET 4559

When Adaptive Server restarts, it spawns a network handler process for each
master line in the entry that corresponds to the server’s DSLISTEN value.
Connections made on each interface are handled equally, as peers.

Configuring the client connections

When an Adaptive Server client scans the interfaces file for a server name, the
client uses the first “query” entry it encounters for the server’s entry. This
makes configuring clients to use multiple n etwork connections less
straightforward than configuring the server ports. You have two choices:

• Use the same DSQUERY name for all clients. The interfaces files on the
different machines contain different network names.

• Use different DSQUERY names for the clients. The interfaces files on all
the machines are the same, but they contain multiple DSQUERY names.

60 Adaptive Server Enterprise

CHAPTER 5 Setting Up Communications Across the Network

Using one network-independent DSQUERY name

If uniform client DSQUER Y naming is important, you can m ake the necessary
changes in the network addressing of the clients in the interfaces file. You can
install separate Sybase installation directories and distinct interfaces files on
client file servers on each network to allow users to connect to the correct
network address. Instead of altering the DSQUERY name the clients use, you
maintain one DSQUERY name for all clients, on all networks, and alter each
network’s interfaces file accordingly.

This method assumes that:

• Y ou have complete control over what the Sybase installation clients see on

each network.

• The interfaces file (at the very least) is not shared or copied among Syb ase

installations on different networks.

The interfaces file looks like the following example on the “engineering”
network:

PRODUCTION<tab>3<tab>3<newline>
<tab>query tcp ether SERV_ENGNET 5470
<tab>master tcp ether SERV_CORPNET 4559
<tab>master tcp ether SERV_ENGNET 5479

The interfaces file looks like the following example on the “corporate”
network:

PRODUCTION<tab>3<tab>3<newline>
<tab>query tcp ether SERV_CORPNET 4559
<tab>master tcp ether SERV_CORPNET 4559
<tab>master tcp ether SERV_ENGNET 5479

The “query” line in each file name is different, depending on the network to be
used.

The full “master” entry is present in both files. This is allowed because only
Adaptive Server will use the “master” lines. Assuming that the server host
machine can see both networks (b oth hos t n ames are interchan geable) , it d oes
not matter which interfaces file is used for Adaptive Server start-up.

Using different DSQUERY names

To use different DSQUERY names for each network listener:
1 Choose an additional server name.

Configuration Gu ide 61

Configuring interfaces files for multiple networks

You can concatenate the original server name and the network name. For
example, if your server is named PRODUCTION, you could choose the
names PRODUCTION_network1 and PRODUCTION_network2.

2 Do one of the following:

• For PC clients, use

sqledit to create multiple sql.ini file entries for the

server, one for each network. In the following example, you create
one entry for PRODUCTION_network 1 and one for
PRODUCTION_network2. For more information, see the Open
Client documentation for your client platform.

• For UNIX clients, you can edit the interfaces files with an ASCII text

editor. From the server’s interfaces files, copy the server name line
and the “master” line for each network into the client interfaces file.
Add the appropriate server name for each entry, and change “master”
to “query.”

Clients on each network must use the DSQUERY value that
corresponds to the network the client is on. In the following example,
either PRODUCTION_network1 or PRODUCTION_network2 can
be used.

# Client entry for PRODUCTION on network1
PRODUCTION_network1<tab>3<tab>3<newline>
<tab>query tcp ether serv_corpnet 4559
# Client entry for PRODUCTION on network2
PRODUCTION_network2<tab>3<tab>3<newline>
<tab>query tcp ether serv_engnet 5479

Configuring for query port backup

Another use for multiple network interfaces is to provide a backup in case of
network failure. If a client is connected to a server via two networks, the client
can establish a connection via the second network if the first one goes down.

To configure Adaptive Server for query port backup:
1 Install multiple “master” and “query” lines in a server entry in the

interfaces file.

2 Adaptive Server listens for connections at both ports. Clients looking for

a host name and a port number for a connection to an Adaptive Server try
the port on each “query” line in order, until they establish a connection.

62 Adaptive Server Enterprise

CHAPTER 5 Setting Up Communications Across the Network

The following example shows how to configure a backup network that
will be used only if the normal connection fails. The primary network is
“corporate network” and backup is “engineering network.”

# PRODUCTION server with two network listeners
PRODUCTION<tab>3<tab>3<newline>
<tab>master tcp ether SERV_CORPNET 4559
<tab>master tcp ether SERV_ENGNET 5479
<tab>query tcp ether SERV_CORPNET 4559
<tab>query tcp ether SERV_ENGNET 5479

3 Configure PC-client interfaces files with the appropriate multiple “query”

entries, as described in the Open Client documentation. Fo r cli ent
interfaces files in a homogeneous environment, you can copy the entire
interfaces file entry for the Adaptive Server into the client interfaces file.

4 A connection on the secondary port occurs only if the corporate network

is disabled, or if the corporate network interface on the host machine fails
or is shut down due to a network-related failure.

IPv6 support

Adaptive Server supports IPv6 technology.

Understanding IPv6

IPv6 addressing terminol o gy:

• Link-local address – an IPv6 address th at is usable only over a single link .

• Site-local address – an IPv6 address that can be used within a single-site.

• Global address – an IPv6 address that can be used across the global

IPv6 application types:

• IPv6-unaware – an application that cannot handle IPv6 addresses.

• IPv6-aware – an application that can communicate with n odes that do n ot

Internet.

have IPv4 addresses. In some cases, this might be transparent to the
application, for instance when the API hides the content and fo rmat of the
actual addresses.

Configuration Gu ide 63

IPv6 support

• IPv6-enabled – an application that, in addition to being IPv6-aware, takes

• IPv6-required – an application that requires some IPv6 features and cannot

IPv6 Infrastruct u re:

IPv6 infrastructure

Dual Stack infrastructure implements both IPv4 and IPv6. This is the
recommended infrastructure implementation for using Adaptive Server
Enterprise as an IPv6-aware server.

Sybase applications are IPv6-aware. All code to turn Sybase™ Adaptive
Server and the Open Client/Server compone nts IPv6-aware wa s done using the
IETF designed primitives, see “Creating or converting for IPv6-awar e
applications.” The following matrix lists the platform run-time requirements
and the specific product and its release version:

advantage of some IPv6 features.

operate over IPv4.

Table 5-3: IPv6 support

Adaptive Server IPv6

Platform

Sun Solaris 8 32- and 64-
bit

HP-UX 11i(v1) 32- and
64-bit

Microsoft Server 2003 12.5.3a and 15.0 12.5 and 15.0
Linux RHEL 3.0 15.0 12.5 and 15.0

awareness

12.5.3a and 15.0 12.5 and 15.0

12.5.3a and 15.0 12.5 and 15.0

Open Client/Server
IPv6 awareness

Many Sybase products that are Open Client/Server based like XP Server,
Backup Server, Replication Server and Open Switch became automatically
IPv6-aware due to the layered Open Client Transport Control Layer (CTlib­>NETlib) which is IPv6-aware for network-socket operation s. An important
note is that any DBlib based Open Client product is not IPv6-aware.

For Adaptive Server Enterprise being IPv6-aware is a complex issue because
some components within the ASE are 3rd party components and are not yet
IPv6-aware. To und erstan d how this impacts Adaptive Server Enterprise the
following list shows all functional mechanisms of Adaptive Server Enterprise
that are IPv6-aware with respect to the platform / release matrix above:

• Connection Handler

64 Adaptive Server Enterprise

CHAPTER 5 Setting Up Communications Across the Network

• RPC mechanisms

• Job Scheduler Task / Agent session connection

• Netwo r k Ho st API

• UDP Message support for

sybsendmsg

• Component Integration Services connectivity

• Host / name resolving

• XML URL connection handler

• Auditing for client address data
The following functional mechanisms in Adaptive Server Enterprise do not

support IPv6. These mechanisms in Adaptive Server Enterprise are IPv6­unaware. They will gradually (over time) be become IPv6-aware in follow-on
releases:

• Java support

• License Management Server

• LDAP driver

Starting Adaptive Server Enterprise as IPv6-aware

Adaptive Server is IPv6-unaware, by default. To make Adaptive Server IPv6­aware, you must start Adaptive Server with trace flag 7841. This causes
Adaptive Server to determine IPv6 availability and makes Adaptive Server
IPv6-aware.

See your Network or IT specialist to configure your platforms and Network
Infrastructure correctly for IPv6 support.

A second trace flag, 7815 can be set when you start Adaptive Server which
captures and logs address connection requests and host / name lookups.

The IPv6 Adaptive Server traceflags:

• T7841 – Enable Adaptive Server IPv6-awareness

• T7815 – Report all Adaptive Server IPv4 & IPv6 Client address connect

requests

Configuration Gu ide 65

Troubleshooting

Before starting Adaptive Server for IPv6-aware operations, make sure that
your infrastructure is correctly set up. Once your operating system is correctly
configured, an IPv6
Configuring and enabling the IPv6

connection handler can be configured and enabled.

connection handler requires adding an

additional DCL entry. A single Adaptive Server configuration can typically
carry up to 32

connection handler assignments within the DCL.

For example if you have a Site-local setup with two domains administrated
under the nameserver setup:

sybase.com - being responsible for all IPv4 networking applications
v6.sybase.com - being responsible for all IPv6 networking applications

The DCL entry for Adaptive Server to start named “SYBASE” on the host
“revival” for port 17100 would typically look like:

SYBASE
master tcp ether revival.sybase.com 17100
query tcp ether revival.sybase.com 17100
master tcp ether revival.v6.sybase.com 17100
query tcp ether revival.v6.sybase.com 17100

In the above example, when Adaptive Server is started with IPv6-awareness it
creates two

connection handlers. One listens on port 17100 for incoming IPv4

Clients connection requests, and the other listens on port 17100 for incoming
IPv6 Clie nts connec t ion requests.

Troubleshooting

This section describes how to correct some common situations that may cause
a server to not start.

Server fails to start

If a server fails to start with the following message, the port number s pecified
in the interfaces file may be in use:

00:00000:00002:2003/09/22 12:37:23.63 kernel network name SERV_CORPNET, type
ether, port 4559, filter NONE
00:00000:00002:2003/09/22 12:37:23.65 kernel ninit: bind, Address already in
use
00:00000:00002:2003/09/22 12:37:23.68 server Error: 1602, Severity: 18, State:

66 Adaptive Server Enterprise

CHAPTER 5 Setting Up Communications Across the Network

2
00:00000:00002:2003/09/22 12:37:23.68 server Unable to initialize network 0
00:00000:00002:2003/09/22 12:37:23.68 kernel ninit: All master network
listeners have failed. Shutting down.
00:00000:00002:2003/09/22 12:37:23.68 kernel ueshutdown: exiting
00:00000:00016:2003/09/22 16:11:35.46 server SQL Server shutdown by request.

v Investigating the port assignment

1 Look in the interfaces file to identify the port number assigned to the

server.

2 Determine whether another process is using the same port number by

entering:

netstat -a

If the port number is presented as a local ad dress in the netstat output, you
cannot use that port for the server. Another process is already using that
port.

3 To verify that the server port is in use, start the server manually.

The server

does not start if its assigned port number is already in use.

For information on starting servers manually, see the installation
documentation for your platform and the Adaptive Server Utility Guide.

v If a stale server process is retaining use of the port num ber

1 Do one of the following:

• Use the operating system

• Use another port number for the server
file.

2 Start the server

For information on starting servers manually, see the installation
documentation for your platform and the Utility Guide.

Error when executing an ESP

kill command to terminate the process.

by modifying the interfaces

manually to confirm that the port number is available.

If you attempt to execute an ESP (extended s tored procedure), you may see th e
following error:

00:00000:00008:1997/09/10 12:52:53.03 kernel XP Server failed to start. Try
bringing up XP Server manually. Check SQL Server documentation for more

Configuration Gu ide 67

Troubleshooting

information on how to bring XP Server up.

XP Server cannot start because the port number may be in use by another
process. Use the

netstat comma nd describe d in the previous section to

determine if the port number specified for XP Server is in use.
If you find no processes using the same port nu mber:
1 Restart Adaptive Server.
2 Execute the ESP that you attempted earlier.

XP Server

should start automatically .

If you find a process using the same port number, you can do one of the
following:

• Change the interfaces file to use a new port number for the XP Server.

• Stop the process using the port number allotted to XP Server.
Restart Adaptive Server, and execute the ESP that you attempted earlier. XP

Server should start automatically.

68 Adaptive Server Enterprise

CHAPTER 6

Using the Lightweight Directory
Access Protocol as a Directory
Service

Adaptive Server uses directory services to establish client and RPC
connections over the Internet. This chapter provides information about
using LDAP directory services to establish connections.

Topic Page

Overview 69
LDAP directory services versus the Sybase inte rfaces file 70
The libtcl*.cfg file 73
Enabling LDAP directory services 74
Adding a server to the directory services 76
Multiple directory services 77
Encrypting the password 78
Performance 78
Migrating from the interfaces file to LDAP 79

Overview

Configuration Gu ide 69

Lightweight Directory Access Pr otoco l (LDAP) is an industry standard
for accessing directory services. Directory services allow components to
look up information by a distingu ished name (DN ) from an LDA P server
that stores and manages server , user, and software information that is used
throughout the enterprise or over a network.

The LDAP server can be located on a different platform from the one on
which Adaptive Server or the clients are running. LDAP defines the
communication protocol and the contents of messages exchanged
between clients and servers. Messages are operators, such as client
requests for read, write and query, and server responses, including
data-format information.

LDAP directory services versus the Sybase interfaces file

The LDAP server stores and retrieves information about:

• Adaptive Server, such as IP address, port number, and network protocol

• Security mechanisms and filters

• High availability companion server name
The LDAP server can be configured with these access restrictions:

• Anonymous authentication – all data is visible to any user.

• User name and password auth entication – Adaptive Server uses the default
user name and password for UNIX platforms:

• $SYBASE/$SYBASE_OCS/config/libtcl.cfg on 32-bit platfo rms

• $SYBASE/$SYBASE_OCS/config/libtcl64.cfg on 64-bit platforms

User name and password authentication properties establish and end a session
connection to an LDAP server.

Note The user name and password that are passed to the LDAP server for user

authentication purposes are distinct and different from those used to access
Adaptive Server.

Note LDAP user authentication is not supported on IBM AIX.

When an LDAP server is specified in the libtcl.cfg or libtcl64.cfg file
(collectively the libtcl*.cfg file) the server informatio n is acc essible only from
the LDAP server. Adaptive Server ignores the interfaces file.

If multiple directory services are supported in a server, then the order in which
they are searched is specified in libtcl*.cfg. Y ou cannot specify the search order
with the
page 77.

dataserver command-line option. See “Multiple directory services” on

LDAP directory services versus the Sybase interfaces
file

The LDAP driver implements directory services for use with an LDAP server .
LDAP directories are an infrastructure that provide:

70 Adaptive Server Enterprise

CHAPTER 6 Using the Lightweight Directory Access Protocol as a Directory Service

• A network-based alternative to the traditional Sybase interfaces file

• A single, hierarchical view of information, including users, software,

resources, networks, files, and so on

Table 6-1 highlights the differences between the Sybase interfaces file and an
LDAP server.

Table 6-1: interfaces file versus LDAP directory services

interfaces file Directory services

Platform-specific Platform-independent
Specific to each Sybase in stallation Centralized and hierarchical
Contains separate master and query entries One entry for each server that is accessed by both clients and servers
Cannot store metadata about the server Stores metadata about the server

LDAP directory services support more attributes than the Sybase interfaces
file. These attributes can include server version, server status, and so on. See
Table 6-2 for a list of attributes.

Note LDAP is only supported with reentrant libraries. You must use isql_r,

instead of isql, when connecting to a server using LDAP directory services.

Table 6-2 lists the Sybase LDAP directory entries.

Table 6-2: Sybase LDAP directory definitions

Attribute name Value type Description

ditbase interfaces file

or libtcl.cfg

dn Character

string
sybaseVersion Integer Server version number.
sybaseServername Character

string
sybaseService Character

string
sybaseStatus Integer Status: 1 = Active, 2 = Stopped, 3 = Failed, 4 = Unknown.

DIT base for object tree. If the libtcl.cfg file is specified, the
interfaces file is ignored. The libtcl.cfg file can be overridden with

ct_con_prop() for a specified connection.

Distinguished name. Must be unique name that identifies th e object.

Server name.

Service type: Sybase Adaptive Server, or Sybase SQL Server.

Configuration Gu ide 71

LDAP directory services versus the Sybase interfaces file

Attribute name Value type Description

sybaseAddress String Each server address includes:

• Protocol: TCP, NAMEPIPE, SPX DECNET (entry is case
sensitive).

• Address: any valid address for the protocol type.

Note dscp splits this attribute into T ranspor t type and Transport
address.

sybaseSecurity (optional) String Security OID (object ID).
sybaseRetryCount Integer This attribute is mapped to CS_RETRY_COUNT, which specifies

the number of times that ct_connect retries the sequence of network
addresses associated with a server name.

sybaseRetryDelay Integer This attribute is mapped to CS_LOOP_DELAY, which specifies the

ct_connect waits before retrying the entire

sybaseHAservername
(optional)

delay, in seconds, that
sequence of addresses.

String A secondary server for failover protection.

The traditional interfaces file with TCP connection and a failover machine
looks like:

master tcp ether huey 5000
query tcp ether huey 5000
hafailover secondary

An example of an LDAP entry with TCP and a failover machine looks like:

dn: sybaseServername=foobar, dc=sybase,dc=com
objectClass: sybaseServer
sybaseVersion: 1500
sybaseServername: foobar
sybaseService: ASE
sybaseStatus: 4
sybaseAddress: TCP#1#foobar 5000
sybaseRetryCount: 12
sybaseRetryDelay: 30
sybaseHAServernam: secondary

All entries in the LDAP directory service are called entities. Each entity has a
distinguished name (DN) and is stored in a hi erarchical tree structure based on
its DN. This tree is call the directory information tree (DIT). Client
applications use a DIT base to specify where entities are stored. See

“The

libtcl*.cfg file” on page 73.

72 Adaptive Server Enterprise

CHAPTER 6 Using the Lightweight Directory Access Protocol as a Directory Service

In the example above, the entry describes an Adaptive Server nam ed “foobar ”
listening on a TCP connection with a port number of 5000. This entity also
specifies a retry count of 12 (times) and a retry delay of 30 (seconds). Once a
client has found an address where a serv er res po nds, the login dialog between
the client and the server begins.

You can find a complete list of Sybase’s LDAP directory schema in UNIX
$SYBASE/$SYBASE_OCS/config.

In the same directory, there is also a file called sybase-schema.conf, which
contains the same schema, but uses a Netscape-specific syntax.

Since LDAP supports multiple entries for each attribute, each address attribute
must contain the address of a single server , including protocol, access type, and
address. See

sybaseAddress in Table 6-2.

For example, this is an LDAP entry for an Windows server listening on two
addresses, with different connection protocols:

sybaseAddress = TCP#1#TOEJAM 4444
sybaseAddress = NAMEPIPE#1#\pipe\sybase\query

Note Each entry in the address field is separated by the # character.

You can edit these entries with
services” on page 76.

To ensure cross-platform compatibility for all Sybase products, the pro tocol
and address attribute fields should be in a platform- and product-independent
format.

The libtcl*.cfg file

Y ou use the libtcl*.cfg file to specify the LDAP server name, port number, DIT
base, user name, and password to authenticate the connection to an LDAP
server.

The purpose of the libtcl*.cfg file is to provide configuration information such
as driver, directory, and security services for Open Client/Open Server and
Open Client/Open Server-based applications. 32-bit utilities such as

srvbuild, look up the libtcl.cfg, while 64-bit applications use the libtcl64.cfg file

for configuration information

dsedit. See “Adding a server to the directory

dsedit and

Configuration Gu ide 73

Enabling LDAP directory services

You should edit both th e libtcl.cfg and the libtcl64.cfg files to ensure
compatibility between 32- and 64-bit applications.

The default libtcl.cfg file is located in $SYBASE/$SYBASE_OCS/config.
If LDAP is specified in the libtcl.cfg file, the interfaces file is not used.

Note Open Client/Open Server applications that use the -I option at start-up

override the libtcl.cfg file and use the interfaces file.

In its simplest form, the libtcl.cfg file is in this format:

[DIRECTORY]
ldap=libsybdldap.dll ldapurl

where the ldapurl is defined as:

ldap://host:port/ditbase

The following LDAP entry, using these same attributes, is an anonymous
connection and only works only if the LDAP server allows read-only access.

ldap=libsybdldap.dll ldap://seashore/d=sybase,dc=com

You can specify a user name and password in the libtcl.cfg file as extensions to
the LDAP URL to enable password authentication at connection time.

Enabling LDAP directory services

To use a directory service, you must:
1 Configure the LDAP server according to the vendor-supplied

documentation.

2 Add the location of the LDAP libraries to the Unix load library path

environment variable for your platform.

3 Configure the libtcl.cfg file to use directory services.

Use any standard ASCII text editor to:

• Remove the semicolon (;) comment markers from the beginning of
the LDAP URL lines in the libtcl.cfg file under the [DIRECTORY]
entry.

74 Adaptive Server Enterprise

CHAPTER 6 Using the Lightweight Directory Access Protocol as a Directory Service

• Add the LDAP URL under the [DIRECTORY] entry. See Table 6-3

for supported LDAP URL values.

Warning! The LDAP URL must be on a single line.

libtcl.cfg
ldap+libsydblad.so ldap://host:port/ditbase??scope??bindname=username
password

libtcl64.cfg
ldap=libsydbldap64.so
ldap://host:port/ditbase??scope??bindname=username
password

For example:

[DIRECTORY]
ldap=libsydbldap.so ldap:///huey:11389/dc=sybase,dc=com??one??
bindname=cn=Manager,dc=sybase,dc=com secret

“one” indicates the scope of a s earch that retrieves entries one level below
the DIT base.

Table 6-3 defines the keywords for the ldapurl variables.

Table 6-3: ldapurl variables

Keyword Description Default

host (required) The hos t nam e or I P ad dr ess o f the ma chin e run nin g

the LDAP server

port The port number that the LDAP server is listening on 389
ditbase (required) The default DIT base None
username Distinguished name (DN) of the user to authenticate NULL (anonymous authentication)
password Password of the user to be authenticated NULL (anonymous authentication)

None

4 Verify that the appropriate environment variable points to the required

third-party libraries. The Netscape LDAP SDK libraries are located in
$SYBASE/$SYBASE_OCS/lib3p or lib3p64.The Unix load library path
environment variable must point to this directory.

5 Add your server entry to the LDAP server using

dscp or dsedit. See

“Adding a server to the direc tory services” on page 76.

Configuration Gu ide 75

Adding a server to the directory services

Adding a server to the directory services

Warning! Most LDAP servers ha ve an ldapadd utility for adding directory

entries. Sybase recommends you use
semantic checks that generic tools do not provide.

Each server entry is made up of a set of attributes. When you add or modi fy a
server entry, you are prompted for information about server attributes. Some
attributes are provided by default, others require user input. When a default
value is provided, it appears in brackets “[ ]”. See Table 6-2 for accepted
values.

dsedit instead since it has built-in

You can use

v Adding a server entry to the directory service using dsedit

srvbuild to add entries, but not modify or delete them.

Before you can ad d, delete, o r modif y an LDAP s erver entry, you must add t he
LDAP URL to the libtcl.cfg file. See “The libtcl*.cfg file” on page 73.

Use

dsedit to add a server to the directory service:

1 Source SYBASE.csh or SYBASE.sh to set the environment variables.
2

cd to $SYBASE/$SYBASE_OCS/bin.

3 Execute

dsedit.

4 Select LDAP from the list of servers, and click OK.
5 Click Add New Server Entry.
6Enter:

• The server name – this is required.

• The security mechanism – optional. This is the name of the high­availability failover server, if you have one.

7 Click Add New Network Transport and:

• Select the transport type from the drop-down list.

• Enter the host name.

• Enter the port number

8 Click OK two times to edit
To view the server entries, enter the following URL in Netscape

http://host:port/ditbase??one.

76 Adaptive Server Enterprise

dsedit.

CHAPTER 6 Using the Lightweight Directory Access Protocol as a Directory Service

For example:

ldap://huey:11389/dc=sybase,dc=com??one

Note Microsoft Internet Explorer does not recognize LDAP URLs.

For more information about
Guide, in the 11.1.x Generic Collection

http://www.sybase.com/support/manuals

dscp, see the Open Client/Server Configuration

at

.

Multiple directory services

Any type of LDAP service, whethe r it is a n actual server or a gateway to other
LDAP services, is called an LDAP server.

You can specify multiple directo ry services for high-availability failover
protection. Not every directory service in the list needs to be an LDAP server.

For example:

[DIRECTORY]
ldap=libsydbladp.so ldap://test:389/dc=sybase,dc=com
ldap=libsybdldap.so ldap://huey:11389/dc=sybase,dc=com

In this example, if the connection to test:389 fails, the connection fails over to
the DCE driver with the specified DIT base. If this also fails, a connection to
the LDAP server on huey:11389 is attempted. Different ven dors employ
different DIT base formats.

Note For more information, see the Open Client Client-Library/C

Programmer’s Guide and the Open Client Client-Library/C Reference Manual

at http://www.sybase.com/support/manuals.

Configuration Gu ide 77

Encrypting the password

Encrypting the password

Entries in the libtcl.cfg file are in human-readable format. Sybase provides a

pwdcrypt utility for basic password encryption. pwdcrypt is a simple algorithm

that, when applied to keybo ard input , generates an encrypted va lue that can be
substituted for the password.
$SYBASE/$SYBASE_OCS/bin.

From the $SYBASE/$SYBASE_OCS directory, enter:

bin/pwdcrypt

Enter your password twice when prompted.

pwdcrypt generates an encrypted password. For example:

0x01312a775ab9d5c71f99f05f7712d2cded2i8d0ae1ce78868d0e8669313d1bc4c706

Copy and paste the encrypted password into the libtcl.cfg file using any
standard ASCII-text editor. Before encryption, the file entry appears as:

pwdcrypt is located in

ldap=libsybdldap.so
ldap://seashore/dc=sybase,dc=com??one??bindname=uid=Manager,dc=sybase,
dc=com?password

Replace the password with the encrypted string:

ldap=libsybdldap.so
ldap://seashore/dc=sybase,dc=com??one??bindname=uid=Manager,dc=sybase,dc=com
0x01312a775ab9d5c71f99f05f7712d2cded2i8d0ae1ce78868d0e8669313d1bc4c706

Warning! Even if your password is encrypted, you s hould st ill protect i t using

file-system security.

Performance

Performance when using an LDAP server may be slower than when using an
interfaces file because the LDAP server requires time to make a network
connection and retrieve data. Since this connection is made when Adaptive
Server is started, changes in performance will be seen at login time, if at all.
During normal system load, the delay should not be noticeable. During high
system load with many connections, especially repeated connections with short
duration, the overall performance difference of using an LDAP server versus
the traditional interfaces file might be noticeable.

78 Adaptive Server Enterprise

CHAPTER 6 Using the Lightweight Directory Access Protocol as a Directory Service

Migrating from the interfaces file to LDAP

There is no direct method to upgrade an existing server using the interfaces file
to one that uses lightweight directory services. To upgrade a previous release
of Adaptive Server to Adaptive Server version 15.0, see the Installation Guide
for Windows.

Once you have upgraded the server, you can configure your server to use
LDAP service.

1 Shut down the server. See Chapter 2, “Starting and Stopping Servers.”
2 Edit the $SYBASE/$SYBASE_OCS/config/libtcl.cfg or libtcl64.cfg file to

add the directory service. See “Enabling LDAP directory services” on
page 74.

3Use

dsedit and add the server entry to directory service. See “Adding a

server to the directory services” on page 76.

4 Restart your server.

Configuration Gu ide 79

Migrating from the interfaces file to LDAP

80 Adaptive Server Enterprise

CHAPTER 7

Customizing Localization for
Adaptive Server

This chapter provides information about Sybase localization support for
international installations, including configuring languages, character
sets, and sort order. For more information, see the System Admini stra tion
Guide.

Topic Page

Overview of localization support 81
Character set conversion 89
Sort orders 90
Language modules 93
Localization 94
Changing the localization configuration 97

Overview of localization support

Localization is the process of setting up an application to run in a
particular language or country environment, including translated system
messages and correct formats for date, time, and currency. Adaptive
Server supports localization for international customers and for customers
with heterogeneous environments.

This support includes:

• Data processing support – Adaptive Server comes with character set
and sort order de finiti on fil es i t us es to process the characters us ed in
different languages.

Sybase provides support for the major languages in:

• Western Europe

•Eastern Europe

•Middle East

Configuration Gu ide 81

Overview of localization support

• Latin America

•Asia

• Trans lated system messages – Adaptive Server includes language modules
for:

• Brazilian Portuguese

• Chinese (Simplified)

•French

•German

• Japanese

• Korean

• Polish

•Spanish

• Translated documentation – translated documentation is available in:

Language modules

Adaptive Server stores its localized software messages in separate language
modules.

When you install a language module, the installation program loads the
messages, character set, and sort-order files that support the new language in
the correct locations.

•Thai

• Chinese (Simplified)

•French

•German

• Japanese

• Korean

When you install Adaptive Server and Backup Server, system messages in
English are installed by default.

82 Adaptive Server Enterprise

CHAPTER 7 Customizing Localization for Adaptive Server

Default character sets for servers

The default character set is the character set in which data is encoded and stored
on the Adaptive Server databases.

Changing the default language and character set

Warning! Make all changes to the character set and sort orde r for a new

Adaptive Server before creating any user database s or maki n g any changes t o
the Sybase-supplied databases. Changing the character set and sort order after
data or data structures have been added to Adaptive Server may require
additional steps. T o change the character set or sort order after you have added
data, see the System Administration Guide.

srvbuild configures a new Adaptive Server, it displays a message box

After
asking if you want to localize your Adaptive Server to a language other than
us_english and if you want to use a character set or sort order other than the
default.

srvbuild creates an Adaptive Server with the following defaults:

• us_english language

• iso_1 character set (on HP-UX platforms, use Roman8)

• Binary sort order
V a lid language options depen d on what language modul es were unloaded from

the distribution media onto your system.
All character sets are copied from the distribution media by default.
You can:

• Click No to accept the defaults.

• Click Yes to change the defaults.

The

sqlloc menu is displayed. sqlloc is the GUI utility used to change

default languages, character sets, and sort orders.

By default, when Adaptive Server and Backup Server are installed on IBM,
and SUN Solaris systems, the installation installs the character set files for ISO
8859-1, which supports the Western European languages.

Configuration Gu ide 83

Overview of localization support

By default, when Adaptive Server and Backup Server are installed on HP
systems, the installation installs the character set files for ROMAN8, which
supports the Western European languages.

Changing the default character set for server s

You can select any character set as the default on Adaptive Server, including
character sets that are not the platform default character sets. Keep the
following guidelines in mind when selecting a new default character set:

• To avoid co nversion errors or overhead, determine the default character
set based on the character set used by your clients.

For example, if most of your clie nts use ISO 8859-1, you can minimize the
amount of data conversion that has to occur by specifying ISO 8859-1.

• If your server is operating in a heterogeneous language environment,
choose a character set that works with all the character sets needed. Often,
this is Unicode (UTF-8).

Warning! Make all chang es to the default character set and sort order for a new

Adaptive Server before creating any user databases or making any chan ges to
the Sybase-supplied databases. Changing the character set and sort order after
data or data st ructures h ave been adde d to Adaptive Server can cause incorrect
behavior. To change the character set or sort order after you have added data,
see the System Administration Guide.

Supported character sets

The following language, scripts and character sets are supported by Adaptive
Server:

• Arabic – see Table 7-1 on page 85.

• Baltic – see Table 7-2 on page 85.

• Chinese, Simplified – see Table 7-3 on page 86.

• Chinese, Traditional – see Tabl e 7-4 on page 86

• Cyrillic – see Table 7-5 on page 86.

• Eastern European – see Table 7-6 on page 86.

• Greek – see Table 7-7 on page 87.

84 Adaptive Server Enterprise