PI Server System Management Guide

(1)

PI Server System Management Guide

PI3 Server

Version 3.4.370

(2)

OSIsoft, Inc.

777 Davis St., Suite 250 San Leandro, CA 94577 USA Telephone

(01) 510-297-5800 (main phone) (01) 510-357-8136 (fax)

(01) 510-297-5828 (support phone)

North American Offices Houston, TX Johnson City, TN Mayfield Heights, OH Phoenix, AZ Savannah, GA Seattle, WA Yardley, PA

WWW.OSISOFT.COM Email: [email protected]

Worldwide Offices OSIsoft Australia Perth, Australia

Auckland, New Zealand OSI Software GmbH Altenstadt, Germany OSIsoft Canada ULC Montreal, Canada

OSIsoft Japan KK Tokyo, Japan

OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico

OSI Software Asia Pte Ltd. Singapore

OSIsoft, Inc. Representative Office Shanghai, People’s Republic of China Sales Outlets and Distributors

Brazil

Middle East / North Africa Republic of South Africa Russia / Central Asia

South America / Caribbean Southeast Asia

South Korea Taiwan

Revised: January 2006

Send documentation requests, comments and corrections to [email protected]. OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party's products or any affiliation with such party of any kind.

Restricted Rights Legend

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

Copyright Notice

(3)

P

REFACE

–

U

SING THIS

G

UIDE

About this Guide

The PI Server System Management Guide is an in-depth manual that provides the information and instructions that system administrators need to operate the PI System. This guide includes comprehensive instructions to assist you in:

Using PI Server command-line tools such as PIConfig, PIDiag, and PIArtool

Configuration and tuning of your PI Server for optimum performance

Monitoring system health, and ensuring data preservation and integrity

Managing the Snapshot, Event Queue and Data Archive

Troubleshooting and repair

To effectively manage a PI System, follow the recommendations and procedures for each of the following topics:

Starting and Stopping PI Systems

Backing Up PI Servers

Managing Archives

Managing Interfaces

Managing Security

Monitoring PI System Health

Moving, Copying or Merging PI Servers

For troubleshooting and performance issues, this guide includes Appendices of error messages provided in the System Message Log, and an extensive list of performance measurements (statistics) you can use to optimize the System.

(4)

The PI Server Documentation Set

The PI Server Documentation Set includes seven user guides, described below.

Tip: Updated user guides, which provide the most up-to-date information, may be

available for download from the OSIsoft Technical Support Web site (http://techsupport.osisoft.com).

Title Subject Matter

Introduction to PI

System Management A guide to the PI Server for new users and administrators. It explains PI system components, architecture, data flow, utilities and tools. It provides instruction for managing points, archives, backups, interfaces, security and trusts, and performance. It includes a glossary and resource guide.

PI Server Installation and Upgrade Guide

A guide for installing, upgrading and removing PI Servers on Windows and UNIX platforms, including cluster and silent installations.

PI Server System Management Guide

An in-depth administration guide for the PI Server, including starting and stopping systems, managing the Snapshot, Event Queue and Data Archive, monitoring system health, managing backups, interfaces, security, and moving and merging servers. Includes comprehensive instructions for using command-line tools: PIConfig, PIDiag, and PIArtool, and in-depth

troubleshooting and repair information.

PI Server Reference Guide

A comprehensive reference guide for the system administrator and advanced management tasks, including: databases; data flow; PI Point classes and attributes, class edit and type edit; exception reporting; compression testing; security; SQL subsystem; PI time format; and overviews of the PI API, and PI-SDK System Management Tool (SMT).

Auditing the PI

Server An administration guide that explains the Audit Database, which provides a secure audit trail of changes to PI System configuration, security settings, and Archive Data. It includes administration procedures to enable auditing, to set subsystem auditing mode, to create and archive database files, and to export audit records.

PI Server

Applications User Guide

A guide to key add-on PI Server Applications: Performance Equations (PE), Totalizer, Recalculator, Batch, Alarm, and Real-Time SQC (Statistical Quality Control). Includes a reference guide for Performance Equations, and Steam calculation functions.

PINet and PIonPINet

User Guide A systems administration guide, including installation, upgrade and operations, for PINet for OpenVMS and PIonPINet, which support migration and interoperability between PI2 and PI3 Systems.

(5)

Preface - Using this Guide

Conventions Used in this Guide

This guide uses the following formatting and typographic conventions.

Format Use Examples

Title Case PI Client Tools PI System Elements PI Server Subsystems

Use the client tool, PI ProcessBook, to verify that all data has been recovered.

All incoming data is queued in the Event Queue by the Snapshot Subsystem.

Italic text Files, Directories, Paths Emphasis

New Terms Fields

References to a chapter or section

The backup script is located in the \PI\adm directory. Archive files can be either fixed or dynamic. The

archive receiving current data is called the Primary

Archive.

See Section 4.2, Create a New Primary Archive.

Bold Italic text References to a publication See the PI Server Reference Guide. System and Application

components: Subsystems Tools / Utilities

Processes / Scripts / Variables Arguments / Switches / Options Parameters / Attributes / Values Properties / Methods / Events /

Functions

The Archive Subsystem, piarchss, manages data archives. Piarchss must be restarted for changes to take effect.

On UNIX, invoke site-specific startup script, pisitestart.sh, and on Windows, invoke pisrvsitestart.bat.

Three Point Database attributes affect compression: CompDev, CompMin, and CompMax. These are known as the compression specifications. Procedures and Key Commands On the Tools menu, click Advanced Options.

Press CTRL+ALT+DELETE to reboot Bold text

Interface components Menus / Menu Items Icons / Buttons / Tabs Dialog box titles and options

Click Tools > Tag Search to open the Tag Search tool.

Click the Advanced Search tab.

Use the search parameters PImean Value = 1.

Monospace type:

"Consolas"

font

Consolasmonospace is used for: Code examples

Commands to be typed on the command line (optionally with arguments or switches) System input or output such as

excerpts from log files and other data displayed in ASCII text Bold consolas is used in the

context of a paragraph

To list current Snapshot information every 5 seconds, use the piartool -ss command. For example:

Light Blue -

(6)

Related Documentation

OSIsoft provides a full range of documentation to help you understand and use the PI Server, PI Server Interfaces, and PI Client Tools. Each Interface has its own manual, and each Client application has its own online help and/or user guide.

The UniInt End User Manual describes the OSIsoft Universal Interface (UniInt), which is recommended reading for PI Server system managers. Many PI Interfaces are based upon UniInt, and this guide provides a deeper understanding of principals of Interface design.

Using PI Server Tools

The PI Server provides two sets of powerful tools that allow system administrators and users to perform system administration tasks and data queries.

The PI Server includes many command-line tools, such as pidiag and piartool. The PI Server Documentation Set provides extensive instruction for performing PI Server administrative tasks using command-line tools.

The PI System Management Tools (SMT) is an easy-to-use application that hosts a variety of different plug-ins that provide all the basic tools you need to manage a PI System. You access this set of tools through a single host application. This host application is sometimes referred to as the SMT Host, but it is more commonly called System Management Tools or SMT.

You can download the latest version of SMT from the Technical Support Web site:

http://techsupport.osisoft.com

In addition to extensive online help that explains how to use all of the features in the SMT, the SMT includes the Introduction to PI System Management User Guide.

(7)

Q

UICK

T

ABLE OF

C

ONTENTS

Chapter 1. Starting and Stopping PI ...1

Chapter 2. Monitoring PI System Health ...17

Chapter 3. Managing Archives ...33

Chapter 4. Backing up the PI Server...63

Chapter 5. Managing Interfaces ...93

Chapter 6. Managing Security ...115

Chapter 7. Moving PI Servers ...147

Chapter 8. Copying a PI Server ...151

Chapter 9. Merging Two PI Servers ...153

Chapter 10. The piconfig Utility...171

Chapter 11. PI Troubleshooting and Repair...225

(8)

(9)

T

ABLE OF

C

ONTENTS

Preface – Using this Guide ...iii

Table of Tables...xix

Table of Figures ...xxi

Chapter 1. Starting and Stopping PI ...1

1.1 Starting PI...1

1.1.1 Starting PI on Windows Systems ...2

1.1.2 Starting PI on UNIX Systems ...3

1.2 Stopping PI...3

1.2.1 Stopping PI on Windows Systems ...3

1.2.2 Stopping PI on UNIX Systems ...4

1.3 Automatic Startup ...6

1.3.1 Automatic Startup and Shutdown on UNIX Systems ...7

1.4 Shutting Down an Individual Subsystem...16

Chapter 2. Monitoring PI System Health ...17

2.1 Checking Key System Indicators...17

2.2 Viewing System Messages ...18

2.2.1 Available Log History...18

2.2.2 Viewing System Messages with pigetmsg ...18

2.2.3 Viewing Messages When the Message Subsystem Goes Down...20

2.2.4 Viewing Message Log Files Generated on other Servers...20

2.2.5 Interpreting Error Messages (pidiag)...21

2.2.6 Subsystem Healthchecks (RPC Resolver Error Messages) ...22

2.3 Monitoring Snapshot Data Flow...22

2.3.1 Listing Current Snapshot Information with piartool -ss...22

2.4 Monitoring the Event Queue...25

2.4.1 piartool -qs...25

2.5 Monitoring the Archive ...27

(10)

2.6 Monitoring the Update Manager ...30

2.6.1 Adjusting the Pending Update Limit ...31

2.7 System Date and Time ...31

Chapter 3. Managing Archives ...33

3.1 Tasks for Managing Archives...33

3.2 About Archives ...33

3.2.1 About Archive Shifts ...33

3.2.2 About Archive Files...34

3.2.3 About Primary Archives ...35

3.2.4 About Fixed and Dynamic Archives ...35

3.2.5 About Read-Only Archives ...37

3.3 Tools for Managing Archives ...37

3.3.1 Using the piartool Utility...37

3.3.2 Using the Offline Archive Utility (piarchss) ...40

3.4 Listing the Registered Archives ...46

3.4.1 Determining an Archive Sequence Number from a Listing ...47

3.5 Listing Archive Record Details ...49

3.5.1 Performing an Archive Walk with piartool -aw...49

3.6 Estimating Archive Utilization...51

3.7 Editing Archives ...51

3.8 Creating Archives...52

3.8.1 Naming Archives ...52

3.8.2 Choosing an Archive Size ...52

3.8.3 Selecting an Archive Type: Fixed or Dynamic...53

3.8.4 Specifying the Number of Points in the Archive ...53

3.8.5 Specifying the Maximum Archive Size ...54

3.9 Creating Data Archives Prior to the Installation Date...54

3.10 Creating a New Primary Archive...55

3.10.1 Registering an Archive ...56

3.10.2 Unregistering an Archive ...56

3.10.3 Deleting an Archive ...56

3.10.4 Moving an Archive ...56

3.11 Managing Archive Shifts...57

3.11.1 Archive Shift Enable Flag ...58

3.11.2 Forcing Archive Shifts...58

(11)

Table of Contents

3.12.1 Combining Archives into a Single Archive...59

3.12.2 Event Queue Recovery ...61

Chapter 4. Backing up the PI Server...63

4.1 Planning for Backups...63

4.1.1 Choosing the Backup Platform (VSS vs. Non-VSS) ...63

4.1.2 Choosing a Backup Strategy...63

4.2 Other Backup Considerations...64

4.2.1 Guidelines for VSS Backups ...64

4.2.2 Guidelines for non-VSS Backups ...65

4.3 Guidelines for Backing Up Before Upgrading ...65

4.4 Automating PI Backups ...66

4.4.1 Automating Backups on Windows...66

4.4.2 Do a Test Backup ...69

4.4.3 Do a Test Restore ...70

4.4.4 Automating Backups on Windows with a 3rd Party Backup Application...72

4.5 Automating Backups on a Windows Cluster...73

4.6 Automating Backups on UNIX...73

4.7 How The PI Backup Subsystem Works...74

4.7.1 Principles of Operation ...74

4.7.2 Selecting Files or Components for Backup ...75

4.7.3 The Backup Components of PI ...77

4.7.4 The Files and Components for each Subsystem ...78

4.7.5 Lifetime of a Backup ...80

4.8 Launching Non-VSS Backups with piartool -backup <path>...83

4.9 Managing Backups with piartool ...84

4.9.1 Backup Command Summary ...84

4.9.2 piartool -backup -query...85

4.9.3 piartool -backup -identify ...87

4.10 Timeout Parameters ...87

4.11 Troubleshooting Backups ...89

4.11.1 Log Messages ...89

4.11.2 VSSADMIN...90

Chapter 5. Managing Interfaces ...93

5.1 Introduction...93

5.2 General Interface Principles ...94

(12)

5.2.2 About PI Interface Nodes ...94

5.2.3 About Data Buffering ...95

5.2.4 About the PI API ...96

5.2.5 About the PI SDK ...96

5.2.6 About UniInt-Based Interfaces ...96

5.3 Basic Interface Node Configuration ...97

5.3.1 Install the PI SDK and/or the PI API...97

5.3.2 Connect to PI with apisnap.exe...98

5.3.3 Connect with AboutPI SDK.exe...98

5.3.4 Configure PI Trusts for the Interface Node...98

5.3.5 Install the Interface ...101

5.3.6 Set the Interface Node Time ...101

5.3.7 Connect to the PI Server with the Interface...102

5.3.8 Configure Points for the Interface...103

5.3.9 Configure Buffering...104

5.3.10 Configure Interface for Automatic Startup ...106

5.3.11 Configure Site-Specific Startup Scripts ...107

5.3.12 Configure PointSource Table ...108

5.3.13 Monitor Interface Performance...108

5.3.14 Configure the PI Interface Status Utility ...112

5.3.15 Configure Auto Point Synchronization...113

Chapter 6. Managing Security ...115

6.1 Physical Security...115

6.2 Network Security ...115

6.3 Operating System Security...116

6.4 PI Server Security...116

6.4.1 Running applications on the system console ...117

6.4.2 Running applications remotely ...117

6.5 Firewall Security ...117 6.5.1 Firewall Database...118 6.6 Database Security ...120 6.6.1 PIDBSEC...120 6.6.2 PIARCADMIN ...120 6.6.3 PIARCDATA ...121 6.6.4 PIBatch ...121 6.6.5 PICampaign...121

(13)

Table of Contents 6.6.6 PIDS ...121 6.6.7 PIHeadingSets...121 6.6.8 PIModules...121 6.6.9 PIPOINT ...121 6.6.10 PITransferRecords ...121 6.6.11 PIUSER ...121

6.6.12 Individual Subsystem Tokens...121

6.7 Point Security...122

6.7.1 Point Data Access ...122

6.7.2 Point Attribute Access ...122

6.7.3 Access Algorithm...122

6.7.4 Assigning and Changing Ownership and Access Permissions...123

6.7.5 How to Make All Points Accessible ...124

6.7.6 Security for Default Points in the PI Server ...125

6.8 User Security ...125

6.8.1 Group Database ...125

6.8.2 User Database...126

6.9 Trust Login Security...128

6.9.1 Connection Credentials ...128

6.9.2 Defining Trust Records in the Trust Database ...130

6.9.3 Evaluating the Match Between Trust Records and Connection Credentials ...134

6.9.4 New PI Server Installations ...136

6.9.5 Trust changes on System Startup ...136

6.9.6 Multiple Network Cards ...136

6.9.7 Examples...137

6.10 Resolving Ambiguities...144

Chapter 7. Moving PI Servers ...147

7.1 Preparation...147

7.2 Different Computer...147

7.3 Same Computer ...148

Chapter 8. Copying a PI Server ...151

8.1 Understanding the Server ID ...151

8.2 Situations where Server ID must be Addressed ...151

Chapter 9. Merging Two PI Servers ...153

(14)

9.2 Server Merge Procedure - Example...156

9.3 Shut Down the Retired System ...163

9.3.1 Add Retired Point Configuration to Destination System...164

9.3.2 Add PI Batch Unit Configuration to Destination System ...165

9.3.3 Convert the Archives ...165

9.3.4 Merge the PI Batches ...169

Chapter 10. The piconfig Utility...171

10.1 PI TagConfigurator & PI SMT Point Builder plug-in...171

10.2 A Note to Pidiff Users...171

10.3 Key Concepts for Using Piconfig ...172

10.3.1 Starting and Stopping Piconfig ...172

10.3.2 Interactive Session vs. Batch Method ...172

10.3.3 Selecting PI Tables...172 10.3.4 Table Attributes ...174 10.3.5 Records ...175 10.3.6 Piconfig Commands ...176 10.3.7 Mode...178 10.3.8 Structure Type ...179 10.3.9 Select Command ...181 10.3.10Operators...181 10.3.11Wildcards...182

10.3.12The Ellipsis (…) Construct for Repeating Attributes...182

10.3.13Endsection...182

10.3.14Exit...183

10.3.15Batch Methods...183

10.3.16Security on Piconfig Sessions ...185

10.3.17Remote Piconfig Sessions...185

10.4 Piconfig Commands and Tables...186

10.4.1 Point Database Table ...188

10.4.2 PI Attribute Set Table ...191

10.4.3 Point Class Database ...192

10.4.4 Point Source Database...194

10.4.5 Digital States Table ...195

10.4.6 Snapshot and Snapshot2 Tables ...200

10.4.7 Archive Table...202

(15)

Table of Contents

10.4.9 PI Batch Alias Table ...208

10.4.10PI Batch Table ...209

10.4.11PI Subsystem Table ...210

10.4.12PI Subsystem Statistics Table...211

10.4.13PINet Manager Statistics Table...212

10.4.14PI Users Table...214

10.4.15PI Group Table ...215

10.4.16PI Thread Table...215

10.4.17PI Database Security Table...216

10.4.18PI Trust Database...218

10.4.19PI General Table Interface ...219

10.5 Helpful Hints...220

10.5.1 Abbreviations...220

10.5.2 Case-sensitivity ...220

10.5.3 Command Input Files ...220

10.5.4 Input Line Length...220

10.5.5 Using Quoted Strings ...221

10.5.6 Sending Values as Strings ...222

10.5.7 Boolean Values ...222

10.5.8 Configuration Persistence ...223

10.5.9 Command Line Parameters...223

10.5.10Changing Special Characters...223

10.5.11Convert Mode Example ...224

10.5.12Converting Point Database Information from PI2 to PI Server...224

10.5.13Hexadecimal and Octal Numbers...224

Chapter 11. PI Troubleshooting and Repair...225

11.1 Troubleshooting Checklist ...225

11.2 Verifying PI Processes...228

11.2.1 Verifying PI Processes on Windows Systems...228

11.2.2 Verifying PI Processes on UNIX Systems...228

11.2.3 Communication with PINet Manager...229

11.2.4 Pimsgss ...229

11.2.5 PI Update Manager ...230

11.2.6 PI Base Subsystem ...230

11.2.7 Snapshot Subsystem...230

(16)

11.2.9 Pishutev...231

11.2.10Random Interface ...232

11.2.11RampSoak Interface...232

11.2.12Running PI Processes Independently ...232

11.3 UNIX Process Quotas...233

11.3.1 IBM AIX...234

11.3.2 Compaq Tru64...234

11.3.3 HP-UX...235

11.3.4 Sun Solaris ...235

11.4 PI Server Data Files ...235

11.5 Identifying the Update Manager Issues: the pilistupd utility ...238

11.6 Repairs...241

11.6.1 Recovering Data from Corrupted Archives...241

11.6.2 Restoring a Complete Server from Backup...243

11.6.3 Restoring Archives From Backup...244

11.6.4 Restoring Subsystem Databases From Backup...245

11.6.5 Correcting Archive Event Timestamps ...245

11.6.6 Repairing the Archive Registry...246

11.6.7 How to Repair the Snapshot...247

11.6.8 Recovering from Accidental Change to System Time...249

11.6.9 How to Repair the Point Database ...250

11.6.10How to Repair the Module Database ...250

11.7 Tuning the PI Server...251

11.7.1 Communications Layer of the PI Server...251

11.7.2 Resolving Excessive CPU Usage by Utilities ...252

11.7.3 Identifying Abusive Usage...253

11.8 Solving Other Problems...254

11.8.1 Failed Backups ...254

11.8.2 Slow Reverse Name Lookup...254

11.8.3 Slow Domain Controller Access ...255

11.8.4 Flatline in a PI ProcessBook Trend ...255

11.9 COM Connectors ...257

11.9.1 Redirector Troubleshooting ...257

11.9.2 COM Connector Troubleshooting...261

Chapter 12. Finding and Fixing Problems: the pidiag Utility ...263

(17)

Table of Contents

12.1.1 Version Information ...265

12.1.2 Error Code Translation ...265

12.2 Time Utilities ...265

12.2.1 Time Translations ...265

12.2.2 Time Zone ...266

12.3 File-base Utilities ...269

12.3.1 Dump File-base Data File...269

12.3.2 Compact a File-base Data File...269

12.3.3 Recover File-base Data File Index ...270

12.4 Archive Management ...270

12.4.1 Dump the Archive Manager Data File ...270

12.4.2 Automatic Recovery of the Archive Manager Data File ...270

12.4.3 Manual Recovery of the Archive Manager Data File...271

12.4.4 Information about Unregistered Archives ...271

12.4.5 Verify the Integrity of Archive Files...272

12.4.6 Downgrade Archive File to Older Versions ...274

12.5 Server ID Utilities...275

12.6 Performance Counter Utilities (Windows Only) ...276

12.6.1 Get Performance Counter Path...276

12.6.2 Uninstall Performance Counters ...276

12.6.3 Get Performance Counter Values ...276

12.7 Miscellaneous ...278

12.7.1 Wait for Passed Milliseconds...278

12.7.2 Testing Crash Dump Capability of an OS ...278

12.7.3 Reset Password to Blank ...278

12.7.4 Display Network Definitions...278

12.7.5 Register a COM Component ...279

12.7.6 Replaceable Parameter...279

12.7.7 GUID Generation...280

12.7.8 Machine-specific Programming Information ...280

Appendix A: PI Messages ...281

Appendix B: PI Performance Counters ...331

Technical Support and Resources...345

(18)

(19)

T

ABLE OF

T

ABLES

Table 3–1. Options for Use with piartool ...37

Table 10–1. PI Tables Accessible Through piconfig...172

Table 10–2. Piconfig Commands ...186

Table 10–3. Snapshot and Snapshot2 Tables Attributes ...200

Table 10–4. Archive Table Attributes ...202

Table 10–5. PI Batch Unit Table Attributes...207

Table 10–6. PI Batch Alias Table Attributes ...209

Table 10–7. PI Batch Table Attributes ...209

Table 10–8. Subsystem Table Attributes ...210

Table 10–9. PI Subsystem Statistics Table Attributes ...211

Table 10–10. PINet Manager Statistics Table Attributes ...212

Table 10–11. PI Users Table Attributes ...214

Table 10–12. PI Group Table Attributes ...215

Table 10–13. PI Thread Table Attributes ...215

Table 10–14. PI Thread Table Actions ...216

Table 10–15. PI Database Security Table Attributes ...216

Table 10–16. Trust Table Attributes...218

Table 10–17. PI Timeout Table Attributes ...219

Table 10–18. PI Firewall Table Attributes ...219

Table A–1. Error Codes 1-99, With Messages ...294

(20)

Table A–12. Error Codes15000-15999, With Messages ...321

(21)

T

ABLE OF

F

IGURES

Figure 6-1. Establishing PI Performance Monitor as a Windows Service...134

Figure 11-1. Distributed COM Configuration Properties ...258

Figure 11-2. Windows Task Manager Processes ...259

Figure 11-3. Application Log Properties...260

(22)

(23)

Chapter 1.

S

TARTING AND

S

TOPPING

PI

The PI Server includes several separate processes that participate in startup and shutdown. These are referred to as PI processes or PI subsystems. This section describes the relationship between the processes, and the startup and shutdown scripts used to control them.

PI should only be started or stopped by the PI System manager. It is important to remember that stopping PI affects all client applications, performance equation calculations, and the archiving of data.

PI Server startup is performed with a pair of scripts: a generic PI startup script starts all PI processes, which then calls a site-specific script to start interfaces and other site specific programs. The system manager should modify only the site-specific script since the generic startup script may be replaced during a PI Server upgrade. The actual file names of these scripts vary with the operating system. Platform-specific details are provided in the following subsections.

In general, the PI Server shutdown scripts are similar: a generic PI shutdown script calls a site-specific script to shut down interfaces and site specific programs, and then shuts down all PI processes.

Note: The only exception to this is shutting down PI processes running as individual

command windows. In this case, you must bring each window in focus and type <CTRL-C>. Running PI subsystems in command windows is very rare; and usually only encountered in troubleshooting scenarios.

It is important to configure Shutdown Events. Generally, points collected by interfaces running on the PI Server node should be configured for shutdown events; points collected on remote, buffered nodes usually are not configured for shutdown events. See Stopping PI on page 3.

Production systems are usually configured so that PI is automatically started when the computer is powered on. See Automatic Startup on page 6 for more information.

1.1 Starting

PI

The PI Subsystems may take several minutes to start. Remote or PI API based interfaces and other applications are blocked from connecting until the core PI Subsystems have completed startup. The connection blocking is accomplished by opening the TCP/IP listener when the core subsystems are ready to service requests. The following message is posted to the PI

(24)

>> TCP/IP connection listener opened on port: 5450

Connection attempts before the listener is opened will fail. Interfaces will retry until a connection is made.

1.1.1 Starting PI on Windows Systems

On Windows systems, the Manager can be logged into any account that allows full access to the PI Server files and enough privileges to start services. To start PI, change to the PI\adm directory.

PI normally runs as Windows services. For diagnostic purposes, you can also start PI in interactive mode.

Starting PI as Windows Services

To start PI as Windows services:

1. Log in to a Windows account that has full access to the PI Server files, and permission to start PI services

2. Open a Windows Command Prompt window. 3. Change to the PI\adm directory.

4. Use the pisrvstart.bat script to start PI as Windows services:

pisrvstart.bat [-nosite] [-base]

Nosite is an optional parameter to indicate that the site-specific script file should not be called. This results in the interfaces not being started.

Base starts only the core subsystems and is used for troubleshooting.

The pisrvstart.bat script starts all the PI Server processes, and then calls pisrvsvrappsstart.bat if PI Server Applications are installed. Then, it calls pisrvsitestart.bat to start all of the interfaces.

Starting PI in Interactive Mode

To start PI in interactive mode:

pistart.bat [-nosite] [-stdout] [-base]

The pistart.bat script calls pisitestart.bat.

Nosite is an optional parameter to indicate that the site-specific script file should not be called. This results in the interfaces not being started.

Stdout is an optional parameter to indicate that all messages for the processes should be sent to the standard output instead of to the message log. When you use this parameter, the PI Message Subsystem is not started.

The error Control service unknown error 5 opening Service Control Manager is returned if the PI startup is attempted by a user without enough privileges.

(25)

1.2 - Stopping PI

Some interfaces on Windows cannot be run as services. Check the interface documentation.

1.1.2 Starting PI on UNIX Systems

On UNIX systems the manager should be logged in as root or piadmin. For a UNIX system, type:

pistart.sh [-nosite] [-stdout] [-base] [M]

This starts all the PI Server processes, calls piappstart.sh if Server applications are installed, and then calls the interfaces and programs that are listed in the site-specific script file,

pisitestart.sh.

Nosite is an optional parameter for pistart used to indicate that the site-specific script file should not be called. This results in the interfaces not being started.

Stdout is an optional parameter to indicate that all messages for the processes should be sent to the standard output instead of the Message Log. When you use this parameter, the PI Message Subsystem is not started.

M starts only PI Network Manager, PI License Manager, and the PI Message Subsystem.

1.2 Stopping

PI

The procedure for stopping PI is slightly different, depending on whether you’re running on Windows or UNIX.

1.2.1 Stopping PI on Windows Systems

To stop PI on a Windows system, if PI processes are running as Windows services, type:

pisrvstop.bat

This stops all of the interfaces and programs listed in pisrvsitestop.bat, and then the PI processes. PI services are shut down automatically when you shut down your system. The order of the shutdown in this case is determined by the operating system.

Windows has a registry entry that defines the maximum wait for a service to exit. On PI Systems with large point counts, the maximum wait time may need to be increased to allow PI enough time to shut down properly. The PI installation procedure increases the default value of 20,000 milliseconds to 300,000 milliseconds, or 5 minutes. This is generally enough time for proper shutdown on systems with fewer than 50,000 points. Larger systems may require more time. This can be determined by manually stopping the PI Server using

pisrvstop.bat and record the time to shutdown. If it is longer than 5 minutes, the registry

entry:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WaitToKillServiceTimeout

should be set to reflect the actual shutdown time. Failing to allow proper shutdown of the PI Server can result in lost data or corrupted data files.

(26)

To shut down an interactively started PI Server, type <CTRL-C> in each of the command windows corresponding to the PI processes. These should be stopped in the following order:

Utilities (for example, piconfig)

Interfaces (for example, Ramp Soak and Random)

pinetmgr (When you instruct pinetmgr to stop, the remaining processes are told to exit in the proper order and, finally, pinetmgr will stop.)

1.2.2 Stopping PI on UNIX Systems

To stop PI on a UNIX system, change to the PI/adm directory and type:

pistop.sh

This stops all the interfaces and programs that are listed in the site-specific script file

pisitestop.sh. Then it stops all the PI processes.

If some processes do not stop successfully, run the pistop.sh script again. If you still have problems stopping the individual programs, use the UNIX kill command.

Distributed systems use PINet and Interface Nodes as data source machines. Normally these systems buffer data if the PI Server is not available. The buffered data is sent to the PI Server when it becomes available.

There are a few instances in which data is not buffered when the home node is down. Examples include cases where an interface is loaded on the PI Server machine and the PI Server is shut down or where the data is generated locally with performance equations. In these cases, you may wish to record intervals when the PI Server on the home node was shut down. This is accomplished by inserting a shutdown event.

A shutdown event is a timestamp and a digital state, typically shutdown, which are written to one or more points. The digital state prevents the interpolation of data over periods with possible missing data, and also records system status, providing a clear indication of a gap in the data.

The PI Server provides a utility, pishutev, to insert shutdown events for points that are configured to receive them. The pishutev utility uses a configuration file, shutdown.dat, to determine which points should receive events.

Note: Interfaces may also be configured to record instances when no data is

received from an interface.

Shutdown Flag

The shutdown point attribute in the point database is set to TRUE (1) by default. If the shutdown attribute for a point is set to TRUE, the point is able to receive shutdown events if the shutdown.dat file targets the point.

(27)

1.2 - Stopping PI

pishutev

Shutdown events are written at system startup by the pishutev interface. The utility reads a configuration file to determine which tags should receive shutdown events. It also supplies a configurable timestamp for the PI Server shutdown. Unlike most PI processes, pishutev exits after completion.

The startup command line for pishutev is located in the PI startup files PI/adm/pistart.sh (UNIX), PI\adm\pistart.bat and PI\adm\pisrvstart.bat.

By default, the configuration file is PI\dat\shutdown.dat. It is sometimes useful to create additional shutdown configuration file(s) with additional point selections. These files are processed by starting another instance of the interface. The new shutdown configuration file name is passed as a parameter using the -f flag in the pishutev command line: For example:

pishutev -f myshutdown.dat

This command line should be added to the PI site-specific startup files PI/adm/pisitestart.sh (UNIX) and PI\adm\pisitestart.bat. Starting a second instance of pishutev in order to process an additional shutdown configuration file is not supported when starting PI as Windows services.

By default, pishutev determines the shutdown event timestamp from a file written by the Snapshot Subsystem. This file is updated whenever the Snapshot is flashed to disk, usually every 10 minutes. Hence, in the event of a power failure, the timestamp of the shutdown event are accurate to within 10 minutes. When PI is shut down normally, the timestamps are the actual shutdown time. If the file that is written by the Snapshot Subsystem is missing, the shutdown events interface uses the current time to timestamp the shutdown events.

The default time may be overridden by a user-specified time using the -t flag and passing the time as a parameter in the command line.

For example:

pishutev -t 11:00

By default, the digital state of shutdown is written for each shutdown event.

To write a digital state other than shutdown, use the -s flag and pass the digital state as a parameter in the command line. The specified state must already be configured in the System Digital State Set in the Digital State Table. For example:

pishutev -s SpecialState

The -f, -t, and -s flags may be used in any combination.

Shutdown.dat

The points receiving shutdown events are specified using the file PI\dat\shutdown.dat. The PI Server is delivered with a shutdown.dat file that selects all points whose shutdown flag is TRUE. This file is shown below. You may wish to edit the file to restrict shutdown events to certain groups of tags.

! @(#)shutdown.dat 1.1 05/24/96 ! default shutdown events file

(28)

! login info - only localhost is supported localhost

! tag mask *

! attrib selection

! add here point attributes,value to select points receiving shutdown shutdown,1

! pointsource,R* ! location1, 1 ! etc...

To specify more than one tag name use a tag mask. The tag mask may contain the wildcards * and ?. The symbol * matches all possibilities with any number of characters. The symbol ? matches a single character and may be used any number of times.

Caution: Do not specify additional tags by appending comma separated tag masks

or by using additional lines. Only one tag mask may be specified.

If you do not specify a tag-mask, the interface exists with an error. To prevent all shutdown events, specify a tag mask that does not match any tag.

Other point attributes and values may be used in addition to or instead of the shutdown flag. These conditions are logically ANDed together.

For example, the following configuration file selects only tags that start with s, have the location1 attribute set to 0, and Pointsource set to H. No other tags will receive shutdown events. ! tag mask s* ! point attributes location1,0 pointsource,H

If no point attributes are specified, all tags specified by the tag mask are selected to receive shutdown events.

Caution: The Shutev process is used to execute post installation procedures;

therefore the Shutev process should not be disabled or removed from the normal startup procedures. The shutdown.dat file, or point shutdown attribute should be used to prevent writing shutdown events.

1.3 Automatic

Startup

The procedure to configure PI for automatic startup depends on the operating system. PI Server on Windows is normally run as a collection of services. The installation procedure provides a dialog to optionally set automatic startup on reboot. The reboot startup behavior of PI can also be set using the Control Panel Services applet.

(29)

1.3 - Automatic Startup

1.3.1 Automatic Startup and Shutdown on UNIX Systems

Shutdown and startup for UNIX systems varies with platform, but there are generally two varieties: BSD style systems use one file, /etc/inittab, which specifies what scripts to run in each run level, while System V flavors of UNIX use scripts which reside in a set of

directories called rcn.d, where n is an number ranging from 0 on up. Usually these

subdirectories are in the /etc directory, but can be in others (HP-UX 10 has them under /sbin, for example). Here, we're going to give examples of how to configure each of the systems we support.

No matter which UNIX platform you're using, if you want to have PI automatically start up when the system boots or reboots, and shut down when the system shuts down, you MUST ensure that the .profile or .login file for piadmin does not require interaction with a terminal. This means that if you use, for example, tset to set the TERM variable, you must first check to see if there is a terminal attached to the current process. One way to do this is:

if tty -s ; then tset .... fi

Automatic Startup/Shutdown for Solaris 2.x

Solaris recognizes numerous run levels: Run Level Purpose

s or S single user (used for administering the system) 2 standard level, non-networked

3 default level

4 standard level, user-defined

Which processes run at each level is determined by a set of scripts, /etc/rcS through /etc/rc6. These scripts look in the directories /etc/rc#.d (where # = 0, 2, 3, etc.) for scripts that begin with a K or an S. The K scripts are used to kill processes, and the S scripts are used to start processes. When the system moves from level 3 to level 2, the K scripts in /etc/rc2.d are executed first, then the S scripts. The scripts are run in ASCII collated sequence, so K02stop is run before K04metoo. On shutdown or reboot, the system runs the scripts in /etc/rc0.d. If you are using the default run level, you will need to put the PI startup in /etc/rc3.d. The shutdown script for PI needs to be in /etc/rc2.d, so PI will be shut down if the system goes to non-networked mode, and also in /etc/rc0.d, so PI will be shut down if the system is halted or rebooted.

Note: Solaris systems should be restarted using shutdown -i 6. This will cause the

shutdown scripts to be run before running reboot. The reboot command simply restarts the kernel, without taking the time to shut down processes properly. The command shutdown -i 5 is for powering down.

Script files are actually kept in /etc/init.d, with links placed in the /etc/rc#.d directories. So, in

/etc/init.d, you need to create the following three files: PI, PIstart and PIstop. Be sure to

(30)

#!/bin/ksh #

# Filename: /etc/init.d/PI #

# become piadmin to start/stop PI PATH=/sbin:/usr/sbin:/usr/bin export PATH

case "$1" in 'start')

if [ -f /etc/init.d/PIstart ] ; then

su - piadmin -c "/etc/init.d/PIstart" > /dev/console 2>&1 fi

;; 'stop')

if [ -f /etc/init.d/PIstop ] ; then

su - piadmin -c "/etc/init.d/PIstop" > /dev/console 2>&1 fi

;; *)

echo "usage: $0 {start|stop}" ;;

esac #!/bin/ksh #

# Filename: /etc/init.d/PIstart

# Make sure to set the directory in these # files to your PIHOME directory, in all # places # if [ -f /opt/pi/adm/pistart.sh ] ; then cd /opt/pi/adm nohup ksh pistart.sh fi #!/bin/ksh # # Filename: /etc/init.d/PIstop

# Make sure to set the directory in these # files to your PIHOME directory, in all # places # if [ -f /opt/pi/adm/pistop.sh ] ; then cd /opt/pi/adm ksh pistop.sh fi

Next, set the owner, group, and permissions on these files to match the other files in this directory:

root> chgrp sys /etc/init.d/PI* root> chmod 755 /etc/init.d/PI*

(31)

Then, you'll need to set the links in the rc#.d directories. Make sure that the S## number on the startup file is higher than the S## number for inetd, and that the K## number for the kill file is lower than the K## number for inetd (in both directories).

root> ln -s /etc/init.d/PI /etc/rc3.d/S96PI root> ln -s /etc/init.d/PI /etc/rc2.d/K04PI root> ln -s /etc/init.d/PI /etc/rc0.d/K04PI

Verify that these files have the same owner, group, and permissions as other startup files in those directories.

Finally, test your scripts before you restart your machine. To stop PI:

root> sh /etc/rc0.d/K04PI stop

Verify that PI processes shut down.

root> sh /etc/rc3.d/S96PI start

Verify that PI starts properly.

If there is any problem with stopping or restarting PI, remove the links in the /etc/rc#.d directories until you've debugged and fixed the problems. The files in the /etc/init.d directory will not affect your system as long as there are not links in the /etc/rc#.d directories.

Automatic Startup/Shutdown for HP-UX 10

HP-UX 10 recognizes numerous run levels: Run Level Purpose

s or S Single user (used for administering the system)

1 – 6 standard levels (1 is single-user, 2 is default, 3 and up are user-defined)

Which processes run at each level is determined by the /sbin/rc script. This script looks in the directories /sbin/rc#.d (where # = 1, 2, 3, etc.) for scripts that begin with a "K" or an "S". The "K" scripts are used to kill processes, and the "S" scripts are used to start processes. When moving down from a higher level to a lower level, all "K" scripts in all the intervening levels are run. When moving up to a higher level, all "S" scripts in all intervening levels are run. So when the system moves from level 4 to level 2, the "K" scripts in /sbin/rc3.d are executed, then the "K" scripts in /sbin/rc2.d. The scripts are run in ASCII collated sequence, so

K002stop is run before K004metoo.

If you are using the default run level of 2, you must put the PI startup in /sbin/rc3.d. The shutdown script for PI needs to be in /sbin/rc%.d, where % is the default run level, minus 1, so PI will be shut down if the system goes out of the default run level to any other level, or if the system is halted or rebooted. To determine your default run level, check the line in

/etc/inittab that reads "init:#:initdefault:." The # is the default run level for the system.

Script files are actually kept in /sbin/init.d, with links placed in the /sbin/rc#.d directories. So, in /sbin/init.d, you need to create the following three files: PI, PIstart and PIstop. Be sure to change the lines that specify where to find PI on your system.

(32)

#

# Filename: /sbin/init.d/PI #

if [ -f /sbin/init.d/PIstart ] ; then

su - piadmin -c "/sbin/init.d/PIstart" > /dev/console 2>&1 fi

;; 'stop')

if [ -f /sbin/init.d/PIstop ] ; then

su - piadmin -c "/sbin/init.d/PIstop" > /dev/console 2>&1 fi

;; 'start_msg')

echo "Starting PI" ;;

'stop_msg')

echo "Shutting down PI, please wait" ;;

*)

esac #!/bin/ksh #

# Filename: /sbin/init.d/PIstart

# Make sure to set the directory in these # files to your PIHOME directory, in all # places # if [ -f /opt/pi/adm/pistart.sh ] ; then cd /opt/pi/adm nohup ksh pistart.sh fi #!/bin/ksh # # Filename: /sbin/init.d/PIstop

# Make sure to set the directory in these # files to your PIHOME directory, in all # places # if [ -f /opt/pi/adm/pistop.sh ] ; then cd /opt/pi/adm ksh pistop.sh fi

Next, set the owner, group, and permissions on these files to match the other files in this directory:

(33)

root> chgrp sys /sbin/init.d/PI* root> chmod 755 /sbin/init.d/PI*

Then, you'll need to set the links in the rc#.d directories. Make sure the S### number on the startup file is higher than the S### number for inetd, and the K### number for the kill file is lower than the K### number for inetd (in both directories). Note that HP-UX uses three digits in the link file names as opposed to the two digits used by other varieties of UNIX. Here, run level 3 is our default run level, so we're putting the start script in /sbin/rc3.d, and the kill script in /sbin/rc2.d:

root> ln -s /sbin/init.d/PI /sbin/rc3.d/S960PI root> ln -s /sbin/init.d/PI /sbin/rc2.d/K004PI

root> sh /sbin/rc2.d/K004PI stop

root> sh /sbin/rc3.d/S960PI start

If there is any problem with stopping or restarting PI, remove the links in the /sbin/rc#.d directories until you've debugged and fixed the problems. The files in the /sbin/init.d directory will not affect your system as long as there are no links in the /sbin/rc#.d directories.

Automatic Startup/Shutdown for PI on Compaq Tru64 and Tru64 UNIX 4.0x

This operating system was originally known as DEC UNIX. Compaq Tru64 UNIX recognizes four run levels:

Run Level Purpose

0 shutting down

s single user (used for administering the system)

2 local (non-networked)

3 default, networked

Which processes run at each level is determined by a set of scripts, /sbin/rc0, /sbin/rc2, and

/sbin/rc3. These scripts look in the directories /sbin/rc#.d (where # = 0, 2, 3) for scripts that

begin with a "K" or an "S". The "K" scripts are used to kill processes, and the "S" scripts are used to start processes. When the system moves from level 3 to level 2, the "K" scripts in

/sbin/rc3.d are executed first if the system is not coming from single-user mode, then the "S"

scripts are run (remember the system goes to single-user on boot, then goes to the default run level). The scripts are run in ASCII collated sequence, so K02stop is run before K04metoo. On shutdown or reboot, the system will run the scripts in /sbin/rc0.d.

(34)

You should put the PI startup in /sbin/rc3.d. The shutdown script for PI must be in

/sbin/rc2.d, so PI will be shut down if the system goes to non-networked mode, and also in /sbin/rc0.d, so PI will be shut down if the system is halted or rebooted.

Note: Compaq Tru64 systems should be restarted using shutdown to go to

single-user mode, then shutdown -r to reboot or shutdown -h to halt. This will cause the shutdown scripts to be run. Using shutdown -r or shutdown -h from run level 3 or 2 will bypass the scripts and simply kill all processes, without taking the time to shut down processes properly.

Script files are actually kept in /sbin/init.d, with links placed in the /sbin/rc#.d directories. So, in /sbin/init.d, you need to create the following three files: PI, PIstart and PIstop. Be sure to change the lines that specify where to find PI on your system.

#!/bin/ksh #

# Filename: /sbin/init.d/PI #

if [ -f /sbin/init.d/PIstart ] ; then

su - piadmin -c "/sbin/init.d/PIstart" > /dev/console 2>&1 fi

;; 'stop')

if [ -f /sbin/init.d/PIstop ] ; then

su - piadmin -c "/sbin/init.d/PIstop" > /dev/console 2>&1 fi

;; *)

esac #!/bin/ksh #

# Filename: /sbin/init.d/PIstart

# Make sure to set the directory in these # files to your PIHOME directory, in all # places # if [ -f /opt/pi/adm/pistart.sh ] ; then cd /opt/pi/adm nohup ksh pistart.sh fi #!/bin/ksh # # Filename: /sbin/init.d/PIstop

(35)

# files to your PIHOME directory, in all # places # if [ -f /opt/pi/adm/pistop.sh ] ; then cd /opt/pi/adm ksh pistop.sh fi

Next, set the owner, group, and permissions on these files to match the other files in this directory (check the setting on your system):

root> chown bin /sbin/init.d/PI* root> chgrp bin /sbin/init.d/PI* root> chmod 755 /sbin/init.d/PI*

Then, you'll need to set the links in the rc#.d directories. Make sure that the S## number on the startup file is higher than the S## number for inet, and that the K## number for the kill file is lower than the K## number for inet (in both directories).

root> ln -s /sbin/init.d/PI /sbin/rc3.d/S96PI root> ln -s /sbin/init.d/PI /sbin/rc2.d/K04PI root> ln -s /sbin/init.d/PI /sbin/rc0.d/K04PI

root> sh /sbin/rc2.d/K04PI stop

root> sh /sbin/rc3.d/S96PI start

If there is any problem with stopping or restarting PI, remove the links in the /sbin/rc#.d directories until you've debugged and fixed the problems. The files in the /sbin/init.d directory will not affect your system as long as there are no links in the /sbin/rc#.d directories.

Automatic Startup/Shutdown for IBM AIX

IBM AIX recognizes numerous run levels: Run Level Purpose

s (S) or m (M) Single user (used for administering the system) 2 default multi-user run level

3 - 9 user defined levels

The system determines what processes should run at each level by reading the /etc/inittab file. The lines in this file tell the system what scripts to run at what run levels. The line with the initdefault in it (init:#:initdefault:, where # is some number 2-9) tells the system the default

(36)

run level. Each line with this number after the first colon is executed when entering the default run level. Thus, we need to add a line to the /etc/inittab file:

pisystem:2:once:su - piadmin -c /etc/rc.pistart > /dev/console 2>&1 # Start PI

Caution: Before editing /etc/inittab, you must save the original under another name. If you do not and make an error while editing, your system will not boot.

If your initdefault level is not 2, you should replace the 2 with the appropriate number from initdefault.

For shutdown and reboot, the system uses the /etc/rc.shutdown script. If this file does not exist, you should create it. Otherwise, just add the last line below to your current file. If you have to create the /etc/rc.shutdown file, you should give it the same owner, group, and permissions as the /etc/rc file. As before, you are strongly advised to save a copy of the original file under another name before editing this file.

#! /bin/ksh #

# Filename: /etc/rc.shutdown #

su - piadmin -c "/etc/rc.pistop" > /dev/console 2>&1

Now you'll have to create these two files you've told the system to use, /etc/rc.pistart and

/etc/rc.pistop. Be sure to change the directory in these files to the PI Server directory on your

system. #!/bin/ksh # # Filename: /etc/rc.pistart # if [ -f /usr/PI/adm/pistart.sh ] ; then cd /usr/PI/adm nohup ksh pistart.sh fi #!/bin/ksh # # Filename: /etc/rc.pistop # if [ -f /usr/PI/adm/pistop.sh ] ; then cd /usr/PI/adm ksh pistop.sh fi

You'll need to change the permissions on these files so that piadmin can run them:

root> chmod 755 /etc/rc.pi*

root> su - piadmin -c "/etc/rc.pistop" > /dev/console 2>&1

(37)

root> su - piadmin -c /etc/rc.pistart > /dev/console 2>&1

If there is any problem with stopping or restarting PI, you'll need to restore the previous versions of /etc/inittab and /etc/rc.shutdown until you can find and fix the problem.

Automatic Startup/Shutdown for HP-UX 9

PI Server is no longer supported on HP-UX Version 9.x. The information in this section is provided as a reference in case you are still running a previous version of PI. You should be aware that Hewlett-Packard no longer supports HP-UX 9.x and recommends upgrading. HP-UX 9 uses the /etc/rc file to control system startup. An individual site may also have additional scripts specified in the /etc/inittab file, to stop and start processes when moving from one run level to another. If so, the PI System Manager needs to determine which run levels should have PI running and which should not, and should put suitable entries in the scripts to stop and start PI when moving from one run level to another. Here, we'll just deal with the basic system, which uses only the standard /etc/rc file.

Caution: Before editing /etc/rc, save the original under another name. If an error is made while editing, the system will not boot.

In /etc/rc, there is a section intended for use by the local PI System Manager, "localrc()". In this section, add the following lines (be sure to add them before vuelogin, if you have it):

#

# start PI #

su - piadmin -c /etc/rc.pistart > /dev/console 2>&1

There's another directory, /etc/shutdown.d, which has the shutdown scripts for applications on the system. This directory may be empty.

In any case, you should create a file, /etc/shutdown.d/PIstop, that looks like this:

#! /bin/ksh #

# Filename: /etc/shutdown.d/PIstop # Stop PI gracefully

su - piadmin -c "/etc/rc.pistop" > /dev/console 2>&1

This file should have the same owner, group, and permissions as the /etc/rc file. For our systems, that means running these commands:

root> chown bin /etc/shutdown.d/PIstop root> chgrp bin /etc/shutdown.d/PIstop root> chmod 555 /etc/shutdown.d/PIstop

Next create the two files in /etc. Make sure you set the directories in these files to point to your PI Server directory.

#!/bin/ksh #

(38)

# if [ -f /export/PI/adm/pistart.sh ] ; then cd /export/PI/adm nohup ksh pistart.sh fi #!/bin/ksh # # Filename: /etc/rc.pistop # if [ -f /export/PI/adm/pistop.sh ] ; then cd /export/PI/adm ksh pistop.sh fi

Again, you need to set the owner, group, and permissions:

root> chown bin /etc/rc.pi* root> chgrp bin /etc/rc.pi* root> chmod 555 /etc/rc.pi*

Then test these scripts before restarting your machine.

root> sh /etc/shutdown.d/PIstop

Verify that PI shuts down.

root> su - piadmin -c "/etc/rc.pistart" > /dev/console 2>&1

Verify that PI starts up properly.

If there is any problem with stopping or restarting PI, you will need to restore your original

/etc/rc file, and remove the new file from the /etc/shutdown.d directory.

1.4 Shutting Down an Individual Subsystem

Shutting down an individual subsystem depends on the operating system. On Windows, look in the file adm\pisrvstop.bat for the shutdown procedure; on UNIX, adm/pistop.sh. For restart procedure check adm\pisrvstart.bat and adm/pistart.sh onWindows and UNIX, respectively.

(39)

Chapter 2.

M

ONITORING

PI

S

YSTEM

H

EALTH

2.1 Checking Key System Indicators

Each day, check the key elements of your PI System to make sure PI is working efficiently and correctly. By checking the PI System daily, you can catch problems quickly and you also familiarize yourself with the normal state of the system. This makes it easier to interpret system metrics (such as I/O rates) and to find abnormal messages, when they occur.

Area What to check Tools

Backups Have PI System backups been run? piartool -al Message Log Check the System Message Log to see

whether unusual events have occurred.

pigetmsg

Update Manager Are the clients connecting to the PI Server normally?

pilistupd

Tag Data Does the Archive data for a reference tag look normal?

pisnap.bat or pisnap.sh

Snapshot data flow

Is the Snapshot data flow normal? piartool -ss

Archive data flow Is the Archive data flow normal? piartool -as and piartool -qs Archive Shift Verify that the expected archives are

registered and that you have prepared for the next archive shift.

piartool -al

Interface Logs Check the interface logs to see whether unusual events have occurred.

IO Rate Counters

Interfaces support writing snapshot rates to PI Points. The IO rate values and timestamps are a good indicator of interface health.

PI Datalink or PI ProcessBook to view or trend the IO rate points.

Performance Counters (Windows)

All Subsystems publish key performance counters to Windows. Subsystem counters are discussed in this chapter.

Windows Performance Monitor. PI Performance Monitor Interface.

License limits

and usage Check the usage statistics and point counts for your system. Anticipate license increase needs.

(40)

2.2 Viewing System Messages

During normal operation, the PI Message Subsystem maintains a central log file for messages from all PI subsystems. PI creates a new log every day, on universal time coordinate (UTC) time. PI puts the log files in the PI\log directory and names each log according to the date. The file names are of the form, pimsg_YYMMDD.dat, where:

YYY is years since 1900 (for example,if the year is 2000, YY is 100)

MM is the month (for example, if the month is January, MM is 01)

DD is the day (for example, if it is the fifth of the month, DD is 05) For example, the log file for January 5, 2000 is named pimsg_1000105.dat.

PI Message log files are binary files that you can view using the pigetmsg utility.The pigetmsg utility lets you view messages according to time, subsystem, or sender’s identity. The pigetmsg utility requires PI to be running.

2.2.1 Available Log History

The number of files left on the system determines the amount of log history available. PI creates a new log file every day. PI keeps log files for 35 days, at which point it automatically purges them from the system. If you want to keep the log files longer than 35 days, you can back them up before PI deletes them. If necessary, you can restore the backed up files at a later date for investigation.

Note: The message log can be written (but not read) using function calls in the PI

API. It can be both read and written using the function calls in the PI SDK.

You can also view the log files from PI SMT.

2.2.2 Viewing System Messages with pigetmsg

In general, the message source is a PI subsystem, but it can be a facility within a subsystem, such as pipoint if a point database error is recorded. You can run pigetmsg in interactive or non-interactive mode.

The pigetmsg utility is located in the PI/adm directory. To get help on usage of the pigetmsg utility, type:

pigetmsg /?

Using pigetmsg in Non-Interactive Mode

When you use pigetmsg in non-interactive mode, you specify all necessary parameters on the command line when you call pigetmsg. In this mode, There are no defaults for the start time (-st), end time (-et), or maxcount (-mc) options because the utility requires that at least two of these three parameters (start time, end time, max count) be defined.

If start time and end time are specified, the utility returns messages from the start time to the end time.

(41)

2.2 - Viewing System Messages

If start time and max count are specified, the utility returns the number of messages specified by the max count beginning from the start time.

If end time and max count are specified, the utility returns the number of messages specified by the max count up to and including the end time.

If start time, end time, and max count are all specified, the utility returns messages beginning at the start time and finishing when either the number of messages specified in the max count or the end time is reached.

All the command line options for pigetmsg are listed in the following table. Argument Description

-st Start time. This should be entered in PI time format. -et End time. This should be entered in PI time format.

-mc Max count. This is an integer the total number of messages to return. -id This is an integer that represents the specific message identification number

from the text-file: 0 for the free-format messages. The default is all messages. -pn This is the message source, either a specific program name (pinetmgr) or a

wild-card mask (* for all programs, *arc* for all archive related sources, etc.). The default is all programs.

-msg A string mask selection for the message text. The default is * (show everything). -dc Number of message to display at one time. The default is to display all

messages.

Using pigetmsg in Interactive Mode

When you run pigetmsg without specifying at least two of the required parameters (-st, -et, and -mc), the pigetmsg utility goes into interactive mode. In the interactive mode, you are prompted to enter these parameters. The standard defaults for the parameters are obtained by entering a carriage return, <Enter>, after each prompt.

In the interactive mode, there is a default for the start time, end time, and max count. The default for the start time is *-15m, which is 15 minutes prior to the current time. The end time is * which is the current time and the max count default is no limit.

Searching and Sorting the Messages

To list all messages received from a specific subsystem such as the Totalizer for today, use:

pigetmsg -st t -et "*" -pn pitotal

On UNIX systems, * on the command line is expanded to perform a directory search. Thus for pigetmsg it must be specified either as \* or *. The same is true for any mask containing *.

To list the last 100 messages that have the word “error” as part of the message and then display these messages 10 at a time, use: