Sybase 12.5.1 User Manual

User’s Guide

Historical Server

12.5.1

DOCUMENT ID: DC36556-01-1251-01
LAST REVISED: August 2003

Copyright © 1989-2003 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 agreement may contact Customer Fulfillment 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, the Sybase logo, AccelaTrade, ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture,
Adaptive Server, Adaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server
Enterprise Replication, Adaptive Server Everywhere, Adaptive Server IQ, Adaptive W arehouse, Anywhere Studio, Application
Manager, AppModeler, APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-FORMS, AP T-Translator, APT-Library, AvantGo,
AvantGo Application Alerts, AvantGo Mobile Delivery, AvantGo Mobile Document Viewer, AvantGo Mobile Inspection, AvantGo
Mobile Marketing Channel, AvantGo Mobile Pharma, AvantGo Mobile Sales, A vantGo Pylon, AvantGo Pylon Application Server,
AvantGo Pylon Conduit, AvantGo Pylon PIM Server, AvantGo Pylon Pro, Backup Server, BizTracker, ClearConnect, Client-Library,
Client Services, Convoy/DM, Copernicus, Data Pipeline, Data Workbench, DataArchitect, Database Analyzer, DataExpress, DataServer,
DataWindow , DB-Library , dbQueue, Developers W orkbench, Direct Connect Anywhere, DirectConnect, Distribution Director, e -ADK,
E-Anywhere, e-Biz Integrator, E-Whatever, EC Gateway, ECMAP, ECR TP, eFulfillment Accelerator, Embedded SQL, EMS, Enterprise
Application Studio, Enterprise Client/Server, Enterprise Connect, Enterprise Data Studio, Enterprise Manager, Enterprise SQL Server
Manager, Enterprise Work Architecture, Enterprise Work Designer , Enterprise Wor k Modeler, eProcurement Accelerator, EWA,
Financial Fusion, Financial Fusion Server, Gateway Manager, GlobalFIX, ImpactNow, Industry Warehouse Studio, InfoMaker,
Information Anywhere, Information Everywhere, InformationConnect, InternetBuilder, iScript, Jaguar CTS, jC onne c t for J DBC, Mail
Anywhere Studio, MainframeConnect, Maintenance Express, Manage Anywhere Studio, M-Business Channel, M-Business Network,
M-Business Server , MDI Access Server , MDI Database Gat eway , media.splash, MetaWorks , My A vantGo, My A vantGo Media Channel ,
My AvantGo Mobile Marketing, MySupport, Net-Gateway, Net-Library, New Era of Networks, ObjectConnect, ObjectCycle,
OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, Open Biz, Open Client, Open ClientConnect, Open Client/Server, Open
Client/Server Interfaces, Open Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++, PB-Gen, PC APT Execute, PC
Net Library, PocketBuilder, Pocket PowerBuilder, Power++, power.stop, PowerAMC, PowerBuilder, PowerBuilder Foundation Class
Library, PowerDesigner, PowerDimensions, PowerDynamo, PowerJ, PowerScript, PowerSite, PowerSocket, Powersoft, PowerStage,
PowerStudio, PowerTips, Powersoft Portfolio, Powersoft Professional, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst,
Rapport, Report Workbench, Report-Execute, Replication Agent, Replication Driver, Replication Server, Replication Server Manager,
Replication Toolkit, Resource Manager, R W -DisplayLib, S-Designor , SDF , Secure SQL Server, Secur e SQL T oolset, Security Guardian,
SKILS, smart.partners, smart.parts, smart.script, 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, STEP, SupportNow, S.W.I.F.T.
Message Format Libraries, Sybase Central, Sybase Client/Server Interfaces, Sybase Financial Server, Sybase Gateways, Sybase MPP,
Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase User W ork bench, SybaseWare, Syber Financial,
SyberAssist, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data Stream, TradeForce, Transact-SQL,
Translation Toolkit, UltraLite.NET, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Viewer, Visual
Components, VisualSpeller, VisualWriter, VQL, Wa rehouseArchit e ct, Warehouse Control Center, Ware hous e Studio, Warehouse
WORKS, Watcom, W atcom SQL, Watcom SQL Server, Web Deployment Kit, Web.PB, W eb.SQL, W ebSights, WebV iewer , W orkGroup
SQL Server, XA-Library, XA-Server and XP Server are trademarks of Sybase, Inc. 03/03

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

Description of Adaptive Server Enterprise Monitor .......................... 1

Adaptive Server Monitor components....................................... 1

Adaptive Server Monitor architecture........................................ 2

Adaptive Server Enterprise Monitor architecture.............................. 3

Historical Server concepts......................................................... 3

CHAPTER 2 Configuring Historical Server ........................................................ 9

Historical Server configuration concepts.......................................... 9

The Historical Server control file and home directory................ 9

The operating system start-up account................................... 10

The Historical Server superuser account ................................ 11

Sybase Open Client/Server connections................................. 11

Initial configuration on UNIX platforms........................................... 12

Assumptions on UNIX platforms ............................................. 12

Configuration procedures on UNIX platforms.......................... 12

Initial configuration on Windows NT............................................... 15

Assumptions on Windows NT ................................................. 15

Results of installation on Windows NT.................................... 16

Configuration procedures on Windows NT.............................. 16

Setting Historical Server start-up parameters ................................ 20

Function................................................................................... 20

Syntax ..................................................................................... 20

Parameters.............................................................................. 20

Configuring multiple instances of Historical Server........................ 23

When to create multiple instances of Historical Server........... 23

Configuring an additional Historical Server on UNIX platforms 24
Configuring an additional Historical Server on Windows NT... 25

CHAPTER 3 Starting and Stopping Historical Server..................................... 33

Starting and stopping Historical Server on UNIX platforms............ 33

User’s Guide iii

Contents

Starting Historical Server on UNIX.......................................... 33

Stopping Historical Server on UNIX........................................ 34

Starting and stopping Historical Server on Windows NT ............... 36

Starting Historical Server on Windows NT.............................. 37

Inferring start-up parameters from the NT Registry................. 37

Verifying that Historical Server is running ............................... 38

Stopping Historical Server on Windows NT ............................ 38

CHAPTER 4 Command Reference..................................................................... 43

Command summary....................................................................... 43

Command syntax........................................................................... 44

Command status and errors........................................................... 45

Script files as input to Historical Server.......................................... 46

Connecting to Historical Server...................................................... 46

Assumptions before connection.............................................. 46

How to connect........................................................................ 47

Required permissions for Historical Server activities.............. 47

Mutually exclusive sessions.................................................... 49

Historical Server commands .......................................................... 50

hs_create_alarm ............................................................................ 51

hs_create_filter............................................................................... 54

hs_create_playback_session......................................................... 57

hs_create_playback_view.............................................................. 67

hs_create_recording_session........................................................ 69

hs_create_view.............................................................................. 72

hs_delete_data............................................................................... 73

hs_initiate_playback....................................................................... 74

hs_initiate_recording...................................................................... 75

hs_list............................................................................................. 75

hs_playback_sample...................................................................... 79

hs_shutdown.................................................................................. 83

hs_status........................................................................................ 85

hs_terminate_playback.................................................................. 86

hs_terminate_recording ................................................................. 86

CHAPTER 5 Data Files........................................................................................ 89

Overview of Historical Server data files ......................................... 89

Description of Historical Server files........................................ 89

Permissions on files ................................................................ 90

General file format................................................................... 90

Control file...................................................................................... 91

Header record ......................................................................... 91

Session control record............................................................. 92

iv

Historical Server

Contents

View control record.................................................................. 94

Data item control record.......................................................... 94

Alarm control record................................................................ 94

Filter control record ................................................................. 95

Data file.......................................................................................... 95

Error message file.......................................................................... 96

Script file ........................................................................................ 97

Script file table names............................................................. 97

Script file table column names ................................................ 97

Passing script file commands.................................................. 98

Script use example.................................................................. 98

Bulk copy example......................................................................... 99

Example ................................................................................ 100

Cut utility example........................................................................ 101

APPENDIX A Data Items........................... ....... ...... ....... ..................................... 103

Table of data items and definitions .............................................. 103

APPENDIX B Specifications for Defining Recording Session Views............ 121

Definition of key and result........................................................... 121

Designing recording session views.............................................. 122

Using the Process ID............................................................. 122

Using the application name................................................... 123

Empty rows versus no rows in views..................................... 123

Table of valid key and result data item combinations .................. 124

Examples of valid combinations............................................ 146

Examples of invalid combinations......................................... 147

Table of valid statistic types for data items .................................. 147

APPENDIX C Specifications for Defining Playback Views............................. 157

Summarization level details ......................................................... 157

Raw playback........................................................................ 158

Actual playback..................................................................... 158

Entire playback...................................................................... 159

Playback with user-defined intervals..................................... 160

Summary of summarization intervals.................................... 161

Designing playback views............................................................ 162

Rules for specifying input sessions....................................... 162

Relationship of input views to playback views....................... 162

Rules for defining views ........................................................ 163

Table of data item requirements for playback views.................... 165

Additional information about some data items............................. 170

User’s Guide v

Contents

Using “Timestamp”, “Timestamp Datim”, and “Elapsed Time” 170

APPENDIX D Examples of Recording Session Views..................................... 173

Cache performance summary...................................................... 174

Database object lock status......................................................... 175

Database object page I/O ............................................................ 175

Data cache activity for individual caches ..................................... 176

Data cache statistics for recording session.................................. 177

Data cache statistics for sample interval...................................... 177

Device I/O for recording session.................................................. 178

Device I/O for sample interval...................................................... 178

Device I/O performance summary ............................................... 179

Engine activity.............................................................................. 179

Lock performance summary......................................................... 179

Network activity for recording session.......................................... 180

Network activity for sample interval.............................................. 180

Network performance summary................................................... 181

Page I/O....................................................................................... 181

Procedure cache statistics for recording session......................... 182

Procedure cache statistics for sample interval............................. 182

Procedure page I/O...................................................................... 183

Process activity............................................................................ 183

Process database object page I/O............................................... 184

Process detail for locks ................................................................ 185

Process detail page I/O................................................................ 185

Process locks............................................................................... 186

Process page I/O ......................................................................... 186

Process state summary................................................................ 187

Process stored procedure page I/O ............................................. 187

Server performance summary...................................................... 188

Stored procedure activity ............................................................. 188

Transaction activity ...................................................................... 189

Index ........................................................................................................................................... 191

vi

Historical Server

About This Book

Adaptive Server Enterprise Monitor Historical Server User’s Guide
describes how to use Sybase® Adaptive Server® Enterprise Monitor
Historical Server version 12.5.1 (Historical Server). Historical Server is a
Sybase Open Server™ application that obtains performance statistics on
Sybase SQL Server™ version 11.0 and Adaptive Server Enterprise
version 1 1.5 and later.

Audience

How to use this book

This book is for people responsible for:

• Configuring and managing Historical Server

• Using Historical Server to monitor Adaptive Server performance
This book contains the following chapters:

• Chapter 1, “Introduction” provides an overview of Adaptive Server
Enterprise Monitor and presents some basic Historical Server
concepts.

• Chapter 2, “Configuring Historical Server” describes how to
complete an initial Historical Server configuration or change a
configuration, for both UNIX and Windows NT platforms.

• Chapter 3, “Starting and Stopping Historical Server” describes how
to start and stop Historical Server on both UNIX and Windows NT
platforms.

• Chapter 4, “Command Reference” describes the
interface to Historical Server.

• Chapter 5, “Data Files” describes the files that Historical Server
creates and how to access the data in them, including how to use the

bcp utility to load the data into Adaptive Server tables.

• Appendix A, “Data Items” provides descriptions of the data items
available through Historical Server.

isql command

• Appendix B, “Specifications for Defining Recording Session
Views” describes valid combinations of dat a item names and statisti c
types for defining recording session views.

User’s Guide vii

• Appendix C, “Specifications for Defining Playback Views” describes
valid combinations of data item names and statistic types for defining
playback session views.

• Appendix D, “Examples of Recording Session Views” provides examples
of recording session views.

Related documents

The following documents comprise the Sybase® Adaptive Server® Enterprise
documentation set:

• 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 installati on, upgrade,
and configuration procedures for all Adaptive Server and related Sybase
products.

• What’s New in Adaptive Server Enterprise? – describes the new features
in Adaptive Server version 12.5.1, the system changes added to support
those features, and the changes that may affect y our existin g app lications.

• ASE Replicator User’s Guide – describes how to use the ASE 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.

• Configuring Adaptive Server Enterprise for your platform – provides
instructions for performing specific configuration tasks for Adaptive
Server.

• EJB Server User’s Guide – explains how to use EJB Server to deploy and
execute Enterprise JavaBeans in Adaptive Server.

• Error Messages and Troubleshooting Guide – explains how to resolve
frequently occurring error messages and describes solu tions to system
problems frequently encounte red by users.

• Full-T ext Search Sp ecialty Data Stor e User’ s Guide – describes how to use
the Full-Text Search feature with Verity to search Adaptive Server
Enterprise data.

viii Historical Server

About This Book

• Glossary – defines technical terms used in the Adaptive Server

documentation.

• Historical Server User’s Guide – describes how to use Historical Se rver to

obtain performance information for SQL Server

®

and Adaptive Server.

• 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.

• jConnect for JDBC Programmer’s Reference – describes the jConnect™

for JDBC™ product and explains how to use it to access data stored in
relational database management systems.

• Job Scheduler User's Guide – provides instructions on how to instal l and

configure, and create and schedule jobs on a local or remote Adaptive
Server using the command line or a graphical user interface (GUI).

• 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.

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

• Optimizer and Abstract Plans – describes how t he optimizer
processes queries and how abstract plans can b e used to chang e some
of the optimizer plans.

• Monitoring and Anal yzing – explains how statistics are obtained and
used for monitoring and optimizing performance.

• Quick Reference Guide – provides a comp rehensive listing of the names
and syntax for commands, fun ctions, system pr ocedures, extended s ystem
procedures, datatypes, and utilities in a pocket-sized book.

• Reference Manual – is a series of four books that contains the following
detailed Transact-SQL

User’s Guide ix

®

information:

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

variables, expressions, identifiers and 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 Administration Gui de – provides in-depth information about
administering servers and databases. This manual includes instructions
and guidelines for manag ing phy sical reso urces, secur ity, 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 Guide – documents Transact-SQL, Sybase’s
enhanced version of the relational dat abase la nguage. This manual ser ves
as a textbook for beginning users of the database management system.
This manual also contains descriptions of the

pubs2 and pubs3 sample

databases.

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

• 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.

• 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 ma pping functions
that comprise XML Services.

x Historical Server

About This Book

Other sources of
information

Sybase certifications
on the Web

Use the Sybase Getting Started CD, the Sybase Technical Librar y CD and the
T echnical Library Product Manual s W eb site to l earn 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 Technical Library CD. It is i ncluded with
your software. To read or print documents on the Getting Started CD you
need Adobe Acrobat Reader (downloadable at no charge from the Adobe
Web site, using a link provided on the CD).

• The T echnical Librar y CD contai ns product manuals and is incl uded wit h

your software. The DynaText reader (included on the Technical Library
CD) allows you to access technical information about your pr oduct in an
easy-to-use format.

Refer to the Technical Library Installation Guide in your documentation
package for instructions on installing and starting the Technical Library.

• The Technical Library Product Manuals Web site is an HTML version of

the Technical Library CD that you can access using a standard Web
browser. In addition to product manuals, you will find links to
EBFs/Updates, Technical Documents, Case Management, Solved Cases,
newsgroups, and the Sybase Developer Network.

T o access the Technical Library Product Manuals Web site, go to

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

.

Product

Technical documentation at the Sybase Web site is updated frequently.

❖ 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.

❖ 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 cr eate
a personali zed view of Sybase Web pages.

User’s Guide xi

Sybase EBFs and
software
maintenance

1 Point your Web browser to Technical Documents at

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

2 Click MySybase and create a MySybase profile.

❖ 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. Enter user name and password in for mati on, if

prompted (for existing Web accounts) or create a new account (a free
service).

3 Select a product.
4 Specify a time frame and click Go.
5 Click the Info icon to display the EBF/Maintenance report, or click the

product description to download the software.

Conventions used i n
this manual

The following table describes the style conventions used in this manual.

Description Examples

Command names, command parameters,
and other keywords appear in the text in

Helvetica typeface.

Variables, file names, path names, and
Adaptive Server table names appe ar in th e
text in italic typeface.

User input appears in

Computer output, such as error mes sages
and command outpu t, appears in
typeface.

Brackets indicate that the encl osed item is
optional. Do not type the brackets.

Curly braces indicate that you must choose
at least one of the enclosed options. Do not
type the braces.

Ellipses indicate that you may repeat the
preceding item multiple times in the
command. Do not include ellipses in your
command.

Courier typeface.

Courier

The -S parameter is required.

-Uusername

isql -Usybase -Psa

-Sserver1

Unable to attach with
shared memory.

[no_wait]

{0,1}

[, dataItemName, dataItemStat]. . .

xii Historical Server

About This Book

If you need help

Each Sybase installation that has pu rchased a support contract has one or more
designated people who are au th orized t o co ntact Sy bas e Technical Support. If
you cannot resolve a problem using the manuals or online help, please have the
designated person contact Sybase Technical Support or the Sybase subsidiary
in your area.

User’s Guide xiii

xiv Historical Server

CHAPTER 1

Introduction

Topic Page

Description of Adaptive Server Enterprise Monit or 1
Adaptive Server Enterprise Monitor architecture 3

Description of Adaptive Server Enterprise Mon itor

Adaptive Server Enterprise Monitor (Adaptive Server Monitor) provides
a way to monitor Adaptive Server performance in real time or in a
historical data-gathering mode. System administrators can use this
information to identify potential resource bottlenecks, to research current
problems, and to tune for better performance. Adaptive Server Monitor
provides feedback for tuning at several levels:

• Adaptive Server configuration

• Database design

• SQL statements in applications and stored procedur es

Adaptive Server Monitor components

Adaptive Server Monitor consists of four components that gather or
display Adaptive Server performance data:

• Adaptive Server Enterprise Monitor Server (Monitor Server) – this
server collects Adaptive Server performance data in real time and
makes the data available to the other Adaptive Server Monitor
components. Monitor Server is a Sybase Open Server application.

• Adaptive Server Enterprise Monitor Historical Server (Historical
Server) – this server obtains Adaptive Server performance data fro m
Monitor Server and saves the data in files for deferred analysis.
Historical Server is a Sybase Open Server application.

User’s Guide 1

Description of Adaptive Server Enterprise Monitor

• Monitors in the Adaptive Server Enterprise plug-in for Sybase Central™
(Monitor Viewer) – the monitors obtain Adaptive Server performance data
from Monitor Server and di splay the dat a in real time in tables and g raphs.

• Adaptive Server Enterprise Monitor C lient Library (Monitor Client
Library) – this application programming interface (API) to Monitor Server
and Historical Server is available to users for dev eloping mon i toring
applications. Historical Server and the monitors in the Adaptive Server
Enterprise plug-in for Sybase Central are Monitor Client Library
applications.

Adaptive Server Monitor architecture

Figure 1-1 shows the relationships between Adaptive Server and the various
components of Adaptive Server Monitor.

Figure 1-1: Adaptive Server and Adaptive S erver Monitor components

Shared memory

Adaptive Server

Enterprise

Monitor

Server

These servers must

reside on the same

computer.

Open

Client

Library

Open

Client

Library

Open

Client

Library

Adaptive Server Enterprise

client applications

including isql

Monitor

Client

Library

Monitor Viewer

in

Sybase Central

2 Historical Server

Historical

Monitor

Client

Library

Server

Monitor

Client

Library

Other Monitor

Client Library

applications

CHAPTER 1 Introduction

Adaptive Server Enterprise Monitor architecture

Adaptive Server saves performance data in a shared memory area that Monitor
Server reads. Because of this shared memory technique, Monitor Server must
be installed and running on the same machine as the Adaptive Server being
monitored. A one-to-one relationshi p exists between a n Adaptive Server and a
Monitor Server. For more information about Monitor Server, see the Sybase
Adaptive Server Enterprise Monitor Server User’s Guide.

Monitor Client Library applications obtain Adaptive Server performance
statistics from Monitor Server. These applications are clients of Monitor
Server. Fo r performance reasons, Sybase recommends run ning Monitor Client
Library applications on machines other than the ones where pairs of Adaptive
Server and Monitor Server are running. See the Sybase Adaptive Server
Enterprise Monitor Client Library Programmer’ s Guide for more information.

The Adaptive Server Enterprise plug-in for Sybase Central includes a set of
monitors showing different aspects of Adaptive Server resource usage at
various levels of detail. Each open monitor is a separate application, with a
unique client connection to Monitor Server. In Sybase Central, each Adaptive
Server installation has its own Monitors folder containing the set of m onitor
objects.

Historical Server collects performance information from Monitor Server and
saves the information in files for deferred analysis. Historical Server interfaces
let users specify the data to collect and the time period desired. They also
include a historical data playback feature. The interfaces are:

• A command interface in

Adaptive Server Enterprise Monitor Historical Server User’s Guide.

• A programming interface using Monitor Client Library. For more

information, see Sybase Adaptive Server Enterprise Monitor Client
Library Programmer’s Guide.

isql. For more information, see the Sybase

Historical Server concepts

This section describes the following Historical Server concepts:

• Recording sessions

• Playback sessions

•Views

• Data items and statis tic types

User’s Guide 3

Adaptive Server Enterprise Monitor architecture

Recording sessions

Recording sessions gather Adaptive Server performance data and store it in
files for later analysis. Some attributes of a recording session are:

• Monitor Server name – by association, this defines the Adaptive Server
whose performance you are monitoring.

• Sample interval – this attribute defines how often to collect performance
data.

• Views, alarms, and filters – views and filters define the data you want to
collect. Alarms define actions that can occur when a specified data item
hits a predefined threshold value.

• Start time and end time – these specificat ions define the time period du ring
which you want to collect the data.

To create a recording session, use a sequence of commands in the Historical
Server

isql command interface:

•

hs_create_recording_session

•

hs_create_view

•

hs_create_filter (optional)

•

hs_create_alarm (optional)

•

hs_initiate_recording

When you create a recording session, Historical Server assigns it a session ID.
You can list the session IDs of defined recording sessions using the
command.

hs_list can also show the complete recording session definition,

hs_list

including view names and the data items, alarms, and filters in the view.
Historical Server stores these recording session definitions in its control file,

which resides in the Historical Server home directory . Therefore,

hs_list can see

only recording session definitions that were created by Historical Server
instances using the same home directory that the current Historical Server is
using. See “Configuring multiple instances of Historical Server” on page 23
for more information on configuring Historical Server home directories.

To examine the data gathered by a recording session, you can:

• Populate Adaptive Server tables with the data from recording sessions by
using the Sybase bulk copy (

bcp) utility. See “Bulk copy example” on

page 99 for more information.

• Initiate a Historical Server playback session.

4 Historical Server

Playback sessions

CHAPTER 1 Introduction

Playback sessions let you retrieve the data gathered during one or more
recording sessions. You can play back data in two forms:

• Playback to a client – the results of the playback are sent to the user, who

can view the results on the terminal or redirect them to a file.

• Playback to a file – the results of the playback are stored in a file. The

resulting files are essentially a new recording session. You can use these
files as input to yet another playback session, or as input to the

bcp utility

to populate Adaptive Server tables, or any other way that you would use
recording session files.

The following attributes define a playback session:

• Input recording sessions – the input to a playback session is one or more

recording sessions.

• Views, start time, and end time – these attributes def ine the data fro m the

input recording sessions that you want to include in the playback session.

• Summarization level – you can specify raw playback, which shows you

exactly what was recorded, or you can specify various summarization
levels.

To create a playback session, use the following sequence of commands from
the Historical Server command interface:

•

hs_create_playback_session

•

hs_create_playback_view

• hs_initiate_playback

• hs_playback_sample (used only for playback to a client)

•

hs_terminate_playback

Views

A recording session view defines the performance data you want Historical
Server to gather. A playback session view defines which performance data
from a recording session view you want Historical Server to play back.

A view consists of a view name and one or more data items. Each data has a
statistic type associated with it. See “Data items and statistic types” on page 6
for more information.

User’s Guide 5

Adaptive Server Enterprise Monitor architecture

When you define a recording session, you define one or more views to be
included in that recording session. A recor ding se ssion must have at least one
view. For more information about creating recording session views, see

hs_create_view on page 72.

Appendix D, “Examples of Recording Session Views” contains many sa mple
recording session views.

When you define a playb ack session, y ou define whi ch views in t he previously
defined recording sessions should be included in the playback session. The
playback session view names must be the same as the names used for the
recording sessions views. You can include all data items or a subset of the data
items from the recording session view in the corresponding playback view . For
more information about creating playback views, see

on page 67

.

Data items and statistic types

A data item identifies specific information that you want to include in the
view. If a data item includes embedded spaces, you must surround the name
with quotation marks when you use it. S ome sam pl e dat a item s are: Page I/O,
Login Name, and CPU Time.

hs_create_playback_view

Table A-1 on page 103 lists all available data items and describes each one.
Each data item has a statistic t ype associated with it. The statistic type defines

the duration of the data item (sample or session) and whether Historical Server
performs calculations on the data item.

The statistic types contain embedded spaces. You must surround them with
quotation marks when you use them in the Historical Server commands.

Not all statistic types are valid with all of the data items. Table B-3 on page 148
shows valid statistic types for each data item.

The six statistic types are:

•

“Value for Sample” – this statistic type returns a count of activity or some

type of information that applies to the most recent sample interval. It
implies no calculations.

• Activity Counts – for data items that represent activity counts, this

statistic type returns the number of occurrences of an activity during
the most recent sample interval. For example, Value for Sample for
Page I/O is the number of page I/Os that occurred during the most
recent sample interval.

6 Historical Server

CHAPTER 1 Introduction

• Other information – this is the only statistic type valid for data items
that represent character strings. For example, Value for Sample for
Object Name returns the name of a table. This statistic type is also the
only one valid for data items that represent values such as IDs and
values for configured parameters, such as Process ID and Code
Memory Size.

•

“Value for Session” – this statistic type returns a cumulative count of

activity since the start of gathering the data (since the connection was
opened). No calculations are performed. For example, Value for Session
for Page I/O is the number of page I/Os that occurred since the record ing
session started .

•

“Rate for Sample” – this statistic type calculates a rate per second. It returns

the average number of occurrences per second of an activity during the
most recent sample interval. For example, Rate for Sample fo r Page I/O is
the average number of page I/Os that occurred each second during the
most recent sample interval.

The calculation is:

Count for the most recent sample interval

--------------------------------------------------------------------------------------------------- ­Number of seconds in the sample interval

•

“Rate for Session” – this statistic type calculates a rate per second. It returns

the average number of occurrences per second of an activity during the
current recording session. For example, Rate for Session for Page I/O is
the average number of page I/Os that occurred per second since the
recording se ssion started.

The calculation is:

Count for the session

-------------------------------------------------------------------------------­Number of seconds in the session

•

“Average for Sample” – this statistic type calculates an average value per

occurrence of an activity over the most recent sample interval. Only a few
data items can use this statistic type. The meaning of the returned value
depends on the data item. For example, Average for Sample for Procedure
Elapsed Time is the average execution time per execution of a stored
procedure during the most recent sample interval.

User’s Guide 7

Adaptive Server Enterprise Monitor architecture

• “Average for Session” – this statistic type calculates an average value per
occurrence of an activity over the session. Only a few data items can use
this statistic type. The meaning of the return ed value dep ends on t he data
item. For example, A verage for Session for Procedure Elapsed T ime is the
average execution time per execution of a stored procedure during the
recording session.

Table B-3 on page 148 shows valid combinations of data items and statistic
types.

8 Historical Server

CHAPTER 2

Configuring Historical Server

Topic Page

Historical Server configuration concepts 9
Initial configuration on UNIX platforms 12
Initial configuration on Windows NT 15
Setting Historical Server start-up parameters 20
Configuring multiple instances of Historical Server 23

Historical Server configuration concepts

This section describes concepts that you should understand before
configuring Historical Server including:

• The Historical Server control file and home directory

• The operating system start-up account

• The Historical Server superuser account

The Historical Server control file and home directory

The Historical Server control file maintains information about recording
sessions that users create. This information persists across start-ups, so
users can access recording sessions that they created during previous
executions of Historical Server. The control file restricts user access to
private recording session files. (Recording session files can have public or
private access.)

The Historical Server home directory is important for two reasons:

• It contains the Historical Server control file. When Historical Server
starts, it looks for a control file in the home directory. If a control file
does not exist, Historical Server creates it.

User’s Guide 9

Historical Server configuration concepts

• It is the default directory location for the data files that Historical Server
writes during recording sessions. The users who create the recording
sessions can override this default location.

The

-D parameter in the Historical Server start-up command specifies the home

directory location. This is a required parameter.
The current execution of Historical Serve r can access d ata files fr om previous

executions only if the current execution is using the same control file, in the
same home directory, as the previous executions were using. Therefore, in
most cases, you should not change the Historical Server home directory
between start-ups. See “Configuring multiple instances of Historical Server”
on page 23 for a discussion about using different home directories.

For more information about the files created by Historical Server, see Chapter
5, “Data Files.”

Accessing control file information

Use the Historical Server hs_list command to gain access to the information in
the Historical Server control file.

Do not edit the control file

Do not edit the control file. You might inadvertently corru pt it. Regard less of
the editor you use, do not open and then save this file.

This is true especially if Historical Server is running on Windows NT. Unlike
the other files created by Historical Server, the control file is not a standard­format Windows NT text file. Lines of text in the control file are terminated
only with newline characters, rather than the usual carriage-return/newline
pairs. The editing prog ram may corr upt the file by embedding unwanted
carriage-return/newline pairs into the text.

The operating system start-up account

The account that starts Historical Server must satisfy these conditions:

• The same account must start Historical Server each time.

10 Historical Server

CHAPTER 2 Configuring Historical Server

The operating system account that starts Historical Server the first time,
when Historical Server creates the control file, is the only account that has
subsequent access to that control file. The same account must perform all
subsequent start-ups of Historical Server using the same home directory,
to gain access to the control file. This restriction prevents unauthorized
reading and modification of Historical Server files.

A different account can start Historical Server if the start-up command
specifies a different home directory . In the new location, if no control
exists, Historical Server creates one. The recording session data files in a
home directory are not visible to a Historical Server using a d ifferent home
directory.

• The account must have search (execute) and write access to the Historical

Server home directory specified in the start-up command.

• The account must have search (execute) and write access to the locations

of recording session data files, as specified by users who create recording
sessions. The default location is the His torical Serv er hom e d irectory, but
users can override that default on a session-by-session basis wh e n they
create recording sessions.

The Historical Server superuser account

The -U parameter in the Historical Server start-up command can optionally
specify a superuser for Historical Server. If this parameter is specified, the
superuser can:

• Shut down Historical Serv er

• Vie w or delete any hist o ri cal data files
If the start-up command does not include the

Historical Server, but no user has unrestricted access to historical data files.

-U parameter, any user may stop

Sybase Open Client/Server connections

Historical Server establishes client/server connections using either interfaces
files (the interfaces file on UNIX; sql.ini file on Windows NT) or a directory
service, as supported by Sybase Open Client/Server version 11.1.x.

User’s Guide 11

Initial configuration on UNIX platforms

The advantage of using a directory service is that you do not need t o update the
interfaces or sql.ini files on all of the client machines. A single directory
service entry replaces these files. Changes such as moving a server to a new
address or changing the server name are easier to administer.

See Open Client/Server Configuration Guide for UNIX or Open Client/Server
Configuration Guide for Desktop Platforms for more information.

Initial configuration on UNIX platforms

This section describes ho w to co nfi gu re Hi storical Server on UNIX platforms.

Assumptions on UNIX platforms

The instructions in this section are based on the following assu mptions:

• Historical Server software was unloaded from the delivery media using the

instructions provided with the delivery media.

• An Adaptive Server/Monitor Server pair is configured on your network.

Configuration procedures on UNIX platforms

To configure Historical Server on a UNIX platform:
1 Set the $SYBASE environment variable to the value of the Sybase

installation directory where you unloaded Historical Server.

2 Log on using the “sybase” account or another account that has read, write,

and search (execute) permissions on the $SYBASE directory.

3 Set the $PATH environment variable.

The Historical Server executable resides in $SYBASE/bin. Add this path
name to the $PATH environment variable for the account that will start
Historical Server.

4 Create a script file for Historical Server start-up.

12 Historical Server

CHAPTER 2 Configuring Historical Server

A script file ensures that correct parameters are used for each Historical
Server start-up. The script file contains the Historical Server start-up
command,

histserver, and its parameters.

To create a Historical Server script file:
a Using any editor, create a new file. The recommended name and

location for the new file is:

install_dir/install/run_histServerName,

where histServerName is the name of the Historical Server.

b Edit the new file, inserting the

histserver command and supplying

parameters and values appropriate to your installation. Do not use
carriage returns within the command; use the UNIX continuation
character (\) to continue the command on multiple lines. Spaces
between a parameter and its value are optional.

Table 2-1 on page 21 describes the command and its parameters. The
parameters marked “required” in the table must appear in the script
file. The ones with default values may be omitted if the default values
are acceptable.

A sample script file for starting Historical Server follows:

histserver -Dserver1HistDir -Sserver1Hist \

-Usa -PsaPasswd \

-lserver1HistLog -n15 &

cUse the chmod command to give the account that will start Historical

Server execute permission on the script file.

5 Add connectivity information for Historical Server.

This task assigns a port or network address to Historical Server. It also
ensures that Historical Server can connect to one or more Adaptive
Server/Monitor Server pairs.

Add Historical Server connection information either to the interfaces files
or to a directory service. See Open Client/Server Configuration Guide for
UNIX for information on

dsedit, dscp, dsedit_dce, and dscp_dce.

If you are relying on interfaces files for m aking cli ent/server connections:
a C heck th e ser ver listings in the interfaces file used by Historical

Server. For Historical Server to run, this file must contain entries for
all of the following servers:

• Any Adaptive Server you want to monitor

User’s Guide 13

Initial configuration on UNIX platforms

• A Monitor Server paired with each Adaptive Server

• Historical Server

b Use either

dsedit (if your system is running X-Windows) or dscp (a

command line utility) to add entries to an interfaces file. Follow the
instructions in Open Client/Server Configuration Guide for UNIX. To
add these entries, you must know the:

• Monitor Server and Adaptive Server names to which you want
Historical Server to connect.

• Port numbers or network addresses assigned to these servers
when they were configured. To research this information, use

dsedit or dscp on the machine where a server was configured to

examine the appropriate interfaces file.

If you are relying on a directory service for making client/server
connections:

• Make sure that the libtcl.cfg file on the machine where Historical
Server was installed points to the appropriate directory service. Use
an editor to check and update libtcl.cfg files.

• Add Historical Server to the directory service, using
your system is running X-Windows) or

dscp_dce (a command line

dsedit_dce (if

utility). Y ou need to know the Historical Server name to complete this
step.

6 Configure Historical Server on client machines.

This task enables clients to connect to Historical Server. Historic al Server
clients are users who create recording sessions or playback sessions. Each
client machine must be configur ed appropriately.

See Open Client/Server Configuration Guide for UNIX for instructions on
using

dsedit and dscp.

If you are relying on interfaces files for making client/server connections:
a Update all of the interfaces files used by Historical Server clients. The

client interfaces files must contain entries for:

• Historical Server

• Any Adaptive Server that you want to monitor through Historical

Server

• Monitor Server associated with each Adaptive Server listed

14 Historical Server

CHAPTER 2 Configuring Historical Server

bUse

If you are relying on a directory service for making client/server
connections, make sure that the libtcl.cfg file on all Historical Server client
machines points to the appropriate directory service. Use a text editor to
check and update libtcl.cfg files.

dsedit (if your system is running X-Windows) or dscp (a

command line utility) to add entries to an interfaces file. To add these
entries, you must know the following information:

• Historical Server name.

• Monitor Server and Adaptive Server names that you want
Historical Server to connect to.

• Port numbers or network addresses assigned to these servers
when they were configured. To research this information, use

dsedit or dscp on the machine where a server was configured to

examine the appropriate interfaces file.

Initial configuration on Windows NT

This section describes ho w to configure Historical Server on Wi ndows NT
machines. It includes the following topics:

• Assumptions on Windows NT

• Results of installation on Windows NT

• Configuration procedures on Windows NT

Assumptions on Windows NT

These procedures assumes that:

• The Historical Server software was l oaded from the delivery media, us ing
the instructions provided with the delivery media.

• An Adaptive Server/Monitor Server pair is configured on your network.

User’s Guide 15

Initial configuration on Windows NT

Results of installation on Windows NT

On the Windows NT platform, the Sybase installation process performs a
nearly complete installation of Historical Server. The installation process:

• Copies Historical Server files to the Sybase installation directory.

• Adds parameter values for the Historical Server start-up command to the
NT Registry. It uses default values for these parameters. The entries are
under:

\\HKEY_LOCAL_MACHINE\SOFTWARE\SYBASE\SERVER\
servername\Parameters

• Adds the new Historical Server to the list of services in the NT Registry.
The entry is under:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\
Services

• Adds Historical Server connectivity information to the sql.ini file in the
Sybase installation direct ory on the Historical Server machine.

Configuration procedures on Windows NT

To complete Historical Server configuration:
1 Add connectivity information for Historical Server.

This task assigns a port or network address to Historical Server. It also
ensures that Historical Server can connect to one or more Adaptive
Server/Monitor Server pairs. A dd connection info rmation either to sql.ini
files or to a directory service. See Open Client/Server Configuration
Guide for Desktop Platforms for more information on any of the foll owing
procedures and on

If you are relying on sql.ini files for making client/server connections,
check the server listings in the sql.ini file. For Historical Server to run, this
file must contain entries for all of the following servers:

• Any Adaptive Server you want to monitor.

• A Monitor Server paired with each Adaptive Server.

16 Historical Server

ocscfg or dsedit.

CHAPTER 2 Configuring Historical Server

• Historical Server. Entr ies for Historical Server should exis t, since the
Sybase installation process adds them. However, since the Adaptive
Server/Monitor Server pairs usually are running on a different
machine from Historical Server , entries probably do not exist for them
on the Historical Server machine. If this is the case, you must add
entries for each Adaptive Server/Monitor Server pair to which
Historical Server intends to connect.

Use

dsedit to add entries to a sql.ini file. To add these entries, you must

know the following information:

• Monitor Server and Adaptive Server names to which you want
Historical Server to connect.

• Port numbers or network addresses assigned to these servers when
they were configured. To research this information, use

dsedit on the

machine where a server is configured to examine the appropriate
sql.ini or interfaces file.

Note The Adaptive Server name cannot be an alias name. It must be

the name that Monitor Server knows it by . For example, use the value
you used in the

-S parameter in the Monitor Server start-up command.

If you edit a sql.ini file using a text editor instead of

dsedit, make sure

a carriage return exists at the end of the last line in the file.

If you are relying on a directory service for making client/server
connections:

• Make sure that the libtcl.cfg file on the machine where Historical
Server is installed points to the appropriate directory service. Use

ocscfg to check and update libtcl.cfg files.

• Add Historical Server to the appropriate directory service, using

dsedit. You mu st know the Historical Server name to complete this

step. The default name created by the installation process is in the
format machineName_hs. For example, smith_hs.

2 Configure Historical Server client machines.

This task enables clients to connect to Historical Server. Historical Server
clients are users who create reco rding sessions or playback s essions. Each
client machine must be configured appropriately.

If you are relying on sql.ini files for making client/server connections, then
update all of the sql.ini files used by Historical Server clients. The client
sql.ini files must contain entries for:

User’s Guide 17

Initial configuration on Windows NT

• Historical Server.

• The Monitor Server associated with each Adaptive Server listed.

• Any Adaptive Server that you want Historical Server to collect data

Use
know the following information:

• Historical Server name.

• Monitor Server and Adaptive Server names to which you want

• Port numbers or network addresses assigned to these servers when

If you are relying on a directory service for making client/server
connections, then make sure that the libtcl.cfg file on all Historical Server
client machines points to the appropriate directory service.

Use

for.

dsedit to add entries to a sql.ini file. To add these entries, you must

Historical Server to connect.

they were configured. To research this information, use

dsedit on the

machine where a server was configured to examine the appropriate
sql.ini file.

ocscfg to check and update libtcl.cfg files.

3 Review start-up parameters in the NT Registry.
This task ensures that the default start-up parameter values that the installation

process inserted into the NT Registry are suitable for your site.
When you start Historical Server using the Control Panel Services window , the

server reads its start-up parameters from the NT Registry entry. If you start the
server from a command line or by means o f a batch file, Historical Server us es
the start-up parameters from both the registry entry and fro m the command. If
the same parameter appears in both places, th e value specified in the command
takes precedence over the value in the registry entry. If you do not specify any
start-up parameters in the command, by default all of the NT Registry entry
parameters are used.

Changing start-up parameters

T o change start-up parameters or to change the server name in the NT Registry:
1 Start the NT Re gistry Editor (regedt32.exe, usually in winnt\system32).
2 For NT 4.0, select the window named:

\\HKEY_LOCAL_MACHINE

18 Historical Server

CHAPTER 2 Configuring Historical Server

or, for NT 3.5.1:

\\HKEY_USER

and select the correct user entry.

3 Save or print the existing settings before proceeding . From the registry

menu, select the Save Subtree As command or the Print command.

4 In the tree view, highlight:

\SOFTWARE\SYBASE\Server\
srvrName\Parameters

where srvrName is the name of the server whose start-up parameters you
want to change.

On the right side of the window, review the list of existing start-up
parameters which appear in this format:

Argx, dataType, parameter

where:

• x is an integer in sequential order.

• dataType defines the type of data in the parameter value.

• parameter is a start-up option, preceded by a dash and followed by the
parameter value.

An example containing the Historical Server

-D, -U, and -P start-up

parameters follows:

Arg0:REG_SZ:-Dc:\sybase\data\hs_data
Arg1:REG_SZ:-Uhssuper
Arg2:REG_SZ:-Pxwdfr

5 To add a new start-up parameter:

• Select Edit | Add Value.

• In the resulting dialog box, in the Value Name box, enter

Argx where

x is the next integer not currently assigned.

• From the Data Type drop-down list, choose

REG_SZ.

• In the resulting String dialog box, enter the parameter and value.

6 To modify existing parameters:

• Double-click the parameter line you want to change.

• In the resulting String dialog box, change the entry.

User’s Guide 19

Setting Historical Server start-up parameters

7 From the Registry menu, choose Exit.

Setting Historical Server start-up parameters

This section describes the Historical Server start-up co mmand and parameters.
The section applies to Historical Server running on both UNIX and NT
platforms.

Function

Starts Historical Server.

Syntax

{histserver|histsrvr}

-DhomeDir

-d delim
[-IinterfacesFile] [-llogFile]
[-UuserName] [-Ppassword]
[-nmaxConnections] [-ShsName] [-v]

The executable name is histserver on UNIX platforms and histsrvr on W indows
NT.

Parameters

T able 2-1 describes the paramet ers to the Hist orical Ser ver start - up command.

20 Historical Server

CHAPTER 2 Configuring Historical Server

Table 2-1: Historical Server start-up parameters

Parameter Description

-DhomeDir Required. This parameter specifies the home directory for this

instance of Historical Server. The account that starts Historical
Server must have read, write, and search (execute) permissions on
the Historical Server home directory.

The default ho me d ire ctory is th e cu rre nt w ork ing d irect ory fo r the
account that starts Historical Server.

The control file used by this instance of Historical Server resides in
the home directory. The control file contains information about past
recording sessions and is updated during t he current run as new
recording sessions are establishe d.

The directory specified by this parameter is also the default
directory into which historical data files are written during a
recording session. The user who creates a recording session can
override this default locatio n without af fecting th e definition of the
control file.

Multiple instances of Historical Server can share the same home
directory. See “Configuring multiple instances of Historical
Server” on page 23 for more information.

Note If any UNIX shell-specific characters, such as the C she ll’s

tilde (~), appear at the start of the directory’s name, you must
separate the

-D parameter and the directory name by one or more

space characters. Otherwise, the shell cannot recognize that file
name expansion is required.

-d delim Specify a default file delimiter for the view files that Historical

Server generates. Delim can be:

• A character. For example:

./histserver -d ‘ ‘ or ./histserver -d/

• an escaped character. For example: ./histserver -d’/t’

• A four digit hexadecimal number representing the ascii code of

./histserver -d0x09

interfacesFile

-i

(Upper or lower
case “i” is valid
after the dash.)

the delimiter. For example:

Path name of the interfaces file to use. The file must contain
connection information, incl uding the correct names, for Histo rical
Server and all Adaptive Server and Monitor Server pairs to which
you want this Historical Server to co nnect. If you omit thi s
parameter, the name and location of the default interfaces file is:

UNIX: $SYBASE/interfaces
NT: SYBASE\sql.ini (where SYBASE is the value of the SYBASE

environment variable)

User’s Guide 21

Setting Historical Server start-up parameters

Parameter Description

-llogFile Path name of the log file in which information and error messages

about the Historical Server are logged. The data collected includes
start-up information, error messages, and possibly a record of
alarms that were triggered. The default path name is hs.log in the
current directory.

-UuserName Name of Historical Server superuser. When the sup eruser logs in to

Historical Server, that user is allowed to issue the
command to terminate Historical Server, and to view or delete any
data files created by Historical Server, regardless of the user who
initiated the recording sessions.

This user name is not required to correspond to either an Adaptive
Server login account or to an operating syst em registration. See
“The Historical Server superuser account” on page 11 for more
information.

If you do not specify this parameter, any user may stop Historical
Server, but no user has unrestricted access to the Historica l Server
data files.

-Ppassword Password of user specified with the -U parameter. A user who logs

in to Historical Server must supply this username and password to
exercise Historical Server superuser privileges. See “The Historical
Server superuser account” on page 11 for more information.

shutdown

Note If you specify the -U parameter on UNIX platforms, but do

not specify this parameter, Historical Server prompts for a
password during star t-up. However, Historical Server mu st be
started in foreground mode for you to receive the prompt. Make the
following changes to the start-up script to be prompted for a
password:

•Remove the

-P parameter and the ampersand (&) from the

start-up script file.

• Execute the script fi le.

• When prompted for a password, enter the password for the

username you specified in the -U parameter.

• Put the Historical Serv er process in the background.

-nmaxConnections Specifies the maximum number of concurrent Open Client

connections allowed to Historical Server. V alid values are 1 through

20. The default is 20.
Open Client connections to Historical Server are isql connections.

22 Historical Server

CHAPTER 2 Configuring Historical Server

Parameter Description

-ShsName Name of Historical Server as it appears in the interfaces file. If

omitted, the Historical Server name defaults to the value of the
DSLISTEN environment variable. If DSLISTEN is not set, the
name “histserver” is used.

-v Displays Historical Server version inf ormation and exits, ignoring

all other parameters.

Configuring multiple instances of Historical Server

There are times when running more than one instance of Historical Server is
appropriate. However, you must configure the multiple instances correctly to
either allow or restrict user access to the recording sessions of the multiple
instances.

This section discusses:

• When to create multiple instances of Historical Server

• Configuring an additional Historical Server on UNIX platforms

• Configuring an additional Historical Server on Windows NT

When to create multiple instances of Historical Server

If a single instance of Historical Server is managing many concurrent recordi ng
sessions that have short sample intervals, the amount o f time re quir ed to
process and record the samples may interfere with the timely acquisition of
new samples. If the timestamps in the recorded data files indicate that samples
are not being collected at a reasonable approximation o f the requ ested sample
interval, you may choose to spread the load among two or more instances of
Historical Server.

When multiple instances of Historical Server use the same home directory:

• Each instance must be started by the same operating system account.

• All instances that use the same home directory use the same control file.

• The sessions recorded by one instance are visible to the other instances.

• File-locking mechanisms ensure that the control file is not corrupted by
concurrent accesses.

User’s Guide 23

Configuring multiple instances of Historical Server

When multiple instances of Historical Server use different home directori es:

• The Historical Server instances can be started by different user accounts.

• The Historical Server instances use different control files.

• The recording sessions of one server are not visible to the others. For
example, the

hs_list command, issued through isql, cannot access the

recording sessions defined by another Historical Server using a different
home direct ory.

When deciding whether multiple instances should use the same or different
home directories, consider these factors:

• Visibility of data – if users of the multiple instances need access to each
other ’s recording session defi nitions, use t he same home directory. If
sharing is undesirable, use different h ome directories. All input sessions to
a playback session must be in the same home directory.

• Visibility of status information – the

hs_status command cannot

distinguish between multiple instances of Historical Server using the same
home directory. If this distinction is important to Historical Server
administration, use different home directories.

• Contention on the control file – if a large control file receives heavy access
from multiple users, different home directories may give better user
response time. Actions such as creating recording sessions and listing
information about recording sessions use the control file; recording
sessions themselves, when they are runnin g, do not block other users from
the control file.

Configuring an additional Historical Server on UNIX platforms

To configure an additional Historical Server on UNIX platforms:
1 Copy the start-up script that you creat ed for the original Historical Server.

Name the new file to reflect the name of the new Historical Server you
want to start.

2 Edit the start-up file, changing the parameters to the start-up command as

appropriate for the new instance of Historical Server. See “Setting
Historical Server start-up parameters” on page 20. Pay particular attention
to the

-D parameter, which specifies the Historical Server hom e directory.

Y ou must decide whether you want multip le instances of Histor ical Server
to share the same home directory or maintain separate ones.

24 Historical Server

CHAPTER 2 Configuring Historical Server

3 Set up connectivity information for Historical Server, adding entries for

the new Historical Server . Use a port number for the new Historical Server
that is unique on its machine.

4 Edit the connectivity information on the client machines, adding entries

for the new Historical Server.

Configuring an additional Historical Server on Windows NT

The Server Configuration utility cannot configure a new Historical Server. To
configure an additional Historical Server after initial installation:

1 Adding start-up parameters to the NT Registry
2 Updating the NT Registry services list
3 Adding connectivity information for Historical Server
4 Configuring Historical Server client ma chines
5 Creating a .bat file (optiona l)

Adding start-up parameters to the NT Registry

To add Historical Server start-up parameters to the NT Registry:
1 Start the NT Registry Editor (regedt32.exe, usually in winnt\system32).
2 For NT 4.0, select the window named:

\\HKEY_LOCAL_MACHINE

or, for NT 3.5.1:

\\HKEY_USER

and select the appropriate user.

3 Save or print the existing settings before proceeding . From the Registry

menu, select the Save Subtree As command or the Print command.

4 In the tree view, highlight:

\SOFTWARE\SYBASE\Server

5 From the Edit menu, choose Add Key.
6 In the resulting dialog box, in the Key Name box, enter the name of the

Historical Server you are adding.

User’s Guide 25

Configuring multiple instances of Historical Server

Leave the Class box blank.

7 In the tree view, highlight:

\SOFTWARE\SYBASE\Server\hsName

where hsName is the new Historical Server name.

8 Select Edit | Add Value.
9 In the resulting dialog box, in the Value Name box, enter:

ServerType

From the Data Type drop-down list, choose:

REG_SZ

In the resul ting String dialog box, ent er:

HISServer

10 Make sure the entry for the new Historical Server name remains

highlighted.

11 Select Edit | Add Key.
12 In the Key Name box, enter:

Parameters

Leave the Class box blank.

13 In the tree view, highlight:

\SOFTWARE\SYBASE\Server\hsName\Parameters

where hsName is the new Historical Server name.

14 Select Edit | Add Value.
15 In the Value Name box, enter:

Arg0

From the Data Type drop-down list, choose:

REG_SZ

In the resul ting String dialog box, ent er:

-ShsName

where hsName is the Historical Server name.

16 Repeat steps 13 through 15 un til y ou hav e entered all of the start-up

parameters for Historical Server.

26 Historical Server

CHAPTER 2 Configuring Historical Server

At a minimum, enter the following required parameters. The order does
not matter; for example,

Value
name Datatype String

Arg0 REG_SZ

Arg1 REG_SZ -DdataDirectoryName

Arg2 REG_SZ -IinstallationRootDir\ini\sql.ini

Arg3 REG_SZ -linstallationRootDir\install\logName

-D does not ha ve to be Arg1.

-ShsName

where hsName is the Historical Server name you used in step

5.
Example:

-SHS_SERVER1

where dataDirectoryName is the full path name of an
existing directory where you want to store Historical Server

data. All users who will create Historical Server recording
sessions must have write access to this directory.

Example:

-Dc:\SYBASE\data\hs.data

Example:

-Ic:\SYBASE\ini\sql.ini

where logName is the file name where you want to store
Historical Server error messages. The server creates the file
on start-up if it does not exist.

Example:

-lc:\SYBASE\install\hs.log

Updating the NT Registry services list

To add Historical Server to the list of services in the NT Registry:
1 Start the NT Registry Editor (regedt32.exe, usually in winnt\system32).
2 For NT 4.0, select the window named:

\\HKEY_LOCAL_MACHINE

or, for NT 3.5.1:

\\HKEY_CURRENT_USER

and select the correct user.

3 Save or print the existing settings before proceeding . From the registry

menu, select the Save Subtree As command or the Print command.

User’s Guide 27

Configuring multiple instances of Historical Server

4 In the tree view, highlight:

\SYSTEM\CurrentControlSet\Services

5 Select Edit | Add Key.
6 In the Key Name box, enter:

SYBHIS_hsName

where hsName is the name of the Historical Server you just configured.
Leave the Class box blank.

7 In the tree view, highlight:

\SYSTEM\CurrentControlSet\Services\SYBHIS_hsName

8 Select Edit | Add Value as many times as necessary to enter all of the

following values, dat atypes, and strings to the

Value name Datatype String

DisplayName REG_SZ Sybase HISServer _ hsName
ErrorControl REG_DWORD 01 (Select hex radio button)
Group REG_SZ (leave blank)
ImagePath REG_

EXPAND_SZ
ObjectName REG_SZ LocalSystem
Start REG_DWORD 03 (Select hex radio button)
Type REG_DWORD 010 (Select hex radio button)

SYBHIS_hsName key entry.

rootInstlDir\bin\histsrvr.exe -ShsName

-C

9 Make sure the

SYBHIS_hsName key entry remains highlighted.

10 Select Edit | Add Key.
11 In the Key Name box, enter:

Security

Leave the Class box blank.

12 In the tree view, highlight the following Security key entry:

\SOFTWARE\SYBASE\Server\hsName\Security

13 Select Edit | Add Value.
14 Enter the following values for value name, datatype, and binary editor:

Value name Datatype Binary editor

Security REG_BINARY 01001480

28 Historical Server

CHAPTER 2 Configuring Historical Server

15 Select Registry | Exit.
16 Restart the machine.

Adding connectivity information for Historical Server

This task assigns a port or network addr ess to Historical Server. It also ensures
that Historical Server can connect to one or more Adaptive Server/Monitor
Server pairs.

This task differs depending on whether you rely on sql.ini files or a directory
service for making client/server connections:

• If you are relying on sql.ini files for making client/server connections,
check the server listings in the sql.ini file for the Historical Se rver
machine. For Historical Server to run, this file must contain entries for all
of the following servers:

• Any Adaptive Server you want to monitor

• Monitor Server paired with each Adaptive Server

• Historical Server
Use

dsedit to add entries to a sql.ini file. To add these entries, you must

know the following information:

• Monitor Server and Adaptive Server names to which you want

Historical Server to connect.

• Port numbers or network addresses assigned to these servers when

they were configured.

T o research this information, us e

dsedit on the machine where a server was

configured to examine the appropriate sql.ini file.

Note The Adaptive Server name cannot be an alias name. It must be the

name that Monitor Server knows it by. For example, use the value you
used in the -S parameter in the Monitor Server start-up command.

• If you are relying on a directory service for making client/server
connections:

• Make sure that the libtcl.cfg file on the machine where Historical

Server was installed points to the appropriate directory service. Use

ocscfg to check and update libtcl.cfg files.

User’s Guide 29

Configuring multiple instances of Historical Server

• Add Historical Server to the appropriate directory service, using

dsedit. You must know the Historical Server name to complete this

step. The default name created by the installation process is in the
format machineName_hs. For example, smith_hs.

See Open Client/Server Configuration Guide for Desktop Platforms for
instructions on using

ocscfg and dsedit.

Configuring Historical Server client machines

This task enables clients to connect to Historical Server. Historical Server
clients are users who create recording sessions or playback sessions. Each
client machine must be configured appropriately.

The configuration task dif fers dependin g on whether you are usi ng sql.ini files
or a directory service for making client/server connections.

• If you are using sql.ini files for making client/server connections, then
update all of the sql.ini files used by Historical Server clients. The client
sql.ini files must contain entries for:

• Historical Server

• The Monitor Server associated with each Adaptive Server listed

• Any Adaptive Server that you want Historical Server to collect data

for

Use

dsedit to add entries to a sql.ini file. To add these entries, you must

know the following information:

• Historical Server name

• Monitor Server and Adaptive Server names to which you want

Historical Server to connect

• Port numbers or network addresses assigned to these servers when

they were configured

To research this information, use

dsedit on the machine where a server is

configured to examine the appropriate sql.ini file.

• If you are relying on a directory service for making client/server
connections, make sure that the libtcl.cfg file on all Historical Server client
machines points to the appropriate directory service.

Use

ocscfg to check and update libtcl.cfg files.

30 Historical Server

Creating a .bat file (optional)

This task allows you to start Historical Server by executing a batch file, rather
than by using the services icons.

To prepare for Historical Server start-up from a batch file:
1 Start any text editor and open a new text file.

CHAPTER 2 Configuring Historical Server

2 Enter the Historical Server start-up command,

histsrvr, and all desired

parameters. Use the full path name of the start-up command histsrvr.exe.
See “Inferring start-up parameters from the NT Registry” on page 37 for
precedence rules used by Historical Server to obtain start-up parameters.
See “Setting Historical Server start-up parameters” on page 20 for
explanations of start-up parameters.

An example line in the .bat file follows. The example has carriage returns
inserted in the command. Do not put carriage returns in your .bat file. The
entire file should be one line.

c:\sybase\bin\histsrvr.exe -Shs_server1

-Dc:\sybase\data\hs_data

-Ic:\sybase\ini\sql.ini

-lc:\sybase\data\hs.log

3 Save the file with a .bat extension. S ybase recommends that you u se RUN_

hsName.bat. For example:

RUN_hs_server1.bat

User’s Guide 31

Configuring multiple instances of Historical Server

32 Historical Server

CHAPTER 3

Starting and Stopping Historical
Server

Topics Page

Starting and stopping Historical Server on UNIX platforms 33
Starting and stopping Historical Server on Windows NT 36

Starting and stopping Historical Server on UNIX platforms

This section describes how to start and stop Historical Server running on
UNIX platforms.

Starting Historical Server on UNIX

On UNIX, you can start a configured Historical Server in two ways:

• Execute the
use this method, you must type all appropriate parameters each time.

• Execute a script file that contains the
appropriate parameters. If you followed the configuration
instructions in Chapter 2, “Configuring Historical Server,” you
would start Historical Server using:

install_dir/install/RUN_histServerName

where install_dir is the Sybase root directory and histServerName is
the name of the Historical Server you want to start.

Regardless of which method you use:

• V erify that the Adaptive Server to be monitored and its corresponding
Monitor Server are running.

User’s Guide 33

histserver command from a UNIX shell prom pt. If you

histserver command and all

Starting and stopping Historical Server on UNIX platforms

• Use the same account each time you start Historical Server , if you want the
new instance to have access to previously recorded sessions. See “The
operating system start-up account” on page 10 for more information.

• Set the $SYBASE environment variable to the root directory of the Sybase
installation.

The $SYBASE environment variable must contain the name of a directory
that has the appropriate locales and charsets subdirectories for Historical
Server. Th ese subdirectories were created and populated automatically by
the installation procedure.

The $SYBASE environment variable also identifies the default location of
the interfaces file. Use parameters to the
the default location.

Historical Server displays the following message to indicate that start-up was
successful:

Initialization is over. Ready to accept connections.

Historical Server writ es messages to its log file during st art-up. You can ignore
these messages if start-up was successful. If start-up is not successful, examine
the log file to research the problem.

histserver command to override

The default path name for the Historical Server log file is hs.log in the current
directory at the time of start-up. You can override this default path name with
the

-l parameter (the letter l) to the histserver command.

Stopping Historical Server on UNIX

This section describes:

• Who can shut down Historical Server

• Determining current activity on Historical Server

• Deferred versus immediate shutdown

• Detailed shutdown procedures

Who can shut down Historical Server

If the start-up command specifies a superuser account, then only the superuser
account can stop Historical Server. If a superuser is not specified in the start­up command, any user can stop Historical Server.

34 Historical Server

CHAPTER 3 Starting and Stopping Historical Server

The superuser is the one whose account was specified in the
parameters to the Historical Server start-up command.

Determining current activity on Historical Server

Before shutting down Historical Server, check current activity on Historical
Server to determine if you want to issue a deferred shutdown or an immediate
shutdown. A deferred shutdown lets all current activity complete before
terminating Historical Server.

Historical Server activity might include fully defined and initiated recording
sessions, uninitiated recording sessions with definitions still in progress,
playback sessions in progress, and playback sessions being defined. Client
connections can be from multiple machines and they might be monitoring
various Adaptive Servers.

T o determine current activity in Historical Server, connect to Historical Server
with the

isql utility and issue the hs_status activity command.

Deferred versus immediate shutdown

To close Historical Server, connect to it using the isql utility and issue one of
the following commands:

•

hs_shutdown – defers shutdown until all active recording sessions

complete and any other active conn ections are closed. No new connections
are accepted during this time.

-U and -P

A deferred shutdown may block for an ex tended period of time, and typi ng
Ctrl+C while the

•

hs_shutdown no_wait – shuts down Historical Server immediatel y and

hs_shutdown command is blocked has no effect.

terminates any connections and active recording sessions.

In either case, the active recording sessions are shut down in a controlled
manner. The Historical Server control file and the historical data files are
available to Historical Server when it is restarted.

Detailed shut down procedures

Shut down servers in the following order:

• Historical Server

• Monitor Server

User’s Guide 35

Starting and stopping Historical Server on Windows NT

• Adaptive Server

To stop Historical Server on a UNIX platform:
1 Connect to Historical Server. If you are using

isql [ -Uhs_superuser_name -Phs_superuser_password ]

-Shistorical_server

isql, the command is:

where:

• superuser_name is the name that was used with the

the Historical Server start-up command. If

-U was not used in the start-

up command, any user can stop Historical Server, and the
parameter in this

isql command is optional.

• superuser_password is the password that was used with the

parameter to the Historical Server start-up command. If

-U paramete r to

-U

-P

-U was not

used in the start-up command, any user can stop Historical Server , and
this parameter is optional.

• historical_server is the name of the Historical Server you want to

stop.

2 To determine current activity on Historical Server, issue the following

command when the

1> hs_status activity
2> go

isql prompt appears:

3 To shut down Historical Server, issue one of the following commands:

1> hs_shutdown
2> go

or:

1> hs_shutdown no_wait
2> go

Starting and stopping Historical Server on Windows
NT

This section describes how to start and stop Historical Server running on
Windows NT platforms. To pics are:

• Starting Historical Server on Windows NT

36 Historical Server

CHAPTER 3 Starting and Stopping Historical Server

• Inferring start-up parameters from the NT Registry

• Verifying that Historical Server is running

• Stopping Historical Server on Windows NT

Starting Historical Server on Windows NT

You can start Historical Server by using:

• The Windows NT Control Panel Services window.

• A batch (.bat) file containing the start-up command and parameters. The
file name is run_hsName.bat, where hsName is the name of the Historical
Server instance. Sybase recommends that you invoke the batch file fr om a
command line shell rather than by double-clicking on it in File Manager.
The command line shell captures start-up error messages, if any occur,
whereas the File Manager does not.

• The start-up command typed directly from a command line shell. The
name of the Historical Server executable file for Windows NT is

histsrvr.exe.

When you use a .bat file or a command line command to start Historical Server ,
the server process is linked to your current login account. When you log off,
the server shuts down.

For production systems, Sybase recommends that you start Historical Server
using the Windows NT Control Panel Services Manager. When you start a
server as a service, it persists across logins.

Inferring start-up parameters from the NT Registry

Start-up parameters for Historical Server are in the following NT Registry
entry:

\SOFTWARE\SYBASE\SERVER\servername\Parameters

User’s Guide 37

Starting and stopping Historical Server on Windows NT

When you start Historical Server using the Control Panel, the server reads its
start-up parameters from this NT Registry entry. If you start the server from the
command line or by means of a batch file, the start-up parameters are taken
from both the registry entry and from the command. If the same parameter
appears in both places, the value specified in the command takes precedence
over the value in the registry entry. If you do not specify any start-up
parameters in the command, by default all of the NT Registry entry parameters
are used.

See “Adding start-up parameters to the NT Registry” on page 25 for
information on editing the NT Registry entries.

Verifying that Historical Server is running

On Windows NT, check the status of Historical Server in the Windows NT
Control Panel Services window.

Stopping Historical Server on Windows NT

This section describes:

• Who can shut down Historical Server on Windows NT

• Determining current activity on Windows NT

• Deferred versus immediate shutdown on Windows NT

• Detailed shutdown procedures on Windows NT

• Shutdown methods to avoid on Windows NT

Who can shut down Historical Server on Windows NT

If a superuser account is specified at start-up, only the superuser account can
stop Historical Server. If a superus er is not specified in the start-up command,
any user can stop Historical Server. Administrators with privileges to use the
Control Panel Services window can also shut down Historical Server.

The superuser account is specified in the
Server start-up command.

38 Historical Server

-U and -P parameters to the Historical

CHAPTER 3 Starting and Stopping Historical Server

Determining current activity on Windows NT

Before shutting down Historical Server, check current activity on Historical
Server to determine if you want to issue a deferred shutdown or an immediate
shutdown. A deferred shutdown lets all current activity complete before
terminating Historical Server.

Historical Server activity might include fully defined and initiated recording
sessions, uninitiated recording sessions with definitions still in progress,
playback sessions in progress, and playback sessions being defined. Client
connections can be from multiple machines and they might be monitoring
various Adaptive Servers.

T o determine current activity in Historical Server, connect to Historical Server
with the

isql utility and issue the hs_status activity command.

Deferred versus immediate shutdown on Windows NT

To close Historical Server, connect to it using the isql utility and issue one of
the following commands:

•

hs_shutdown – defers shutdown until all active recording sessions

complete and any other active conn ections are closed. No new connections
are accepted during this time.

A deferred shutdown may block for an ex tended period of time, and typi ng
Ctrl+C while the

hs_shutdown command is blocked inside the isql has no

effect.

•

hs_shutdown no_wait – shuts down Historical Server immediatel y and

terminates any connections and active recording sessions.

In either case, the active recording sessions are shut down in a controlled
manner. The Historical Server control file and the historical data files are
available to Historical Server when it is restarted.

Detailed shut down procedures on Windows NT

Shut down servers in the following order:

• Historical Server

• Monitor Server

• Adaptive Server

To stop Historical Server on Windows NT, use any of these methods:

User’s Guide 39

Starting and stopping Historical Server on Windows NT

• Click the Stop button on the W indows NT Control Pan el Services wi ndow .

•Issue the

hs_shutdown command from isql.

• If start-up was launched from the command line or by means of a batch
file, then Historical Server is associated with the login that started it. In
these cases, Historical Server shuts down if you close the window in which
it was started or if you log off of the system.

If the controlled shutdown of Historical Server takes longer than a
predetermined time interval (five seconds for closing the window or
twenty seconds for logoff), the system displays a pop-up dialog box at
regular intervals, asking you whether or not to terminate the process.

Warning! Unless you respond with Wait each time the dialog box is

presented, Historical Server shuts down in an uncontro lled way, risking
data loss and file corruption.

To stop Historical Server using
1 Connect to Historical Server using

isql -Uhs_supersuer_name -Phs_superuser_password

-Shistorical_server

isql:

isql:

where:

• superuser_name is the name that was used with the

the Historical Server start-up command. If

-U was not used in the start-

-U paramete r to

up command, any user can stop Historical Server, and this parameter
is optional.

• superuser_password is the password that was used with the

parameter to the Historical Server start-up command. If

-P

-U was not

used in the start-up command, any user can stop Historical Server , and
this parameter is optional.

• historical_server is the name of the Historical Server you want to

stop.

2 To determine current activity on Historical Server, issue the following

command when the

1> hs_status activity
2> go

isql prompt appears:

3 When the isql prompt appears, issue one of the following commands:

1> hs_shutdown

40 Historical Server

CHAPTER 3 Starting and Stopping Historical Server

2> go

or:

1> hs_shutdown no_wait
2> go

Shutdown methods to avoid on Wi ndows NT

In some cases, shutting down your system without first shutting down
Historical Server can cause uncontrolled shutdown. Unless Historical Server is
experiencing a very high level of recording activity, its controlled shutdown
should take less than 20 seconds. If 20 seconds or more are used for the
controlled shutdown, however, the system may intervene and terminate
Historical Server in an uncontrolled way.

Warning! To be safe, Sybase recommends that you manually stop Historical

Server before you shut down the system.
Using the Kill Process button causes an uncontrolled shutdown.

If Microsoft Visual C++ Process Viewer tool is installed on your system,
Sybase recommends that you do not use the Kill Process button in the Process
Viewer window.

User’s Guide 41

Starting and stopping Historical Server on Windows NT

42 Historical Server

CHAPTER 4

Command Reference

This chapter describes the Historical Server command interface.

Topics Page

Command summary 43
Command syntax 44
Command status and errors 45
Script files as input to Historical Server 46
Connecting to Historical Server 46
Historical Server commands 50

Command summary

Table 4-1 summarizes the Historical Server commands.

Table 4-1: Historical Server commands

Activity Commands

Creating recording
sessions

Viewing recording
session definitions

Use these commands to create a recording sessi on:

hs_create_recording_session – defines the

•
characteristics of a recording session.

hs_create_view – defines a view , whic h is a co llec tio n

•
of data to record.

•

hs_create_filter – specifies filtering criteria on a data

item.

hs_create_alarm – specifies a threshold value for a data

•
item that triggers an alarm action.

hs_initiate_recording – ends recording session

•
definition and enables recording to begin at its
predefined start time.

• hs_terminate_recording – stops a recording session.

•

hs_list – lists all of the views defined for a recording

session and their data items.

User’s Guide 43

Command syntax

Activity Commands

Creating a
playback session

Administering
Historical Server

Use these commands to create a playback session:

hs_create_playback_session – defines the

•
characteristics of a playback session

hs_create_playback_view – specifies on e or more

•
views from the input recording sessions to include in
the playback session.

• hs_initiate_playback – ends playback session
definition. Also starts playback to a file.

•

hs_playback_sample – plays back a sampl e to a client.

• hs_terminate_playback – stops a playback session.

Use these commands to manage Historical Server:

•

hs_delete_data – deletes the files containing the

recorded data for specified recording sessions.

hs_status – displays the current status of Historical

•
Server.

hs_shutdown – stops Historical Server.

•

Command syntax

The syntax for Historical Server commands is:

hs_XXX arg1, arg2, arg3, ..., argn

where XXX is the command name. For example, a typical command is

hs_create_recording_session.

Parameters must be separated by commas. You can omit parameters that
are optional or that have default values; however, you must use the value
NULL for those parameters as a placehol der if other parameter values
follow them. For example, the following command uses the default value
for most parameters:

hs_create_playback_session null, null, raw, null,
null, client, null, null, null, null, 7

Command names, command keywords, the word null, data items, and
statistic types are all case-insensitive. File names, view names, and other
user-supplied names are case-sensitive.

44 Historical Server

If a parameter value contains embedded spaces (such as those in data
items, statistic types, and date-time specifications), you must surround the
value with quotes. Matched pairs of single- quo te or double-qu ot es are
valid delimiters.

If the parameter value contains an embedded quote that is the same as the
character used to delimit the entire value, supply a pair of the quotes within
the parameter value. Historical Server compresses the pair of quotes to a
single character.

The word null within quotes is not a keyword.
You can enter Historical Server comma nds o n mu ltiple lines.

Command status and errors

All Historical Server commands return a status value of either zer o or one.

• Zero indicates a successful execution.

• One indicates an error condition. If a status of one ( “1”) is returned,
an error message and its appropriate error code, severity level, and
state are returned to the client.

CHAPTER 4 Command Reference

Historical Server is an Open Server application that us es Client-Library™
to communicate with one or more pairs of Adaptive Server and Monitor
Server. Any of these components may detect and report error conditions.

Historical Server also detects and repor ts error conditions, which it logs or
reports or both to clients. Historical Server error codes are all five-digit
numbers from 30000 through 30999. Open Server error codes are in the
range between 16000 and 20000. For error codes in either of these ranges,
the Historical Server assigns one of the following severity levels:

Table 4-2: Severity levels in command errors

Severity Description

1 Informational message
2 Warning message
3 Fatal server error
4 Fatal process error
5 Operating system error

User’s Guide 45

Script files as input to Historical Server

Errors detected by Client-Library, A daptive Server, and Monitor Server
use their own error numbering and severity-level schemes.

Script files as input to Historical Server

A convenient way to provide input to Historical Server is to enter the
commands in a text file and use that file as input. The Historical Server
input file is not an
conventions. For example, Historical Server does not have a comments
feature.

Appendix D, “Examples of Recording Session Views” provides examples
of views that you might use as a start for your input files. These views also
appear in the views file that was installed in the sample/histserver
subdirectory in the installation directory. However, that the file includes
explanatory text that you must remove before using the file as input to
Historical Server.

isql file, and does not necessarily conform to isql

Connecting to Historical Server

This section contains the following topics:

• Assumptions before connection

• How to connect

• Required permissions for Historical Server activities

• Mutually exclusive sessions

Assumptions before connection

Before you can connect to Historical Server:

• The Adaptive Server whose performance data you want to collect
must be running.

46 Historical Server

How to connect

CHAPTER 4 Command Reference

• A Monitor Server that is monitoring the Adaptive Server must be

running. See Sybase Adaptive Se rver Enterprise Monitor Server
User’s Guide for instructions on verifying whether an Adaptive
Server/Monitor Server pair is running.

• The Historical Server must be running. See Chap te r 3, “Starting and

Stopping Historical Server” for instructions on verifying whether a
Historical Server is running.

• Connection information must be configured correctly on both the

Historical Server machine and its client machines. See Chapter 2,
“Configuring Historical Server” for more information.

Connect to Historical Server using a utility that offers an interactive
interface to Sybase servers, such as SQL Advantage or

isql. Follow the

standard connection procedures for the utility. For example, in SQL
Advantage, choose the Connect menu item. In
Historical Server name as the value of the

isql, start isql using the

-S parameter.

Required permissions for Historical Server activities

Connect to Historical Server using a user login and password that has
permissions for the activities you intend to perform, as described in Table
4-3. Depending on the permi ssions required , you might h ave to disconnect
and reconnect with different login accounts to perform various activities.

Table 4-3: Permissions required for Historical Server activities

Permissions required to perform

Activity

Superuser a ctivities:

• Stop Historical Server.

• Delete Historical Server files,
including record ing ses sion data
files.

• Access files from private
recording sessions.

User’s Guide 47

the activity

Superuser permissions. To obtain
superuser permis sions, connect to
Historical Server using the superuser
account defined at start-up.

The superuser account does not have to
be a valid account in any Adaptive
Server.

Connecting to Historical Server

Permissions required to perform

Activity

Create recording sessions. V alid login and password i n the Adaptive

Create playback sessions using
public recording session files (from
recording sess ions whose
protection_level parameter is

).

public

hs_list comma nd on public

Use
recording sess ion files.

Create playback sessions using
private recording session files
(from recording sessions whose
protection_level parameter is
private).

hs_list command on private

Use the
recording sess ion files.

the activity

Server being monitored.
Execute permission on the

mon_rpc_connect stored procedure in the

Adaptiv e Server being monitored. This
permission is required to connect to
Monitor Server.

V alid login and password in the Adapti ve
Server being monitored.

The same login that created t he private
sessions, or superuser. In the latter case,
the superuser account must be a val id
login in the Adap tive Server being
monitored.

A single Historical Server can connect to and collect data from multiple
Adaptive Server/Monitor Server pairs. For example, from the same
Historical Server connection, you could cr eate two recording sessions, one
gathering performance data for an Adaptive Server named server1 using a
Monitor Server named server1_MO N, and the ot her gatheri ng data for an
Adaptive Server named server2 using a Monitor Server named
server2_MON. If you do not have a login account that is valid in both
Adaptive Server instances, you would need to create these recording
sessions in different connections to Historical Server, using different login
accounts. The data files from the two recording sessions, however, could
reside in the same directory.

The

hs_create_recording_session command specifies the Monitor Server

you want to connect to, which indirectly implies the Adaptive Server you
want performance information abou t.

48 Historical Server

Mutually exclusive sessions

A Historical Server connection can be in volved with only one sess ion at a
time. You can either be defining a recording session, or defining and
executing a playback session, but you cannot mix together com mands for
multiple sessions. That is, if you start a recording session definition with
the

hs_create_recording_session command, you must finish the sequence

of commands to define that session (or cancel th e session) before yo u can
start to define a playback session or a new recording session.

Defining a recording session is not the same thing as a recording session
in progress. The user who defines a recording session is connected to and
actively communicating with Historical Server during definition of a
recording session. The user does not actively communi cate with Historical
Server during the actual recording. Any user connections are irrelevant
during recording. For example, a user might connect to Historical Server
at 3 p.m., define a recording session that starts at 10 p.m., and then
disconnect from Historical Server. At 10 p.m., it is irrelevant whether t he
user is connected to Historical Server; the recording s ession takes p lace if
Historical Server is running.

A playback session, however, requires the user connection during both
playback definition and playback execution. T o cancel playback execution
and allow the user connection to pe rfo rm some other comm unicati on, the
user must issue the

CHAPTER 4 Command Reference

hs_terminate_playback command.

Starting and ending a recording session definition

The hs_create_recording_session command starts a recording session
definition. After issuing this command, you further define th e recordin g
session by issuing other commands to create views, filters , and alarms for
the recording session.

To end the recording session definition, use either:

•

hs_initiate_recording – signals that the definitio n is complete and

enables the recording session to start at the session’s specified start
time.

•

hs_terminate_recording – cancels a recording session definition that is

in progress.

User’s Guide 49

Historical Server commands

Starting and ending a playback session

The hs_create_playback_session command starts a playback definition.
After issuing this command, you use other commands to define the
playback session and perform the playback.

After issuing a successful
must successfully execute a
playback session. This command cancels the definition and ends playback.

Historical Server commands

The following pages describe the Historical Server commands:

•

hs_create_alarm

• hs_create_filter

• hs_create_playback_session

• hs_create_playback_view

• hs_create_recording_session

• hs_create_view

• hs_delete_data

• hs_initiate_playback

• hs_initiate_recording

• hs_list

hs_create_playback_session command, you

hs_terminate_playback command to end the

• hs_playback_sample

• hs_shutdown

• hs_status

• hs_terminate_playback

• hs_terminate_recording

50 Historical Server

CHAPTER 4 Command Reference

hs_create_alarm

Description Creates an alarm. An alarm is triggered when a data item value reaches a

specified threshold value.

Syntax hs_create_alarm view_name, data_item_name, data_item_stat,

alarm_action, alarm_action_data, alarm_value

Parameters

view_name

name of the view that contains the data item to which the alarm applies.

data_item_name

data item to which the alarm applies. If the data item contains embedded
spaces, surround it with quotation marks.

data_item_stat

statistic type for data_item_name. The data_item_name and
data_item_stat combination must exist in the view definition. Surround

the statistic type with quotation marks.

alarm_action

action to take when an alarm condition occurs. Values are:

•

log – logs messages when the alarm condition occurs. You specify

the log file name in the alarm_action_data parameter.

•

execute – executes a program or script file when the alarm

condition occurs. You specify the file to execute in the

alarm_action_data parameter.

alarm_action_data

specifies information required to carry out the alarm_action:

If alarm_action is Then alarm_action_data is

log Name of the file where Historical Server should log

the alarm messages. The default is the Historical
Server log file. If you specify a file that does not
exist, Historical Server creates it. If yo u sp ecify a n
existing file, the user who started Historical Server
must have write permission for the file.

User’s Guide 51

hs_create_alarm

If alarm_action is Then alarm_action_dat a is

execute Name of the file to execute, optio nally fol lowed by

a list of parameters separated by spaces. The file
must exist and the user who starte d Historical
Server must have execute permission for it.

Warning! When an alarm condition occurs an d

alarm_action is execute, the specified file is

executed by the account that st arted Historical
Server, not by the account that created the alarm.
This means that the access privileges of the person
who starts Historical Server are available to the
users who define alarms. A user who normally
cannot execute a file may be able to execute it
through an Historical Server al arm.

alarm_value

triggering value for the alarm.

Examples 1 This example creates an alarm for a view named Page I/O. The view

contains the Page I/O data item with a V alue for Session statistic type.
The data is logged to the page_io_alarm_file file when a trigger value
of 50 or greater is achieved.

hs_create_alarm PageIO,"Page I/O",
"Value for Session",log,page_io_alarm_file,50

2 This example creates an alarm for a view named Page I/O. This alarm

causes the /user/script1 script to be executed and passed the value 100
as its first parameter when a trigger value of 100 or greater is achieved
on the Page I/O data item.

hs_create_alarm PageIO,"Page I/O",
"Value for Session",execute,
"/user/script1 100",100

Usage

•If alarm_action is execute, when the alarm condition occurs, the
script or program executes in the backg round. The commands within
the script or program are executed in the foregro und and disp layed if
applicable.

For example, if you want the clock to display in an alarm condition,
you should put clock.exe into a script file and specify the script file
name when creating the alarm, rather than specifying clock.exe when
creating the alarm.

52 Historical Server

CHAPTER 4 Command Reference

• When an alarm condition occurs and alarm_action is

log, Historical

Server writes three lines to the log file. The first line contains:

• Timestamp of the sample that triggered the alarm

• Name of the data item on which the alarm was set

• Statistic type of that data item

• Value of the data item that triggered the alarm

• Threshold value of the alarm

• The second line in the log file contains:

• Session ID

•View name

•Alarm ID

• The third line in the log file contains:

• Name of the Adaptive Server being monitored

• Names and values of all key data items in the view for the ro w of
sample data that triggered the alarm

• When an alarm condition occurs and alarm_action is

execute,

Historical Server runs the script or program specified in the
alarm_action_data parameter . Historical Server invokes the program
or file using the arguments specif ied in alarm_action_data, followed
by additional positional arguments that can be accessed within the
program. The positional arguments appended to the call by Historical
Server represent the following information:

• Session ID

•Alarm ID

• Sample timestamp

• Data item on which the alarm was set

• Statistic type of that data item

• Value of the data item that triggered the alarm

• Threshold value of the alarm

• Name of the Adaptive Server being monitored

• Number of key data items in the view

User’s Guide 53

hs_create_filter

• For each key data item:

• Name of the data item

• Value of that data item for the row of sample data that

triggered the alarm

• When an alarm condition occurs and alarm_action is

execute, the

specified file is executed by the acco unt that started Historical Server ,
not by the account that created the alarm. This means that the access
privileges of the person who starts Historical Server are available to
users who define alarms.

Warning! It is possible that a user who normally cannot execute a file

can execute that file through an Historical Server alarm.

hs_create_filter

Description Specifies filtering criteria on a data item. A filter limits the scope of

collected data for a single data item in a view. Filters are optional.

Syntax hs_create_filter view_name, data_item_name, data_item_stat,

Parameters

filter_type, value_spec

view_name

name of the view that contains the data item to filter.

data_item_name

data item to which the filter applies. If the data item contains embedded
spaces, surround it with quotation marks.

data_item_stat

statistic type for data_item_name. The data_item_name and
data_item_stat combination must exist in th e view definition. Surrou nd

the statistic type with quotation marks.

filter_type

type of filter to use. Valid values are:

•

eq – pass es values that match any of a list of values. Th at is, a value

passes the filter if it equals the first filter value, or the second filter
value, or any other value in the list. Specify the list of values in the
value_spec parameter.

54 Historical Server

CHAPTER 4 Command Reference

•

neq – passes values that are not equal to any value in a list of

values. That is, a value passes the filter if it is not equal to the first
filter value, not equal to the second filter value, and not equal to any
other value in the list. Specify the list of values in the value_spec
parameter.

•

range – passes values that fall inside a range of values. Specify the

ranges in the value_spec paramete r.

•

top – passes a specified number of values that are the highest values

received for the data item during a sample interval. For example, a
top 10 filter passes the 10 rows of a sample that have the highest
values for the data item.

value_spec

specifies values for the filter tests. The syntax depends on the value of
filter_type:

If filter_type is value_spec sy ntax is

eq or neq value1[, value2]...

See “Using wildcards” on page 56 for information about
using a wildcard character (%) when valuen is a character
string. See “Specifying filters on object name and
procedure name” on page 56 for info rmat ion on sp e cifyin g
a value for the Object Name and Procedure Name data
items.

range To specify values greater than or equal to a low bound:

low,value

To specify values less than or equal to a hig h bound:

high,value

To specify values greater than or eq ual to a low bound and
less than or equal to a high bound:

low,value1,high,value2

See “Specifying filters on object name and procedure
name” on page 56 for info rmat ion on s pecify ing a va lue f or
the Object Name and Procedure Name data items. If you are
specifying both an upper and lower bound for either of these
data items, each bound must have the same number of
subcomponents.

top value

where value is the number of items to be passed. It must be
greater than zero.

User’s Guide 55

hs_create_filter

Examples

This example creates a filter for a view named Page I/O. The view contains
the Page I/O data item with a “Value for Session” statistic type. The
example limits the rows recorded for a sample to the 20 rows that have the
highest total number of Page I/Os for the recording session to date.

hs_create_filter PageIO,"Page I/O","Value for
Session",top,20

Usage Using multiple filters in a view

Filters limit the amount of data that Historical Server records. Each filter
applies to one data item i n the view . Each data item can have onl y one filter
applied to it.

If multiple data items in a view have filters, Historical Server records data
that satisfies all of the individual filters. Effectively, th e Boolean AND
operation is applied to the values of the various filters.

If the

top filter is in effect for a data item and another filter is in effect for

a second data item, some of the values passed by the
eliminated by the other filter. The result is that less that specified
values are returned.

Using wildcards

The wildcard character is the percent sign (%). When filter_type is eq or

neq, you can use the wildcard in value_spec for data items that return

character strings.The wildcard matches any string of zero or more
characters. The wildcard can appear anywhere within the filter value
(beginning, end, or anywhere in between). Only a single instance of the
wildcard can appear in value_spec.

top filter may be

top n

An exception to the single instance rule for the wildcard pertains to the
Object Name and Procedure Name data items. In those multi-component
data items, you can use a single instance of the wildcard in each
component. See “Specifying filters on object name and procedure name”
on page 56 for more information.

When filter_type is

range, you cannot use the wildcard character in

value_spec.

Specifying filters on object name and procedure name

The Object Name and Procedure Name data items accept multi­component values in value_spec when filter_type is

eq, neq, and range.

These composite filter values can use the following name forms, where
object_name is either a table name or a stored procedure name:

• object_name

56 Historical Server

CHAPTER 4 Command Reference

• owner_name.object_name

• database_name.owner_name.object_name
If filter_type is

eq or neq, each component can contain a single instance of

the wildcard character (%). The wildcard can b e used in place of the entire
component. For example, a value_spec of
data_item Object Name sets a filter that returns the

%.%.authors for the

authors table in all

databases, regardless of owner. See “Using wildcards” on page 56 for
more information about the wildcard character.

If filter_type is

range with both upper and lower bounds, the two bounds

must have the same number of subcomponents.
Some specific considerations for designing filters using these component

data items follow:

•If database_name is a component of a composite filter value for an
“Object Name” data item, a “Database Name” data item also must be
present in the view.

•If owner_name is a subcomponent of any composite filter value for an
“Object Name” data item, an “Owner Name” data item also must be
present in the view.

•If database_name is a subcomp onent of any composite filter val ue for
a “Procedure Name” data item, a “Procedure Name” data item also
must be present in the view.

•If owner_name is a component of any composite filter value for a
“Procedure Name” data item, a “Procedure Owner Name” data item
also must be present in the view.

hs_create_playback_session

Description Defines the characteristics of a play back session. This command is the first

step in creating a playback session.

Syntax hs_create_playback_session start_time, end_time,

summarization_interval, allow_estimation, missing_data_option, target,
directory_name, protection_level, sample_interval, script_type,
delete_option, session_id [ , session_id... ]

User’s Guide 57

hs_create_playback_session

Parameters

start_time

specifies the date and time of the beginning of the recorded data to be
played back. The default is to start playback from the beginning of the
first session specified by session_id. Use the value NULL to accept the
default.

The format for start_time is:

58 Historical Server

CHAPTER 4 Command Reference

“year/month/day hour:minute[:second] [time zone]”

Depending on the summarization_interval and missing_data_option
parameters, and depending on whether there is any data available at the
time specified, playback might use data from a time later than that
specified; however, playb ack does not use data from a time earlier than
start_time.

The start_time, if specified, must be earlier than the end time of at least
one of the sessions specified in session_i d. The following time zone
options are available:

Parameter value Explanation

EST U.S. eastern time zone, standard time.
EDT U.S. eastern time zone, daylight sav ing time .
CST U.S. central time zone, standard time.
CDT U.S. central time zone, daylight saving time.
MST U.S. mountain time zone, standard time.
MDT U.S. mountain time zone, daylight saving time.
PST U.S. Pacific time zone, standard time.
PDT U.S. Pacific time zone, daylight saving time.
MET Middle European time zone, standard time.
MET DST Middle European ti me zone, daylight saving time.
WET DST We stern European (Greenwich) time zone, daylight

saving time.

GMT Greenwich mean time. This is equivalent to western

European (Greenwich) time zone without regard to
daylight saving time. All of the preceding tim e zone
specifications, such as EST or EDT, can be supplied only
in combination with dates and times when standard tim e
or daylight savings time is in effect. GMT ca n be paired
with any date and time specification.

GMT{+-}

hours_offset

To specify any other time zone, where hours_offset is the
number of hours that must be added to Greenwich mean
time to derive the local time. The acceptable range of
offset values is between +24 and -24 ho urs, inclusive.
Fractional offsets such as +5.5 are valid.

The default time_zone is the local time zone of Historical Server.

User’s Guide 59

hs_create_playback_session

end_time

specifies the date and time for the end of the recorded data to be played
back. The default is to end playback at the end of the last session
specified. Use the value NULL to accept the default.

The format of this parameter is the same as the start_time format. The
end_time, if specified, must be later than the start_time of at least one
input session.

60 Historical Server

CHAPTER 4 Command Reference

summarization_interval

a required parameter (no default exists) that specifies the level of detail
of the playback. Valid values are:

•

raw – plays back data as it was collected, using the same sample

intervals. Choose this option to view raw data as it was recorded.
Also, this is the only option available for playing back snapshot
data, such as current SQL statement data and status information on
locks or processes. See Table C-2 on page 165 for a definitive list
of the snapshot data items. (They are the ones with “no” in the
“Allowed for Non-raw” column.)

This option is valid only when target is

•

actual – plays back data using the same sample intervals as the

client.

input recording sessions.
This option allows you to specify some data item changes in the

playback view. Als o, Historical Server makes appropriate
adjustments to the first and last samples when the recording session
times do not align with the requested playback session times.

Choose this option to add or change certain data items when
summarization is not required. Also, when target is set to file, this
option provides a way to concatenate the non-snapshot data in
multiple recording sessions.

This option is valid only when target is

•

entire – plays back data for each input recording session

client.

summarized as a single sample. The sample interval is the timespan
between the requested playback start_time and end_time.

This option allows you to specify some data item changes in the
playback view. Als o, Historical Server makes appropriate
adjustments to the data values to accurately reflect the requested
playback session start and end times.

Choose this option to consolidate recorded data, rolling up details
into overviews of activity over longer time periods.

sample_interval

plays back data summarized into sample intervals of the specified
length. The parameter value is the sample interval length, specified as:

"S"
"M:S"
"H:M:S"

User’s Guide 61

hs_create_playback_session

"D H:M:S"

where:

• S – is seconds.

• M – is minutes.

• H – is hours.

• D – is days.
All components are numeric and can be one or two digits. Some

examples are:

"30" (specifies sample intervals of 30 seconds)
"10:0" (specifies sample intervals of 10 minutes)
"8:30:0" (specifies sample intervals of 8 1/2 hours)
"5 0:0:0" (specifies sample intervals of 5 days)

The first sample interval starts at start_time, and every sample, except
possibly the last one, has the specified length.

This option allows you to specify some data item changes in the
playback view. Also, Historical Server makes appropriate adjustments
to the data values to accurately reflect the requested playback session
length and playback sample intervals.

Choose this option to summarize data into any desired granularity. This
type of summary can mediate deviations in activity and is useful for
observing trends over time.

The

actual, entire, and user-defined interv al opti ons have the foll owing

features in common:

• Data item changes in playback views – for all three options, the
playback view can use statistic types different from those in the
input view, and it can include some estimated and calculated data
items not in the input view . It cannot include snapshot d ata, such as
current SQL statement data. See Table C-2 on page 165 for a
definitive list of data items and statistic types that can be included
in playback views when these options are chosen.

• Data adjustments – for all three options, Historical Server performs
appropriate mathematical computations to compensate for
differences in:

• the input recording sessions sample intervals and the requested

playback sample intervals

62 Historical Server

CHAPTER 4 Command Reference

• the input recording sessi onss session lengths and the r equested
playback start and end times

To handle these differences, accumulated counts are prorated.
Percentages and rates are weight-averaged, weighted by the
number of seconds that each input sample contributes.

See Appendix C, “Specifications for Defining Playback Views”
for more information.

allow_estimation

specifies whether or not you want pl ay back to estim ate values for data
items that cannot be calculated exactly. Valid values are:

•

disallow (the default) – causes the hs_create_playback_view

command to return an error if it encounters data items that require
estimation.

•

allow – causes playback to estimate values, if necessary, for certain

data items. Some data items cannot be included in a playback view
unless you allow estimation in the playback session.

This parameter is ignored if summarization_interval is

raw.

See Tabl e C- 2 on page 165 to determine which data items require
estimation.

missing_data_option

when target is

hs_playback_sample command treats periods of time when no data is

client, this parameter specifies how the

available in the input sessions. Valid values are:

•

skip (default) – when a time period contains no data, the
hs_playback_sample command goes directly to the next time

period containing data, rather than returning a sample having no
data.

•

show – the hs_playback_sample command returns a sample even

for a time period where no data is available. During client
playback, the column headers are returned with zero rows.

When target is

file, gaps are not allowed.

User’s Guide 63

hs_create_playback_session

target

specifies the target results of the playback session. Valid values are:

•

client (default) – enables playback to the client.

•

file – enables creation of a new session containing all the data

specified by this
subsequent

hs_initiate_playback command to create the new session. Setting

target to
is

file is not allowed if the summarization_interval parameter

raw or actual.

hs_create_playback_session command and by

hs_create_playback_view commands. Use the

directory_name

when target is
files are created. This parameter is ignored when target is

file, this parameter specifies the directory where the new

client. The

default is the Historical Server home directory.
The operating system account that started Historical Server must have

execute (search) and write permission on the specified directory.

protection_level

when target is

hs_initiate_playback command assigns to the data files for the newly

file, this parameter specifies the permission level that the

created session. The protection level controls viewing the metadata in
the control file (using the
sessions with the data (using the

hs_list command) and creating playback

hs_create_playback_session

command). Valid values are:

•

private (default) – specifies that the new files will be password-

protected. The files will be accessible only to the same account that
created them or to the Historical Server superuser.

•

public – gives unrestricted access to the data in the new session’s

files.

•

null – implements the default value, private.

When target is

client, this parameter is ignored.

64 Historical Server

CHAPTER 4 Command Reference

script_type

when target is

hs_initiate_playback command to create a script file for the newly

file, this parameter specifies whether you want the

created session. The script file contains SQL commands that create an
Adaptive Server table for each playback view defined for the new
session. Valid values are:

•

no_script (default) – does not create a script file for the new session.

•

sybase_script – creates a script file. The file is located in the

Historical Server home directory. Its name is sSessionId, where:

• s is a constant.

• SessionId is assigned by Historical Server.

•

null – implements the default value, no_script.

When target is

client, this parameter is ignored.

delete_option

when target is

hs_initiate_playback comman d to delete the input session files after

file, this parameter specifies whether you want the

successfully creating the new session. Valid values are:

•

retain (default) – does not delete the files containing the data fo r the

input sessions.

•

delete – deletes all input session files, if creation of the new session

is successful. The user must be either the Historical Server
superuser or the owner of all the input sessions.

•

null – implements the default value, retain.

When target is

client, this parameter is ignored.

User’s Guide 65

hs_create_playback_session

session_id[ ,session_id. . .]

specifies the unique identifiers for the input sessions to be play ed back.
At least one session_id is required. When more than one are used, they
must be specified in the correct order according to their start times, with
the earliest start time first. Playback skips over the sessions that are out
of order. If summarization_interval is

raw, then only one session_id is

valid.
Historical Server assigns a session ID to a recording session when the

recording session is defined. Use the

hs_list command to find the

session IDs that you want to play back.
If target is

file, no gaps can exist between an input session’s end time

and the next input session’ s start time. Also, each session specified must
have completed its recording.

If target is

client, then each session must have started recording, but can

be continuing to record when you submit the

hs_create_playback_session command.

Examples 1 This example creates a playback session based on a single input

session (session 7). The session is played back in its entirety , with no
summarization or normalization, and without creating a n ew session.

hs_create_playback_session null, null, raw,
null, null, client, null, null, null, null, 7

2 This example creates a playback session based on three input sessions

(sessions 4, 6, and 9). Only data collected between the time period
from 9:00 to 5:00 is played back. The played b ack data is summarized
at half-hour intervals. The playback is stored as a new session.

hs_create_playback_session "1996/5/3 9:00",
"1996/5/3 17:00", "0 00:30:00", disallow, skip,
file, null, public, no_script, retain, 4, 6, 9

Usage

• A connection to Historical Server can either be defining a recording
session or defining and executing a playback session, but not both.
After the successful execution of the
command, you must successfully execute a

hs_create_playback_session

hs_terminate_playback

command before starting to define a recording session or starting to
define another playback session.

• The behavior of the playback session is different depending on the
value of the target parameter:

66 Historical Server

CHAPTER 4 Command Reference

•If target is

hs_playback_sample command. Playback can occur from

client, the client retrieves the data using the

recording sessions that are still in the process of recording.

•If target is

file, the client does not retrieve any data for this

playback session; instead, Historical Server creates a new session
and fills the data files for that new session with the data from this
playback session. The accessibility of the new session is
determined by the protection_level parameter. The user who
invokes this command is the owner of the new session. The

hs_initiate_playback command creates the new session.

Playback is restricted to sessions that are finished recordin g as of
when you submit the

•If target is

file and multiple playback sessions are used as input,

hs_create_playback_session command.

no time gaps are allowed. For example, if you collected data from
9 a.m. to 5 p.m. every day from Monday through Friday, you
could not play back those five recordin g sessions to create a new,
summarized, weekly session. However , if y ou eliminate the time
gaps by collecting data from 9 a.m. to 9 a.m. every day from
Monday through Friday, you could use the playback feature to
create a new, summarized weekly session. Another way to
eliminate the time gaps is to keep the 9 a.m. to 5 p.m. recording
session, but add another set of recording sessions scheduled from
5 p.m. to 9 a.m. Use a l ong er sample interval for the off hours to
reduce the volume of data collected.

• The value of the summarization_interval parameter used in the

hs_create_playback_session command affects the rules that the
hs_create_playback_view command uses to define views.

hs_create_playback_view

Description Specifies a view from the input recording sessions that you want to include

in the playback session. Also specifies the data items in each view that you
want to play back.

Syntax hs_create_playback_view view_name,

[data_item_name_1, data_item_stat_1
[,data_item_name_2, data_item_stat_2]...]

User’s Guide 67

hs_create_playback_view

Parameters

view_name

name of a view that you wa nt to play back. The playback view name
must match the name of a corresponding view in the input sessions. If
there are two or more input sessions, then the view must exist in all of
the input sessions and must contain the exact same data items and filters
in all of the input sessions.

Only one playback view can be defined for a given view name. An
attempt to create a second playback view with the same name fails.

Use the

hs_list command to list the views in an input session and the

data items in each view.

data_item_name_n

data items existing in the input view that you want to see in the playback
view . (In some cases, you can introduce new data items not in the input
views.) If the data item contains embedded spaces, surround it with
quotation marks.

If you do not specify any data items, then the view is defined using all
of the data items from the corresponding view in the input sessions.
However, if a data item from that corresponding view is not valid in the
playback view, an error results.

See Table C-2 on page 165 for more information about designing
playback views.

data_item_stat_n

statistic types for the respective data items. The statistic types do not
necessarily need to be the same as the statistic types used in the input
view. See Table C -2 on page 165 to determine valid statistic types for
data items in playback views.

Surround statistic types with quotation marks.

Examples 1 This example creates a playback view based on the view device_view

from the input sessions. The playback view includes all of the data
items from the input view, with the same combinations of data items
and statistic types:

hs_create_playback_view device_view

2 This example creates a playback view that returns a timestamp and

two data items from the input sessions:

hs_create_playback_view
device_view,"Timestamp","Value for
Sample","Device Name", "Value for Sample",

68 Historical Server

CHAPTER 4 Command Reference

"Device Reads","Rate for Sample"

Usage

•The hs_create_playback_view command is valid only during the

definition of a playback session; that is, it must be issued after a
successful
successful

hs_create_playback_session command, but before a
hs_initiate_playback command.

• A playback session must have at least one view.

• Appendix C, “Specifications for Defining Playback Views” explains

the requirements for designing valid playback views, including val id
combinations of data items and statistic types for playback views.

hs_create_recording_session

Description Establishes a new recording session.
Syntax hs_create_recording_session monServerName, sample_interval

[,dir_name][,start_time][,end_time]
[,protection_level][,error_option][,script_type], [tab_delimited]

Parameters monServerName

name of the Monitor Server used to collect data from the Adaptive
Server for which you want to collect histori cal data. The user name and
password you used to connect to Historical Server must match a valid
login account on the Adaptive Server being monitored by the Monitor
Server you specify here.

sample_interval

determines the time between samples (in seconds). The shortest valid
sample interval is one second; the l ongest valid sample interval is 86400
seconds, which is the number of seconds in one day.

dir_name

path name of the director y where th e historical data files resultin g from
this recording session will reside. The operating system account that
started Historical Server must have search (execute) and write
permissions on this directory.

The default is the Historical Server home directory, specified in the

-D

parameter to the Historical Server start-up command.

start_time

date and time at which recording is to start, using the format:

User’s Guide 69

hs_create_recording_session

year/month/day hour:minute[:second] [time zone]

The default is to start immediately . The following time zone options are
available:

Parameter value Explanation

EST U.S. easter n time zone, standard time.
EDT U.S. eastern time zone, daylight saving time.
CST U.S. central time zone, standard time.
CDT U.S. central time zone, daylight saving time.
MST U.S. mountain time zone, standard time.
MDT U.S. mountain time zone, daylight saving time.
PST U.S. Pacific time zone, standard time.
PDT U.S. Pacific time zone, daylight saving time.
MET Middle European time zone, standard time.
MET DST Middle European time zone, daylight saving time.
WET DST Western European (Greenwich) time zo ne, daylight

saving time

GMT Greenwich mean time. This is equivalent to western

European (Greenwich) time zone without regard to
daylight saving time. All of the preceding time zone
specifications, such as EST or EDT , can be supplied only
in combination with dates and times when standard time
or daylight savings time is in effect. GMT can be paired
with any date and time specificati on.

GMT{+-}

hours_offset

To specify any other time zone, where hours_offset is the
number of hours that must be added to Greenwich mean
time to derive the local time. The acceptable range of
offset values is between +24 and -24 hours, inclusive.
Fractional offsets such as +5.5 are vali d.

If you do not specify a time zone, the local time zone of the Historical
Server is used.

The start_time cannot be more that 31 days from the present time.

end_time

time at which recording is to stop. The default is to stop the recording
session 24 hours after the start_time. If you specify an end_time and do
not specify a start_time, the start_time defaults to the presen t.

70 Historical Server

CHAPTER 4 Command Reference

protection_level

specifies whether the data files created in this recording session are
password-protected or accessible to all users. The protection level
controls viewing the metadata in the control file (using the

hs_list

command) and creating playback sessions with the data (using the

hs_create_playback_session command).

•

private (default) – s pecifies that the recorded data will be password-

protected. The files will be accessible only by the same account
that created them, or by the Historical Server superuser.

•

public – specifies that access to the recorded data will be

unrestricted.

error_option

specifies how you want Historical Server to handle non-fatal errors
during a recording session. Valid values are:

•

continue (default) – specifies that recording is to continue when

non-fatal errors are detected. For example, when the Monitor
Server fills all of its configured buffers while summarizing
monitoring information, one or more non-fatal errors are sent to
Historical Server, but it is still possible for Historical Server to
collect the available information from the current sample and from
future samples.

•

halt – specifies that the recording session is to terminate when a

non-fatal error is detected.

script_type

specifies whether you want Historical Server to create a script file that
creates tables from your the recording session view definitions.

•

sybase_script – creates a script file containing SQL commands that

create an Adaptive Server table for each view in the recording
session.

•

no_script (the default) – does not create a script file.

tab_delimited

When adding this to the

hs_create_recording_session, the default output

file delimitoer HS is using will be ignored. Instead the TAB character
will be used.

User’s Guide 71

hs_create_view

Examples

This example creates a recording session to capture data from the Monitor
Sever called SERVER1_MON. The data is captured every 30 seconds and
written to the data files in the /user/hist_dir directory, starting now and
ending on August 8, 1997 at 10: 30 a.m. EDT (eas tern time zon e, dayli ght
saving time). The resulting files have private restrictions. The recording
session continues if non-fatal errors are detected. A script file that creates
an Adaptive Server table for each recorded view is created.

hs_create_recording_session SERVER1_MON,30,
/user/hist_dir,NULL,"97/08/08 10:30 EDT",
private,continue, sybase_script

Usage

• Fatal errors include crashes and other connection failures with
Adaptive Server or Monitor Server. A fatal error forces termination of
the recording session, regardless of the value of error_option.

• Y ou mus t issue this command b efore you define any views, alarms, or
filters for the recording session. After you have issued this command
and have defined at least one view, you can start recording with the

hs_initiate_recording command.

hs_create_view

Description Defines a collection of data items to be recorded during a session.
Syntax hs_create_view view_name,

data_item_name_1, data_item_stat_1
[,data_item_name_2, data_item_stat_2]...

Parameters view_name

user-defined name of the view. The view name must be constructed
from the characters a – z, A – Z, 0 – 9, and the undersco re character (_).

data_item_name_n

data items that participate in the view . If a d ata item contains embedded
spaces, surround it with quotation marks.

See Table A- 1 on page 103 for a list of available data items. See
Table B-2 on page 124 for valid combinations of data items within
views.

data_item_stat_n

statistic types of the respective data items. The statistic type must be
surrounded with quotation marks. Valid statistic types are:

72 Historical Server

CHAPTER 4 Command Reference

•

“Value for Sample”

• “Value for Session”

• “Rate for Sample”

• “Rate for Session”

• “Avg for Sample”

• “Avg for Session”
Not all statistic types are valid for all data items. See Table B-3 on

page 148.

Examples This example creates a view called Page I/O that contains the Page I/O

data item with a Value for Session statistic type and the Kernel Proc ess ID
data item with a Value for Sample statistic type.

hs_create_view PageIO,"Page I/O","Value for
Session","Kernel Process ID","Value for Sample"

Usage

• The order in which you specify the options determines the order in

which the data items are stored in the recorded data file for the view.

• You must define at least one view for each recording session.

• If you intend to use the Historical S erver playback features to examine

data in a recording session, you might want to think about the
playback view while designing the recording session view.

For many data items, Historical Server can play back a data item using
a different stati stic type from the one used during recording . However,
for some data items, Historical Server summarizes data by estimating
values (as opposed to exact calculation), unless certain additional data
items are included in the r ecorded data. See Table C-2 on page 165 to
determine which data items are required for exact calculations.

hs_delete_data

Description Deletes the historical monitoring files associated with one or more inactive

recording sessions.

Syntax hs_delete_data low_session_id [,high_session_id]

User’s Guide 73

hs_initiate_playback

Parameters

low_session_id

unique identifier of the first recording session whose data is to be
deleted.

high_session_id

unique identifier of the last in a range of sessions whose data is to be
deleted. If omitted, only the session identified by low_session_id has its
data deleted.

Examples This example deletes historical monitoring files for any inactive recording

sessions that have session IDs of 1 through 15.

hs_delete_data 1,15

Usage

• The only users who can delete historical data files are:

• Historical Server superuser

• Users who connected to Historical Server using the same user

name and password that defined the recording session

• Only inactive recording session files are deleted. Files associated with
active recording sessions are not deleted, even if their session IDs fall
within the range specified in the

hs_delete command.

• An inactive recording session is one that was terminated because the
end_time was reached or because the

hs_terminate_recording

command was issued.

hs_initiate_playback

Description Specifies that you are finished defining a playback session and ready to

perform the playback. If the playback target is to a file, this command
starts the playback. If the playback target is to a client, this command
initializes playback so that the
default step returns the first sample in the playback session.

Syntax hs_initiate_playback
Usage

•The hs_create_playback_session command and one or more
successful

hs_initiate_playback command.

hs_create_playback_view commands must precede the

74 Historical Server

hs_playback_sample command with a

CHAPTER 4 Command Reference

• If no views were created before the

then

hs_initiate_playback returns an error. The user may still attempt

an

hs_create_playback_view command, or may cancel the playback

session with the

hs_terminate_playback command.

hs_initiate_playback command,

hs_initiate_recording

Description Specifies that the definition of a recording session is complete and

requests that recording be started or scheduled to start at the recording
session’s start_time.

Syntax hs_initiate_recording
Usage

•The hs_create_recording_session command and one or more

hs_create_view commands must precede the hs_initiate_recording

command.

•One or more

also precede the

• After you execute the

hs_create_alarm and hs_create_filter commands may

hs_initiate_recording command.

hs_initiate_recording command, you may later

cancel the session, but you cannot add any more views, filters, or
alarms to the description of this recording session.

hs_list

Description Lists information about past and present recording sessions.
Syntax hs_list level [,restriction]

Parameters

User’s Guide 75

level

specifies the level of detail returned for each recording session. Its value
can be

sessions, views, data_items, alarms, filters, or

summarization_data_items.

hs_list

restriction

Selects a subset of the data available about recording sessions for a
given level.

If level is Then restriction is

sessions • One of the following:

• active – limits the returned data to currently active
recording sessions of this Historical Server instance.

•

inactive – selects only completed recording sessions.

• latest – selects only the recording session (if any) most
recently initiated on the current client connection.

• If restriction is omitted, all active and inactive recording
sessions that you have permission to access are listed.

views • A session ID whose views you want to list.

• If restriction is omi tted, the views of all record ing sessions
that you have permission to access are listed.

data_items,
alarms

, filters,

or

summarization
_ data_items

• A session ID and, optionally, a view name whose data items
you want to list. The syntax is:

session_id [,view_name]

session_id limits the listing to data items that participated
in a single session. If specified, view_name limits the
listing to data items that appeared in a single view defined
for the session.

• If restriction is omitted, the data items that belong to all
views defined for all active and inactive recording sessions
that you have permission to access are listed.

Examples 1 This example lists all active sessions for this Historical Server

instance:

hs_list sessions,active

2 This example lists all alarms that ha ve be en d efined for data items in

the Page I/O view of the session whose ID is 10:

hs_list alarms,10,PageIO

Usage

•The hs_list command returns the following fields as an integer
datatype:

•Session ID

• Sample interval

• Alarm count

76 Historical Server

• Filter count

CHAPTER 4 Command Reference

•The

hs_list command returns the following field as a float datatype:

• Alarm value

• All other fields are returned as character strings.

• If a session was recorded with the

private protection level and the

current user is not the Historical Server superuser, the current user’s
name and password are verified against the name and password of the
user who recorded the session before that session is made visible.

Description of returned data

The data returned by hs_list depends on the value of level:

•

sessions causes a single row to be returned for each session, with the

following columns:

• Session ID (a unique identifier for the session)

• Status of the session:

• active

• inactive

• active remotely or inactive – status of the session cannot be
determined unambiguously. Sessions that are currently
active in another instance of Historical Server that is using
the same home directory as the current instance fall into this
category. (For more information about running multiple
instances of Historical Server and sharing control files, see
“Configuring multiple instances of Historical Server” on
page 23.) Sessions that have already ended because of an
abnormal termination of the Historical Server instance that
was running them, and whose intended end times have not
yet been passed, are also in this category.

• Name of the user who initiated the recording session

• Name of the Adaptive Server monitored

• Name of the Monitor Server used

• Start date and time of the recording session

• End date and time of the recording session

• Directory containing the recorded data

User’s Guide 77

hs_list

• Sampling interval used
If this value is 0, it means that the session was created by

playback with a summarization_level of

entire. (The entire

session is represented in one sample, and there is no sample
interval.)

• Error option used (continue or halt on non-fatal error)

•

views produces one row for each view, with the following columns:

•Session ID

•View name

•

data_items produces one row for each data item defined in a view,

with the following columns:

•Session ID

•View name

• Data item

• Data item statistic type

• Number of alarms defined for the data item

• Number of filters defined for the data item

• One of the following keywords:

•

recorded – indicates that the data is from the original

recording session or preserved from that original session.

•

summarized – indicates that the data was summarized at a

different sample interval from that of the original session.

•

estimated – indicates that the data was estimated, rather than

calculated accurately, during summarization.

•

alarms produces one row for each alarm defined for a data item in a

view, with the following columns:

•Session ID

•View name

• Data item

• Data item statistic type

• Alarm action (

log or execute)

78 Historical Server

CHAPTER 4 Command Reference

• File name for log file or file to execute

• Alarm value

•

filters produces one row for each filter for a data item in a view, with

the following columns:

• Session ID

•View name

• Data item

• Statistic type

• Filter type (

eq, neq, range, or top)

• Value specified (returned as a single string)

•

summarization_data_items produces one row for each combination of

data item and statistic type that can be requested for non-raw playback
from a view, with the following columns:

• Session ID

•View name

• Data item

• Statistic type

• One of the following keywords:

•

recorded – indicates that the data for this data item, if played

back, would be the data from the or iginal reco rding s ession ,
or data preserved from that original session.

•

summarized – indicates that the data for this data item, if

played back, would be available in summarized form.

•

estimated – indicates that the data for this data item, if played

back, would be available only in estimated form.

hs_playback_sample

Description Plays back a sample when the playback target is client. The target is

defined in the

Syntax hs_playback_sample [step [, retry_count] ]

User’s Guide 79

hs_create_playback_session command.

hs_playback_sample

Parameters

step

specifies the sample to send to the client, relative to the sample sent in
the most recent

hs_playback_sample command for the current playback

session. Valid values are 0 or positi ve n umbers.
The default is +1, which sends the next later sample. At the beginning,

a step of +1 returns the first sample. Zero resends the most recently sent
sample. A step of +2 sends the next later sample after the one that a step
of +1 would have sent, and so on. An attempt to displ ay a sam pl e la ter
than the last sample returns an error message.

The

hs_initiate_playback command in itializes playback so that the

default (+1) sends the first sample in the playback session.
The definition of what constitutes a sample is affected by the

summarization_interval and missing_data_option parameters to th e

hs_create_playback_session command.

If the playback session was created with a summarization_interval
parameter of

actual, entire, or a user-specified interval, and if any v iew

in the playback session contains a data item with a statistic type of

“Value for Session” or “Rate for Session”, then the only permissible value

for step is +1, the default.

retry_count

specifies the number of times that the Historical Server will retry, at
one-second intervals, to read data from a historical data file of a
recording session that is still recording at the time of playback.

The default is zero, that is, no retries are attempted and an error is
returned when playback reaches an end-of-file condition while reading
a historical data file.

Examples 1 This example plays back the next sample:

hs_playback_sample

2 This example skips over one sample and plays the next sample. If

recording is ongoing, Historical Server retries up to 30 times to
retrieve another sample if the end-of-file is reached.

hs_playback_sample 2, 30

Usage Format of returned data

The hs_playback_sample command returns data in the f orm of tab les. It
returns one table for each playback view. The tables are arranged in the
same order in which you submitted the

hs_create_playback_view

commands that created the views.

80 Historical Server

CHAPTER 4 Command Reference

The columns in each table correspond to the data items in the
corresponding playback view. The columns are arranged in the order in
which the data items were listed when you de fined the playback view. See
Table B-3 on page 148 to determine the datatype of each column.

Each row represents a different combination of key data items in the view .
If the view contains no key data items, then the table returns a single row
reflecting server-level data.

When there is no activity to report, some views return a row with zero
values and other views omit the row. The rules controlling whether or not
a row with zero values appears in a view are:

• Views with server-level data items always return a row, even when
there is no activity to report.

• Views that contain the key data items Process ID, Object ID, or
Procedure ID omit the row when there is no activity to report. See
“Views with Process ID” on page 81 for more explanation about
when a Process ID is returned.

• Views that contain keys other than those listed in the previous item
return rows even when there is no activity.

If playback is summarizing data, a row is returned for a combination of
keys if any sample in any of the input sessions contains the same
combination of keys.

If an integer data item overflows, Historical Server returns the largest valid
number in the data item, and returns an information message to the client.

Views with Process ID

When a server process terminates, Adaptive Server can reuse its Process
ID for a new process. Therefore, the Process ID data item is not guaranteed
to uniquely identify a process. The Kernel Process ID data item, however,
uniquely identifies a process.

Views that include Process ID return rows as follows:

• Recording session views (and hence, raw playback views) return a
row only for Process IDs representing processes that exist at the end
of a sample interval. If a server process terminates in the middle of a
sample interval, a row is not returned for its Process ID.

User’s Guide 81

hs_playback_sample

• Summary playback views do not require the server pr ocess to exist for
the duration of the playback s amp le . Sum mary views r eturn ro ws fo r
all server processes included in any of the input views. However,
since Process ID is not guaranteed to be unique, the Kernel Process
ID must be included in any su mmary view that includes Process ID to
ensure uniqueness of the key. Otherwise, the summary could
erroneously combine data from two different processes.

Gaps in data within the playback session

The start_time and end_time parameters to the

hs_create_playback_session command define the period of time that the

playback session covers. When the target parameter to the

hs_create_playback_session command is client, there might be intervals of

time between the playback session’ s start and end times for which no data
is available in any of the input sessions.

Note When target is file, no gaps are allowed in the specified input

sessions, so there will not be gaps in the playback session.

Gaps in available data might occur when:

• The input sessions specified for the playback session are not
contiguous. For example, if a series of input sessions covered the time
period between 9 a.m. and 5 a.m., Monday through Friday, data gaps
would exist between 5 p.m. each evening and 9 a.m. the next morning.
Larger gaps would exist between Friday evening and Monday
morning.

• The playback session does summarization and has a start or end time
beyond when data is available from the input sessions.

When the target of playback is a client, Historical Server handles gaps
according to the value of the missing_data_option parameter to the

hs_create_playback_session command:

•

skip (the default) – when a time period contains no data, the
hs_playback_sample command goes directly to the next time period

containing data, rather than returning a sample having no data.

•

show – the hs_playback_sample command returns a sample even fo r a

time period where no data is available. No data is returned (the length
of each data table returned is zero).

82 Historical Server

CHAPTER 4 Command Reference

For the client to receive a timestamp in this case, there must be a
playback view containing only the data item

. A view containing any other data items returns zero rows.

Datim

Timestamp or Timestamp

The playback session’s summarization level affects the number of
empty samples returned during playback:

•if summarization_level is
represented with one sample. For example, a gap in data between
the hours of 5 p.m. and 9 a.m. would be represented by one
sample.

•if summarization_level is a time interval, such as 1/2 hour
(specified as

"0 00:30:00"), the gap is represented with a

sample for each time interval. For example, if the time interval is
specified as 1/2 hour, a gap in data between the hours of 5 p.m.
and 9 a.m. would be represented by 32 empty samples.

•if summarization_level is

hs_shutdown

Description Shuts down Historical Server.
Syntax hs_shutdown [wait_option]

Parameters

wait_option

specifies whether termination should occur immediately or wait for
active connections to close. Valid values are:

•

no_wait – causes Historical Server to shut down immediately and

terminates any connections (inclu ding those performing playback)
and active recording sessions. The active recording sessions and
playback sessions that are creating new sessions are shut down in
a controlled manner, which prevents corruption of the control file
or any historical data files.

raw or actual, the entire gap is

entire, gaps are ignored.

•

wait (the default) – defers shutdown until all active recording

sessions (including those performing playback) complete and any
other active connections are closed. No new connections are
accepted during this time.

Examples This example shuts down Historical Server immediately and terminates

any connections and active recording sessions.

User’s Guide 83

hs_shutdown

hs_shutdown no_wait

Usage

• If you use the hs_shutdown command without the no_wait option and
then want to cancel the request, you can send an interrupt to Historical
Server to cancel the shutdown request. A DB-Library application
calls the

ct_cancel() function to cause such an the interrupt. The isql command

dbcancel() function and a CT-Library application calls the

generates one of these calls when you send it an interrupt signal,
which usually is done by typing Ctrl+C.

• You can request an immediate shutdown of Historical Server at any
time by sending one of the following four signals:

• SIGQUIT (quit)

• SIGINT (interrupt)

• SIGABORT (abort)

• SIGTERM (terminate)
Reception of one of these signals at any time (including while waiting

for the

hs_shutdown command to complete) is equivalent to issuing

the

hs_shutdown no_wait command.

Warning! Sybase strongly recommends that you do not u se th e kill

signal (SIGKILL) to shut down Historical Server. The kill signal does
not permit any controlled cleanup to be done and may result in data
loss.

• If any active sessions were terminated during the shutdown,

Historical Server writes information about the sessions to its log
file. Active sessions are recording sessions or playback sessions
in the process of creating a new recording session.

• If a superuser was specified in the Historical Server start-up

command, the only user who can shut down Historical Server is
the superuser . If a super user was not specified, any user can s hut
down Historical Server.

• See Chapter 3, “Starting and Stopping Historical Server” for

more information about stopping Historical Server.

84 Historical Server

hs_status

Description Obtains status information.
Syntax hs_status option

Parameters

option

one of the following specifications:

•

directory – displays the name of the Historical Server home

directory, s pecified by the
start-up command.

•

superuser – displays the name of the Historical Server superuser,

specified by the

-U parameter to the Historical Server start-up

command (or NULL if this parameter was omitted).

•

interfaces – displays the path name of the interfaces or sql.ini file

in use by Historical Server.

•

max_connections – displays the maximum number of concurrent

client connections permitted.

•

logfile – displays the name of the Historical Server log file.

•

version – displays the version string and copyright information of

Monitor Historical Server.

CHAPTER 4 Command Reference

-D parameter to the Historical Server

•

activity – displays the following information about the current level

of activity on Historical Server:

Number of
connections

Number of act ive
recording sessions

Uninitiated
recording sessions

Number of act ive
playback sessions

Number of
uninitiated
playback sessions

Connections to Historical Server, including the
current connection

Sessions created with
initiated with
whose start times have not yet been reached.

Sessions created with hs_create_recording_session but
no matching

Sessions created with
initiated with

Sessions created with
matching

hs_initiate_recording was executed.

hs_initiate_playback was executed.

hs_create_recording_session and

hs_initiate_recording. Includes sessions

hs_create_playback_session and

hs_initiate_playback.

hs_create_playback_session but no

The activity information is relevant when stopping Historical Server
because Historical Server does not shut down while other connections
exist or any sessions are active, unless the

hs_shutdown command is explicitly requested.

User’s Guide 85

no_wait option for the

hs_terminate_playback

Examples

Usage The hs_status command returns the max_connections field and all of the

This example displays the name of the Historical Server home directory:

hs_status directory

activity fields as integer datatypes. All other fields are returned as character

strings.

hs_terminate_playback

Description Terminates the definition of a playback session and the actual

playback.

Syntax hs_terminate_playback
Usage

• This command is valid only after a successful

hs_create_playback_session command.

• Once you issue a successful
you must issue

hs_terminate_playback before you can start defining

hs_create_playback_session command,

any additional playback sessions or recording sessions.

• Unlike a recording session definition, playback session definitions are
not stored in the Historical Server control file.

hs_terminate_recording

Description Terminates the definition of a recording session, cancels the scheduled

start of a recording session, or terminates a recording session in progress.

Syntax hs_terminate_recording session_id [,delete_option]
Parameters

86 Historical Server

session_id

identifies the session you want to terminate. Historical Server assigns a
session ID when a session is defined with
Use the

hs_list command to view session IDs.

hs_create_recording_session.

delete_option

specifies whether to delete the files associated with the recording
session, if recording is in progress.